Foundations
Elevation
Nothing rises. Four shadow tokens exist to make sure of it.
There is no elevation ramp, and the four tokens named after one are there to neutralise it. --shadow-sm, --shadow and --shadow-lg all resolve to none, and --shadow-color to transparent. That is not an oversight waiting to be filled in: a component ported from a shadowed system keeps its shadow class, draws nothing, and stays flat, which is the entire point of declaring them. Law 2 — a box-shadow is never blurred — is enforced by the values rather than by a reviewer.
The one depth cue the system does own is --lift: 3px 3px 0 0 var(--shadow-offset), a hard ink offset with no blur at all, and --lift-sm at 2px. --shadow-offset points at --clay, so the offset is the accent rather than a grey and it re-points when the accent does. Worth knowing before you reach for it: no component in the package uses either one — there is not a single shadow-(--lift) in the library. It is published as the sanctioned idiom for a consumer building a plate of their own, not as something the library leans on.
What the library actually separates with is three things, in this order. A hairline: --rule between rows, --rule-2 around a box. A change of ground: --paper, --paper-2, --stone, three steps and no fourth. And reversal, which is what Card variant="plate" reaches for — it fills with the one reversed surface and carries its own title colour, because a hardcoded ink title on a reversed plate came out at 1.25:1 and was invisible on the one variant whose whole job is to look different. Use at most one plate per screen; two of them is a page with no ground left.
Height and stacking are separate questions here, and only the second one is real. Seven ranks — --z-rule at 1 through --z-toast at 300 — say what sits over what, and none of them implies a shadow, because there is none to cast. A surface’s rank is decided by what it has to survive: a dropdown has to clear a sticky header, a scrim has to cover the dropdown, a modal has to sit on the scrim, and a toast has to be visible over a modal that is asking a question. The ladder itself is tabled on Space & shape rather than repeated here.
Two of the seven have component-facing aliases in the semantic layer, --z-dropdown and --z-overlay. Reach for those from a component and for the primitive ranks only when you are placing something the system has no name for.
Read nextColourSpace & shape
Depth
Four of these resolve to nothing, on purpose. --lift and --lift-sm are the offsets that replace the ramp — currently used by no component in the package, and published for consumers rather than consumed here.
| Sample | Token | Value | Dark | Notes |
|---|---|---|---|---|
--shadow-offset | var(--clay) | var(--clay) | — | |
--shadow-color | transparent | ─── Depth ──────────────────────────────────────────────────────────── Law 2 — a box-shadow is never blurred. The system has no elevation ramp; depth is a hard offset in ink, applied per component. These three resolve to nothing on purpose, so a component ported from a shadowed system stays flat instead of drawing a blur the White Reset does not have. Reach for --lift instead, which is the offset idiom expressed once. | ||
--shadow-sm | none | — | ||
--shadow | none | — | ||
--shadow-lg | none | — | ||
--lift | 3px 3px 0 0 var(--shadow-offset) | The one depth cue the system does have: a hard 3px ink offset, no blur. Used by a plate that must read as sitting above the page. | ||
--lift-sm | 2px 2px 0 0 var(--shadow-offset) | — | ||
--disabled-opacity | 0.5 | — |