Skip to content
opsinjs
Edit this page

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.

Backdrop
  • 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

RungOpaqueIts job
canvasYesThe page itself
cardYesA bounded piece of content, lifted by a soft drop over a decorative edge. The default home for a health value
raisedYesAbove the page without covering it: a menu, popover, tooltip or toast
sheetNoCovers the page and leaves it recognisable: a bottom sheet, side panel or modal
overlayNoChrome that content scrolls beneath, such as a tab bar
scrimNoThe 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

  1. Does content scroll under it? It is overlay.
  2. Does it cover the page, so what is behind is unusable? It is sheet, over a scrim.
  3. Otherwise it is raised if it appears and is dismissed, card if it is a bounded part of the page, or else canvas.
  • 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 card or raised.
  • Show one sheet at a time. Its scrim is a sibling, never a child, and overlay chrome 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 overlay summary 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-xl and opacity on 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 written yet.

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.

Not written yet.

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 sheet does not do for you. Never stack modals, and never let a toast take focus.
  • critical is 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.

This table has not been generated. It is produced by 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

TokenWhat it controlsUsed 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-alpha1Rung 0 (canvas): how opaque that tint is.surface
--opsin-material-canvas-blur0pxRung 0 (canvas): backdrop blur radius.surface
--opsin-material-canvas-saturation1Rung 0 (canvas): backdrop saturation multiplier.surface
--opsin-material-canvas-bordernoneRung 0 (canvas): the boundary.surface
--opsin-material-canvas-shadownoneRung 0 (canvas): the shadow that separates it from what is behind.surface
--opsin-material-canvas-scrim0Rung 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-alpha1Rung 0.5 (inset): how opaque that tint is.surface
--opsin-material-inset-blur0pxRung 0.5 (inset): backdrop blur radius.surface
--opsin-material-inset-saturation1Rung 0.5 (inset): backdrop saturation multiplier.surface
--opsin-material-inset-bordernoneRung 0.5 (inset): the boundary.surface
--opsin-material-inset-shadownoneRung 0.5 (inset): the shadow that separates it from what is behind.surface
--opsin-material-inset-scrim0Rung 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-alpha1Rung 1 (card): how opaque that tint is.surface
--opsin-material-card-blur0pxRung 1 (card): backdrop blur radius.surface
--opsin-material-card-saturation1Rung 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-scrim0Rung 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-alpha1Rung 2 (raised): how opaque that tint is.surface
--opsin-material-raised-blur0pxRung 2 (raised): backdrop blur radius.surface
--opsin-material-raised-saturation1Rung 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-scrim0Rung 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.93Rung 3 (sheet): how opaque that tint is.surface
--opsin-material-sheet-blur20pxRung 3 (sheet): backdrop blur radius.surface
--opsin-material-sheet-saturation1.6Rung 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.93Rung 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.74Rung 4 (overlay): how opaque that tint is.surface
--opsin-material-overlay-blur16pxRung 4 (overlay): backdrop blur radius.surface
--opsin-material-overlay-saturation1.8Rung 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.74Rung 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.44Rung 5 (scrim): how opaque that tint is.surface
--opsin-material-scrim-blur2pxRung 5 (scrim): backdrop blur radius.surface
--opsin-material-scrim-saturation1Rung 5 (scrim): backdrop saturation multiplier.surface
--opsin-material-scrim-bordernoneRung 5 (scrim): the boundary.surface
--opsin-material-scrim-shadownoneRung 5 (scrim): the shadow that separates it from what is behind.surface
--opsin-material-scrim-scrim0.44Rung 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