Foundations
Materials
The six named rungs that say what a surface is made of, and the contrast floor every translucent rung must clear.
A material says what a surface is made of and what shows through it. The six rungs form an ordered ladder, not a palette, and translucency starts at sheet.
0Canvas
What is the page itself?
The application background. Nothing is behind it, so nothing shows through it.
1Card
Is this a distinct piece of content on the page?
A grouped block of related values, such as a result or a day's readings. Opaque, bordered, no shadow. The workhorse.
2Raised
Is this temporarily above the page, but not covering it?
A card that has been lifted: a selected row, a dragged tile, a result being acted on.
3Sheet
Is this covering the page while leaving it recognisable underneath?
A bottom sheet or side panel the reader can dismiss. The blur keeps enough of the page visible that they know where they will return to.
4Overlay
Is this chrome floating over scrolling content?
A sticky header, a filter bar, a popover. The rung most often misused for content that has to stay readable.
5Scrim
Am I trying to make everything behind this unusable on purpose?
The dimming layer behind a modal. Its job is to remove the page, not to be looked at.
The backdrop is generated in CSS, not photographed, so it is the same worst case on every machine. Measured contrast for these pairs is published by pnpm run contrast on foundations/materials/the-contrast-floor. This specimen shows you the problem, and that page gives you the numbers.
The ladder
| Rung | Opaque | Its job |
|---|---|---|
canvas | Yes | The page itself |
card | Yes | A bounded piece of content, lifted by a soft drop over a decorative edge. The default home for a health value |
raised | Yes | Above the page without covering it: a menu, popover, tooltip or toast |
sheet | No | Covers the page and leaves it recognisable: a bottom sheet, side panel or modal |
overlay | No | Chrome that content scrolls beneath, such as a tab bar |
scrim | No | The dimming behind a sheet |
Rung names are token names, so a sheet's blur is --opsin-material-sheet-blur, never a number. Each rung resolves eight properties: -tint, -tint-alpha, -blur, -saturation, -border, -shadow, -scrim and -opaque. People swap overlay and sheet, so translate by job, never by position. The token-only inset rung is the recessed well that Callout and RangeBar draw inside a card.
Surface applies all eight together. In your own CSS, that is your job.
<Surface rung="sheet">Everything the surface holds</Surface>Choosing a rung
- Does content scroll under it? It is
overlay. - Does it cover the page, so what is behind is unusable? It is
sheet, over ascrim. - Otherwise it is
raisedif it appears and is dismissed,cardif it is a bounded part of the page, or elsecanvas.
- Pick the lowest rung that works. A rung shows depth, never importance or two colour axes.
- Never nest translucent rungs. A card inside a sheet is
cardorraised. - Show one
sheetat a time. Itsscrimis a sibling, never a child, andoverlaychrome dims under it. - Never add a shadow of your own. A rung brings its drop, a line of light along its top edge and its edge together, so a card and a menu are lifted by the system rather than by a component.
- A health value sits on an opaque rung, unless a sticky
overlaysummary repeats a value shown opaquely on the same screen.
The contrast floor
Every translucent rung has a minimum backing tint, chosen so that text on it clears the contrast floor against the worst possible backdrop. The composite is α × tint + (1 − α) × backdrop, so the tint over black and over white bound every case, and scripts/check-contrast.mts measures text against both in both themes. Contrast records each result, and today's one shortfall is overlay over a light backdrop in the dark theme.
- Never author alpha inline. That includes
bg-white/70 backdrop-blur-xlandopacityon a container, which makes the text translucent too. - Blur removes texture, not brightness, so it is never traded against tint.
- Text never sits directly on an image. Put it on a translucent rung or a scrim, and ramp a gradient scrim to full opacity before the first baseline.
Not yet measured: borders on translucent rungs as non-text pairs, the saturation boost on sheet and overlay, and anything in Display-P3. contrast:verify fails a below-floor result nightly, not on the pull request.
Reduced transparency
Under prefers-reduced-transparency: reduce, sheet and overlay become the opaque card colour with no blur, and scrim grows more opaque. Borders, shadows and layout stay put, and a browser without backdrop-filter gets the same fallback. Not every browser forwards the preference, so a product may offer its own setting. Surface alone answers prefers-contrast: more and forced-colors: active, in part, and forced colours still loses the scrim's dimming.
Performance budget
At most three translucent surfaces may show at once, and overlay, scrim and sheet together is the designed worst case. Never give a repeating element a translucent rung, never set will-change: backdrop-filter, and never animate the blur radius. Over budget, shrink or drop the surface, never the alpha.
The budget of three is an engineering judgement. No device-lab frame-time measurement backs it yet.
Layering
Layer decides which surface is in front, so a modal sits above a card because of its layer, not its blur. Each layer renders into a portal at the document root, in the order base, sticky, raised, overlay, scrim, modal, notify and critical. Layer names are not rung names.
- Never cover the value a surface is about. A sheet opened from a result keeps the result visible above its edge, or restates it.
- A modal traps focus, makes the page inert and returns focus to its trigger, which choosing
sheetdoes not do for you. Never stack modals, and never let a toast take focus. criticalis reserved for an escalation the product's clinical governance says must never be covered. See High-stakes moments.
The proposed --opsin-layer-<name> tokens are not generated yet.
scripts/build-tokens.mts. Run pnpm run generate and reload.Nothing on this site types a measured number by hand, so an ungenerated table shows this rather than an example.
Tokens
| Token | What it controls | Used by |
|---|---|---|
| --opsin-material-canvas-tintvar(--opsin-neutral-0) | Rung 0 (canvas): the tint over what is behind it. The application background. Nothing is behind it, so nothing shows through it. | surface |
| --opsin-material-canvas-tint-alpha1 | Rung 0 (canvas): how opaque that tint is. | surface |
| --opsin-material-canvas-blur0px | Rung 0 (canvas): backdrop blur radius. | surface |
| --opsin-material-canvas-saturation1 | Rung 0 (canvas): backdrop saturation multiplier. | surface |
| --opsin-material-canvas-bordernone | Rung 0 (canvas): the boundary. | surface |
| --opsin-material-canvas-shadownone | Rung 0 (canvas): the shadow that separates it from what is behind. | surface |
| --opsin-material-canvas-scrim0 | Rung 0 (canvas): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-canvas-opaquevar(--opsin-neutral-0) | Rung 0 (canvas): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |
| --opsin-material-inset-tintvar(--opsin-neutral-100) | Rung 0.5 (inset): the tint over what is behind it. The recessed well inside a card: the explanatory note a Callout draws inside the reading it annotates, and the track a RangeBar lays its range along. Its fill sits below the card fill in both themes, so the well reads as carved into the card rather than lifted off it. In light it is neutral-100, one step under the white card, which is where a Callout already sat. In dark it is a value between the page and the card, below the card so the well is a recess and above the page so a Callout used on its own is still visible. | callout, range-bar, range-legend, surface |
| --opsin-material-inset-tint-alpha1 | Rung 0.5 (inset): how opaque that tint is. | surface |
| --opsin-material-inset-blur0px | Rung 0.5 (inset): backdrop blur radius. | surface |
| --opsin-material-inset-saturation1 | Rung 0.5 (inset): backdrop saturation multiplier. | surface |
| --opsin-material-inset-bordernone | Rung 0.5 (inset): the boundary. | surface |
| --opsin-material-inset-shadownone | Rung 0.5 (inset): the shadow that separates it from what is behind. | surface |
| --opsin-material-inset-scrim0 | Rung 0.5 (inset): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-inset-opaquevar(--opsin-neutral-100) | Rung 0.5 (inset): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |
| --opsin-material-card-tintvar(--opsin-neutral-0) | Rung 1 (card): the tint over what is behind it. The default home for a health value. Opaque, edged by a decorative line, and lifted off the page by a soft drop and a line of light along its top. The rung every ResultCard, MetricTile and RangeBar sits on. | surface |
| --opsin-material-card-tint-alpha1 | Rung 1 (card): how opaque that tint is. | surface |
| --opsin-material-card-blur0px | Rung 1 (card): backdrop blur radius. | surface |
| --opsin-material-card-saturation1 | Rung 1 (card): backdrop saturation multiplier. | surface |
| --opsin-material-card-bordervar(--opsin-chrome-edge) | Rung 1 (card): the boundary. | surface |
| --opsin-material-card-shadowinset 0 1px 0 0 oklch(1 0 0 / 0.7), 0 1px 2px 0 oklch(0.205 0.006 250 / 0.05), 0 10px 30px -14px oklch(0.205 0.006 250 / 0.16) | Rung 1 (card): the shadow that separates it from what is behind. | accordion, body-map, button, care-card, combobox, menu, popover, questionnaire, range-bar, range-legend, result-card, scale-input, scroll-area, segmented-control, select, slider, stepper, surface, switch, toast, tooltip |
| --opsin-material-card-scrim0 | Rung 1 (card): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-card-opaquevar(--opsin-neutral-0) | Rung 1 (card): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |
| --opsin-material-raised-tintvar(--opsin-neutral-0) | Rung 2 (raised): the tint over what is behind it. Menus, popovers, tooltips, a dragged card. Still opaque: the shadow, not translucency, is what says 'above'. | surface |
| --opsin-material-raised-tint-alpha1 | Rung 2 (raised): how opaque that tint is. | surface |
| --opsin-material-raised-blur0px | Rung 2 (raised): backdrop blur radius. | surface |
| --opsin-material-raised-saturation1 | Rung 2 (raised): backdrop saturation multiplier. | surface |
| --opsin-material-raised-bordervar(--opsin-chrome-edge) | Rung 2 (raised): the boundary. | surface |
| --opsin-material-raised-shadowinset 0 1px 0 0 oklch(1 0 0 / 0.8), 0 2px 8px -2px oklch(0.205 0.006 250 / 0.08), 0 22px 52px -20px oklch(0.205 0.006 250 / 0.28) | Rung 2 (raised): the shadow that separates it from what is behind. | combobox, menu, popover, select, surface, toast, tooltip |
| --opsin-material-raised-scrim0 | Rung 2 (raised): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-raised-opaquevar(--opsin-neutral-0) | Rung 2 (raised): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |
| --opsin-material-sheet-tintvar(--opsin-neutral-0) | Rung 3 (sheet): the tint over what is behind it. A bottom sheet or side panel the reader can dismiss by dragging. Its tint is now near opaque, so the panel lands close to the card colour and a white control inside it no longer floats above a greyer surface. What keeps the covered page recognisable is the scrim around the panel rather than the page reading through the panel, because at this opacity very little of the page shows through the tint. | surface |
| --opsin-material-sheet-tint-alpha0.93 | Rung 3 (sheet): how opaque that tint is. | surface |
| --opsin-material-sheet-blur20px | Rung 3 (sheet): backdrop blur radius. | surface |
| --opsin-material-sheet-saturation1.6 | Rung 3 (sheet): backdrop saturation multiplier. | surface |
| --opsin-material-sheet-bordervar(--opsin-chrome-edge) | Rung 3 (sheet): the boundary. | surface |
| --opsin-material-sheet-shadowinset 0 1px 0 0 oklch(1 0 0 / 0.8), 0 4px 12px -4px oklch(0.205 0.006 250 / 0.1), 0 40px 96px -28px oklch(0.205 0.006 250 / 0.38) | Rung 3 (sheet): the shadow that separates it from what is behind. | sheet, surface |
| --opsin-material-sheet-scrim0.93 | Rung 3 (sheet): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-sheet-opaquevar(--opsin-neutral-0) | Rung 3 (sheet): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |
| --opsin-material-overlay-tintvar(--opsin-neutral-0) | Rung 4 (overlay): the tint over what is behind it. A pinned toolbar, a tab bar and a floating action bar are all chrome that content scrolls beneath. | surface |
| --opsin-material-overlay-tint-alpha0.74 | Rung 4 (overlay): how opaque that tint is. | surface |
| --opsin-material-overlay-blur16px | Rung 4 (overlay): backdrop blur radius. | surface |
| --opsin-material-overlay-saturation1.8 | Rung 4 (overlay): backdrop saturation multiplier. | surface |
| --opsin-material-overlay-bordervar(--opsin-chrome-edge) | Rung 4 (overlay): the boundary. | surface |
| --opsin-material-overlay-shadowinset 0 1px 0 0 oklch(1 0 0 / 0.55), 0 1px 2px 0 oklch(0.205 0.006 250 / 0.05), 0 12px 32px -14px oklch(0.205 0.006 250 / 0.2) | Rung 4 (overlay): the shadow that separates it from what is behind. | surface |
| --opsin-material-overlay-scrim0.74 | Rung 4 (overlay): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-overlay-opaquevar(--opsin-neutral-0) | Rung 4 (overlay): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |
| --opsin-material-scrim-tintvar(--opsin-neutral-950) | Rung 5 (scrim): the tint over what is behind it. The dimming layer behind a modal dialog or a consent sheet. Its job is to remove the page from consideration, not to look like glass. | surface |
| --opsin-material-scrim-tint-alpha0.44 | Rung 5 (scrim): how opaque that tint is. | surface |
| --opsin-material-scrim-blur2px | Rung 5 (scrim): backdrop blur radius. | surface |
| --opsin-material-scrim-saturation1 | Rung 5 (scrim): backdrop saturation multiplier. | surface |
| --opsin-material-scrim-bordernone | Rung 5 (scrim): the boundary. | surface |
| --opsin-material-scrim-shadownone | Rung 5 (scrim): the shadow that separates it from what is behind. | surface |
| --opsin-material-scrim-scrim0.44 | Rung 5 (scrim): the minimum scrim opacity needed for text on this rung to clear the contrast floor. | surface |
| --opsin-material-scrim-opaqueoklch(0.205 0.006 250 / 0.72) | Rung 5 (scrim): the opaque substitute used under prefers-reduced-transparency and where backdrop-filter is unsupported. | surface |