{tokens} resolutionA surface
Surfaces group related content. Compose your own card, panel, or dialog.
Backgrounded panel, lower visual weight than the page
A surface
Surfaces group related content. Compose your own card, panel, or dialog.
On-page card, equal weight to surrounding content
A surface
Surfaces group related content. Compose your own card, panel, or dialog.
Layer above the page (modals, popovers, overlays)
ARIA notes
A surface is a container — it has no implicit role. Add role='region' with aria-labelledby when the surface contains a labelled section. Modal surfaces add role='dialog' aria-modal='true'.
When to use Surface
Use a surface to group related content visually without imposing a layout. Three elevation variants give one canonical answer per hierarchy level.
| Variant | When to use |
|---|---|
| Subtle | Background sections — sidebars, side panels, secondary content regions |
| Base | In-flow cards — record summaries, list items with structure |
| Elevated | Above-page layers — modals, dropdowns, popovers, toasts |
Composition
Surface is a primitive — author your own card, panel, dialog by
composing the surface variant with appropriate inner spacing,
typography, and structure. The substrate does not ship a
Card component because every "card" pattern in production is
slightly different; the Surface primitive plus prose-rendering
discipline is more durable than 47 specific card variants.