surface

The surface component is Cedar's highly flexible container which acts as a foundational layer for grouping content and interactive elements. It provides designers and developers with a broad set of styling and layout options to customize aspects like elevation, background, borders, and layout flexibility.

Use surface as a starting point for constructing more specific components such as cards, tiles, and action-driven elements. As a building block, it can adapt to various use cases.

While surface offers a wide range of customization options, make sure to use its specialized variants first whenever appropriate. These variants are built on surface's root pattern but include built-in design decisions for specific use cases, like selection, navigation, and actions.

• Surfaces are solid: They represent tangible layers in the visual hierarchy and do not pass through or overlap one another in terms of elevation
• Surfaces are nestable: You can nest surfaces within one another to create complex layouts, but they maintain their individual properties such as elevation and background
• Surfaces are draggable: You can make surfaces draggable to enable user interaction (e.g., for sortable grids or modifiable UI layouts)
• Surfaces are clickable: With the appropriate child components, surfaces can act as clickable zones, but it's important to define these interactions clearly using the correct components (e.g., surface navigation or surface controls)
• Surfaces do not elevate through other surfaces: Surfaces maintain their position in the visual hierarchy, respecting the elevation levels of surrounding elements
• Surfaces maintain separation: Surfaces are designed to keep content separated visually, ensuring clear distinctions between layered UI elements

• Start with surface when necessary, but first seek more specialized components to fit the interaction pattern you need. Surface provides the most flexibility but is not opinionated about its use. This makes it less suitable for cases requiring clear interaction models
• Use interaction-specific variants whenever possible. Variants like surface selection and surface navigation are optimized for their use cases and ensure consistent behavior across Cedar interfaces
• Keep surface for visual-only use cases when no interaction is required. Surface is perfect for cases where you need to manage elevation, background layers, or borders without any interaction

Surface selection acts as a variation of a checkbox/radio. It's used to build components where selection is the primary user interaction. It provides specialized styles and behavior for checked, disabled, and active states.

Components using surface selection:

Fulfillment tile: Displays a composed selection option and provides feedback with optional icons

Usage

Surface navigation is a specialized variant designed for navigational elements. It provides comprehensive state management for different interaction states (rest, hover, active, focused, and disabled), allowing for fine-grained control over the component's appearance in each state.

What Cedar provides

Each variant of surface is designed to provide accessible interaction patterns, not just visual compliance:

• Surface selection includes ARIA attributes and communicates states like disabled and checked effectively to assistive technologies
• Surface navigation provides clear keyboard navigation, so focus and hover states are distinct and accessible
• Surface controls (coming soon) ensures focus and press states are highly visible, providing clear interaction feedback to all users, including those with disabilities

Development responsibilities

When using surface as a fallback, implement the appropriate ARIA roles. Also ensure keyboard and screen reader accessibility where relevant.

Surface selection

When using the Surface selection component, here's what you are responsible for:

• Always group within a radio group if used with a radio role. The group should be properly labled (see implementation).
• Ensure the content within the component has text, which may be screen reader only. Alternatively, provide an aria-labelledby attribute to link a label
• Add a tabindex="0" prop when appropriate (most of the time this is true)

Surface navigation

When using the Surface navigation component, here's what you are responsible for:

• Ensure proper semantic HTML is used within the component (typically using anchor tags for navigation)
• Provide clear, descriptive text for the navigation destination
• Maintain sufficient color contrast in all interaction states (rest, hover, active, focused, disabled)
• Test keyboard navigation to ensure focus states are clearly visible
• Consider adding aria-current attributes when appropriate to indicate the current page or section

General surface as a fallback

<CdrSurface> 
  <CdrBody>This is a default surface</CdrBody> 
</CdrSurface>

Radio

Use the Surface selection component within a radio group and include a label.

<div id="radio-label">
  How would you like to receieve your order?
</div>
<div
  role="radiogroup"
  aria-labelledby="radio-label"
>
  <CdrSurfaceSelection
    tabindex="0"
    role="radio"
    :checked="orderPreference === 'pickup'"
    @click="orderPreference = 'pickup'"
  >
    <CdrText>Pick up</CdrText>
    <IconCheckFill v-if="orderPreference === 'pickup'" />
  </CdrSurfaceSelection>
  ...
</div>

Checkbox

Use the Surface Selection component as a checkbox. If the content inside does not provide an adequate description, then include a label.

<div id="gift-wrapped-label">
  Would you like your order gift wrapped?
</div>
<CdrSurfaceSelection
  tabindex="0"
  role="checkbox"
  :checked="giftWrapped"
  aria-labelledby="gift-wrapped-label"
  @click="giftWrapped = !giftWrapped"
>
  <CdrText>Gift wrap</CdrText>
  <IconCheckFill v-if="giftWrapped" />
</CdrSurfaceSelection>

Card

Use the Surface Navigation component as a card and the Surface Navigation Link component as a card link.

<CdrSurfaceNavigation v-bind="props" class="card">
  <CdrSurfaceNavigationLink href="#">
    Link
  </CdrSurfaceNavigationLink>
</CdrSurfaceNavigation>

When using CdrSurface or CdrSurfaceSelection in a TypeScript application, we recommend importing the surface or surfaceSelection interface, respectively, from the library. These interfaces allow typed options passed to the component.

ParentComponent.vue

<script setup lang="ts">
import {
  CdrSurface
  CdrSurfaceSelection,
  type surface,
  type surfaceSelection
} from '@rei/cedar'

const surfaceExample: surface = {
  background: 'secondary',
  withBorder: true,
};

const surfaceSelectionExample: surfaceSelection = {
  checked: false,
  modifier: 'primary',
  role: 'checkbox',
  loading: false,
  disabled: true,
};

</script>

<template>
  <main>
    <CdrSurface v-bind="surfaceExample">
      <CdrSurfaceSelection v-bind="surfaceSelectionExample">
        ...
      </CdrSurfaceSelection>
    </CdrSurface>
  </main>
</template>