Surface Atom
Every raised or tinted panel in the library is a Surface. Its variants are where glass and gradients live, so those looks are a choice a screen makes rather than an identity baked into the brand. Glass is deliberately selective: it marks a control or navigation layer above content, not every card on a dashboard.
Anatomy
A Surface is a box with four independent decisions: variant (how it is filled), tone or hue (what colour it leans on), elevation (how far off the page it sits), and radius / padding (both token steps, never free values).
plain
tinted · violet
tinted · success
glass · regular
glass · clear
gradient · blue
<Surface variant="tinted" hue="violet" padding="md"><Text>Tinted card</Text></Surface>Tone versus hue
tone is semantic — it means something (success, danger). hue is decorative — it means
nothing, and exists because a dashboard of six tiles reads better in six colours. Never use tone
to get a colour you liked; that is what hue is for.
danger · means failure
teal · means nothing
<Surface variant="tinted" tone="danger">Payment failed</Surface><Surface variant="tinted" hue="teal">Storage</Surface>Do
Reach for hue when the colour is only there to tell tiles apart.
Don't
Use tone='danger' because the red looked good — a screen reader user gets no colour, and the next reader believes something is wrong.
Glass as a material
Glass needs visible content behind it. Its translucent fill, specular light, edge illumination, backdrop blur, and grounding shadow work together as one Skin-controlled material. Browsers without backdrop filtering, reduced-transparency preferences, increased contrast, and forced-colour modes receive a legible opaque surface automatically.
Use glass for a small control, toolbar, navigation, or overlay plane above content. Keep ordinary
content on plain or tinted surfaces, and never stack glass inside glass. See the
Glass control center for the material over a useful backdrop.
regular is the default because it holds separation and legibility across more backdrops. Use
clear only for a compact control over visually rich content when its label or glyph is bold enough
to remain legible. It intentionally becomes the same opaque fallback as regular glass when someone
requests reduced transparency or increased contrast.
Do
Place one glass control plane over content with enough colour or detail to reveal the material.
Don't
Turn every card into glass or nest glass surfaces — the page loses hierarchy and contrast.
Elevation
none
sm
md
lg
<Surface elevation="lg" padding="md">Floating</Surface>Props
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | 'plain' | 'tinted' | 'glass' | 'gradient' | 'plain' | How the panel is filled. Glass blurs what is behind it, so it needs something behind it. |
| glassStyle | 'regular' | 'clear' | 'regular' | Glass density. Clear is reserved for compact, bold controls over visually rich content. |
| tone | 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'danger' | 'neutral' | Semantic colour for tinted and gradient. |
| hue | 'violet' | 'blue' | 'teal' | 'green' | 'amber' | 'rose' | — | Decorative colour. Wins over tone when both are given. |
| elevation | 'none' | 'sm' | 'md' | 'lg' | 'sm' | Shadow step. |
| radius | 'sm' | 'md' | 'lg' | 'xl' | 'lg' | Corner token. |
| padding | 'none' | 'sm' | 'md' | 'lg' | 'md' | Inner spacing token. |
| bordered | boolean | true | Hairline border. Glass keeps its own border colour. |
| asSection | boolean | false | Renders a <section> for a landmark region. |
Tokens read
--cb-surface, --cb-border, --cb-tint-strength, --cb-glass-*, --cb-gradient-angle,
--cb-shadow-*, --cb-radius-*, --cb-space-*.