The ladder

Overview

Six rungs, ordered by how much separation the surface claims from what is behind it. The first three are opaque and the last three are translucent, and that boundary between rung 2 and rung 3 is the most important line in the system, because everything above it is subject to the contrast floor and everything below it is not.

The demonstration stacks all six over a deliberately hostile photographic backdrop, with the scrim and reduced-transparency toggles live, so that the floor is something you can see rather than something this page asserts.

How it works

The six rungs

Read rows 3 and 4 twice. overlay here is the chrome that content scrolls beneath; the surface that covers the page is sheet. Two retired vocabularies used those two words the other way round, so a positional translation puts a dismissible sheet on the chrome rung and a tab bar on the sheet rung, and both compile and render. ADR 0014 settles which set wins and why: translate by job, never by ordinal.

The names are the vocabulary. Use them in design review, in commit messages, and in the rung prop on Surface. The custom properties carry the same names, so a sheet's blur is --opsin-material-sheet-blur and never --opsin-material-3-blur. A number invites arithmetic and the ladder is not arithmetic. The ordinals in the first column are the ordering and nothing addresses a rung by one.

The properties, rung by rung

Each rung resolves the same eight custom properties: --opsin-material-<rung>-tint, -tint-alpha, -blur, -saturation, -border, -shadow, -scrim and -opaque. Materials is where each of them is defined. The shape of the ladder is easier to see as a set of movements than as a table of values:

• canvas → card adds a boundary. No shadow, and in dark the backing lifts one step off the page colour. A card is a region of content, not an object.
• card → raised adds the only ordinary shadow in the system. Rung 2 is where a surface becomes an object that is temporarily above the page.
• raised → sheet is the boundary. The backing gains an alpha, a blur appears, the saturation is lifted above 1 to compensate for the desaturation the blur causes, and the border becomes a hairline expressed in alpha rather than a solid neutral. The shadow shrinks almost to nothing, because a sheet's separation comes from the blur.
• sheet → overlay lowers the alpha, raises the blur and the saturation further, and brings back a large soft shadow. It is the thinnest material in the system and therefore the one whose contrast floor is hardest to hold.
• overlay → scrim is a different kind of thing entirely: scrim is a dark wash with almost no blur, whose job is to remove information rather than to present any.

Exact resolved values are in the generated table below, in both themes. They are not repeated in prose anywhere on this site, because a value in prose is a value that will be wrong after the next regeneration.

Blur, tint, saturation and vibrancy

Four things are commonly bundled into "frosted glass". opsinjs uses three of them, each for a stated reason, and deliberately declines the fourth.

Tint is used. The backing colour and its alpha. This is the safety parameter: it is what bounds the composite and therefore what makes contrast measurable. See The contrast floor.

Blur is used, for a narrow reason. backdrop-filter: blur() removes high spatial frequency from what is behind the surface. It takes the texture out of a photograph so that glyph edges are not competing with edges behind them. It does not meaningfully change the local mean luminance, so it does not fix contrast, and it is never traded against tint.

Saturation boost is used, on two rungs only. Boosting the saturation of the backdrop is what gives platform materials their characteristic liveliness, and here it does a narrower job: a large blur desaturates whatever is behind it, so without a boost sheet and overlay look grey rather than translucent. It is a per-rung token and the other four rungs sit at 1, the identity, so a boost is something a rung declares rather than something the ladder does everywhere.

Vibrancy is not used. Platform vibrancy blends the foreground text with the backdrop as well, which is a beautiful effect and an unbounded contrast liability. Text on an opsinjs material is opaque, always.

Browser support, honestly

backdrop-filter: blur() is safe to use everywhere a modern browser runs, and has been for years. Two caveats that are still real:

• Older Safari needs the -webkit- prefix, which costs one line and is emitted.
• backdrop-filter with an SVG filter reference is a Chromium-only capability, with the syntax backdrop-filter: url(#something). Nothing in this ladder uses it, and nothing in this ladder ever will, because a rung that only exists in one engine is not a rung.

Where backdrop-filter is unavailable entirely, rungs 3, 4 and 5 land on their opaque fallbacks, which are the same fallbacks that reduced transparency and print use. That path is exercised by real readers, not just by a feature query, so it is designed rather than tolerated.

Using it

Say the rung's name. A design review conversation that contains "make it a bit more glassy" produces a screen with four different alphas. One that contains "that should be overlay, not sheet" produces a screen with two.

The boundary between rung 2 and rung 3 is a decision, not a gradient. Ask what is behind the surface and whether the reader still needs it: a surface that covers the page while leaving it recognisable is sheet, chrome that content passes beneath is overlay, and anything else that needs to look lifted is raised, opaque, with a shadow. There is no half-translucent card.

A toast is raised, not overlay. A toast appears over arbitrary content it knows nothing about, frequently over a photograph or a chart, and it usually carries a message that matters. It must not depend on what is behind it, so it is opaque.

A scrim never appears alone. A scrim exists to isolate a sheet. A dimmed screen with nothing on top of it is a loading state pretending to be a modal.

Do not add a rung. If a surface does not fit one of the six, the usual cause is that it is trying to be two things: a card that is also chrome, a sheet that is also a page. Splitting it is almost always the right fix; the intake process for a genuine seventh rung is in Contributing tokens.

Tokens

Accessibility impact

The opaque rungs (0, 1, 2) carry the ordinary obligation. Their backgrounds are known colours, so text on them is measured exactly as any other pair is. See Contrast and APCA.

The translucent rungs (3, 4, 5) carry a stronger one. Their rendered colour depends on the backdrop, so they are measured against the worst-case composite rather than against their nominal tint: the rung's tint at its own alpha over a pure-black and a pure-white backdrop, in both themes. Where a rung clears the floor at both extremes it is safe over imagery and video; where it does not the report below records the shortfall rather than hiding it. The calculation is The contrast floor.

Borders are not measured yet. A hairline at low alpha over a translucent rung is the most commonly missed non-text contrast failure (SC 1.4.11), because it looks correct on the one backdrop the designer tested, and nothing on this site has measured one. It is an open gap, named here rather than implied by a table that does not hold the row. Material tokens states the same.

The fallback path is a first-class path. Reduced transparency is not a degraded experience. The rung keeps its border, its shadow and its position, and only its translucency changes, so nothing moves and nothing is lost. Reduced transparency states it rung by rung.

Related

• Choosing a layer has the decision table from surface kind to rung, plus the nesting rules.
• The contrast floor explains why rungs 3, 4 and 5 have the alphas they have.
• Layering and elevation has the z-index contract, which the ladder correlates with but does not define.