Elevation
The Figma Elevation collection — box-shadow and blur-radius primitives, and the composed semantic shadow tokens components consume.
Elevation is the Figma collection that governs depth (modes flat / subtle / lifted / dramatic). It ships two Primitive groups — box-shadow and blur-radius — that compose into the ready-to-use semantic --shadow-* values components reference. The CSS variable prefix stays --shadow-* / --box-shadow-*; the collection and this page carry Figma's name, Elevation.
Use composed semantic shadows in component CSS — --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl. Never compose raw blur and spread values yourself; the semantic tokens are tuned together for consistent perceived elevation.
From Figma Elevation to shadow tokens
A Figma variable holds a single dimension, so the Elevation collection's box-shadow group exports as --box-shadow-sm/md/lg/xl carrying only a blur value (e.g. 2px) — not a usable box-shadow shorthand. tokens/gap-fills.css closes the gap: it defines the real multi-part --shadow-* shorthands, then re-aliases --box-shadow-* → var(--shadow-*) so either name resolves to the correct value.
| Layer | Names | Where |
|---|---|---|
| Figma collection | Elevation → groups box-shadow, blur-radius | design-tokens/tokens-studio.json |
| Style Dictionary output | --box-shadow-* (single blur), --blur-radius-*, --shadow-blur/offset/spread-* | tokens/figma-tokens.css |
| Composed semantic (what you use) | --bds-shadow-sm/md/lg/xl, --bds-shadow-overlay | tokens/gap-fills.css |
--shadow-* is canonical for elevation; --box-shadow-{sm,md,lg,xl} is a deprecated alias (#2233). Both ship and resolve identically, but component CSS now references only --shadow-* — the safe composed base, defined once. The --box-shadow-{sm..xl} aliases survive only for existing consumers; don't reach for them in new work. Note --box-shadow-none (value none, for suppressing a shadow) is a separate token with no --shadow-* twin — it stays as-is.
Composed shadow tokens
Ready-to-use box-shadow values defined in tokens/gap-fills.css. These are what components reference.
| Token | CSS Variable | Value | Use case |
|---|---|---|---|
| Small | --bds-shadow-sm | 0px 2px 4px 0px rgba(0,0,0,0.06) | Subtle cards, inputs |
| Medium | --bds-shadow-md | 0px 4px 12px 0px rgba(0,0,0,0.12) | Cards, panels |
| Large | --bds-shadow-lg | 0px 4px 16px 0px rgba(0,0,0,0.12) | Dropdowns, popovers |
| Extra large | --bds-shadow-xl | 0px 8px 24px 4px rgba(0,0,0,0.20) | Modals, dialogs |
Overlay
| Token | CSS Variable | Value |
|---|---|---|
| Overlay | --bds-background-overlay | rgba(0, 0, 0, 0.4) |
Used for modal backdrops and drawer overlays.
Shadow blur scale
Controls the softness/diffusion of shadows.
0px2px4px6px8px10px12px14px16pxShadow spread scale
Controls how far a shadow extends outward.
0px2px4px8px10px12px14px16px16pxFilter blur
--blur-radius-* feeds the CSS filter: blur() and backdrop-filter — the softening of an element or of whatever sits behind it. This is distinct from --shadow-blur-*, which is the blur component of a box-shadow; the two are not interchangeable.
Shipped, but unconsumed today. No component references --blur-radius-* (grep -r "var(--blur-radius" components/ → 0). The family is available for frosted-glass / scrim treatments; until one ships, whether BDS keeps it is an open question for the naming ADR (#1910).
| Token | CSS Variable | Value |
|---|---|---|
| Small | --bds-blur-radius-sm | 8px |
| Medium | --bds-blur-radius-md | 12px |
| Large | --bds-blur-radius-lg | 14px |
| Extra large | --bds-blur-radius-xl | 16px |
.frosted-panel {
backdrop-filter: blur(var(--bds-blur-radius-md));
}Related
- Border — radius and elevation read together at the component edge
- Color tokens — surface tokens shadows sit on