General
OnSurface
Sets the surface tone (`light` / `dark` / `bright`) for descendant components and rebinds the matching CSS custom properties.
Overview
<OnSurface> is the only component that sets the surface tone publicly. It wraps a slot, applies the appropriate .on-light, .on-dark, or .on-bright class, and exposes the tone to descendants via context so any Text, Icon, or chrome component inside resolves to the right colors. A bare <OnSurface> (no tone prop) inherits from the surrounding tone, which makes wrapping safe and idempotent.
For the conceptual treatment of SurfaceTone, the useSurfaceTone() composable, and the colorToSurfaceTone helper, see Surface Tone.
Key Business & UX Benefits
- One wrapper guarantees text and icons stay legible inside any colored section, eliminating the WCAG contrast issues that surface in QA right before launch.
- Idempotent wrapping means designers can nest sections freely without each one needing manual tone configuration.
- Decouples component color from the surrounding background, so the same
CardorTextrenders correctly on light, dark, and bright surfaces.
Usage
Light tone
OnSurface Light
<OnSurface tone="light">
<Text>Light surface, black text by default.</Text>
</OnSurface>
Dark tone
OnSurface Dark
<OnSurface tone="dark">
<Text>Dark surface, white text by default.</Text>
</OnSurface>
Feature List
- Three `tone` values ('light', 'dark', 'bright') apply `.on-light`, `.on-dark`, or `.on-bright` and rebind the matching CSS custom properties
- Bare `<OnSurface>` (no `tone` prop) inherits the surrounding tone, keeping wrapping idempotent and safe to nest
- Publishes the tone to descendants via Vue provide so any Text, Icon, or chrome inside resolves to the right colors
- Pairs with `useSurfaceTone()` so component code reads the tone without prop-drilling through the tree
- Single public surface for tone, so QA can audit contrast at the boundary rather than per-component
API Reference
| Prop | Default | Type |
|---|---|---|
as | div | string | Component |
asChild | false | boolean |
tone | SurfaceTone ("dark" | "light" | "bright") |
| Slot | Type |
|---|---|
default | {} |