Surface

Guidelines React

The Surface component is an engineering-only primitive that applies consistent elevation (box-shadow and background tokens) to containers for visual depth and hierarchy. It is not intended for direct design specification and exists as a quality-of-life tool for engineers to ensure token usage remains uniform.

When to use

• Wrap containers needing standardized depth (e.g., cards, modals, panels) to automatically apply the correct elevation background and shadow tokens.
• Maintain consistency across implementations without manual token referencing.
• Compose with other components where layered hierarchy is required.

Common Patterns

• Card or panel wrapper: Apply raised elevation for content lifted above page background.
• Modal or popover: Use overlay elevation for floating, blocking layers.
• Inset elements: Sunken for recessed areas like content wells.

When NOT to use

• For user-facing design decisions; reference elevation guidelines.
• When no depth is needed (prefer plain containers with background tokens).
• For interactive controls; elevation is visual only.

Variants

Variant	Description	Recommended Context
Sunken	Inset appearance	Recessed areas, wells
Default	Flat, no elevation	Base page content, primary surfaces
Raised	Moderate lift	Cards, floating elements
Overlay	Prominent floating layer	Modals, drawers, popovers, contextual help

Properties

Anatomy

Element	Description
Container	Wrapper element applying elevation background and shadow tokens.
Children	Content placed within the surface (inherits elevation styling).

Accessibility

• Surface adds no interactivity; accessibility inherits from child content.
• Ensure applied shadows and backgrounds maintain sufficient contrast (≥4.5:1) for text and controls.
• Test in high-contrast and forced-colors modes; shadows may be overridden by system settings.

Support standard keyboard navigation Not applicable (Surface is non-interactive; keyboard behavior inherits from children).