Elevation
Two systems work together to build depth: soft shadows imply lift off the surface, and a fixed z-index ladder keeps overlapping layers in a predictable stacking order.
Shadows
Deliberately soft and low-contrast — elevation should be felt, not seen. --elevation-* is the full public surface: these six tokens are the shadows, assembled from the tier-1 axes below. Components read these and nothing else.
Hover is not a rung. Every rung names a kind of surface; a hover lift moves an element one rung up from wherever it rests. Rung 3 used to be described as “raised cards, hover state,” and being the only rung that named an interaction is why it became the drawer everything lifted got thrown into — six dropdown surfaces sat on it instead of rung 4.
--elevation-1 step 050 Resting lift — always-visible surfaces --elevation-2 step 100 Cards, list items --elevation-3 step 200 Raised cards; resting rung for unanchored floating controls --elevation-4 step 300 Dropdowns, popovers, menus, tooltips, toasts --elevation-5 step 400 Modals, dialogs --elevation-6 step 500 Full-screen overlays — command palette, entity search Shadow axes
The tier-1 material each role clusters. A box-shadow has four axes plus a colour, and splitting them is what makes a shadow themeable — re-point --shadow-color-* and every elevation retints. --shadow-offset-x is a single shared token, not a ramp, because every shadow in the kit casts straight down.
| Step | offset-y | blur | spread | color |
|---|---|---|---|---|
050 | 1px | 4px | 0 | rgba(0, 0, 0, 0.03) |
100 | 2px | 12px | 0 | rgba(0, 0, 0, 0.04) |
200 | 4px | 20px | -4px | rgba(0, 0, 0, 0.06) |
300 | 6px | 24px | -6px | rgba(0, 0, 0, 0.07) |
400 | 8px | 32px | -8px | rgba(0, 0, 0, 0.08) |
500 | 20px | 60px | 0 | rgba(0, 0, 0, 0.2) |
Z-index
Overlay layers reference these tokens instead of ad-hoc numbers, so stacking conflicts can't happen. The order is canonical — tooltips always win.
| Token | Value | Layer |
|---|---|---|
--z-dropdown | 50 | Menus, comboboxes |
--z-sidebar | 100 | App sidebar |
--z-header | 200 | Sticky header / topbar |
--z-modal-backdrop | 300 | Dialog scrim |
--z-modal | 400 | Dialog surface |
--z-toast | 500 | Toasts / notifications |
--z-tooltip | 600 | Tooltips (always on top) |