Elevation levels, recesses and status fills, with their light and dark values, the parts that own them and how each separates from its parent.
Hierarchy comes from elevation levels, not from background colors. Each level pairs a fill and a shadow for each theme. Light mode separates levels with shadows. Dark mode separates them with lightness steps.
This page lists each level, the recesses and the status fills. For role shadow tokens and how Box and Card apply them, see Elevation. For the full color token list, see Colors.
Elevation levels
Bind to the semantic token, not to a ramp step. A component on --color-bg-overlay gets the right fill in both themes with no per-component override.
Level
Fill token
Light
Dark
canvas
--color-bg-default
step 2 (#fcfcfd)
step 1 (#090a0e)
surface
--color-bg-surface
step 4 (#e9eaef)
step 3 (#1c1f27)
raised
--color-bg-raised
step 1 (#ffffff) plus --elevation-raised-shadow
step 3 (#1c1f27), no shadow
overlay
--color-bg-overlay
step 1 (#ffffff) plus --elevation-overlay-shadow
step 4 (#252832) plus --elevation-overlay-shadow
modal
--color-bg-modal
step 1 (#ffffff) plus --elevation-modal-shadow
step 5 (#2d313d) plus --elevation-modal-shadow
tooltip
--color-bg-tooltip
step 1 (#ffffff) plus --elevation-overlay-shadow
step 6 (#373a4a) plus --elevation-overlay-shadow
Owners and separation
Level
Owning parts
Separates from its parent by
canvas
AppShell
Nothing. It is the page, and it has no shadow.
surface
Sidebar
Lightness step in both themes. No shadow.
raised
Panel, Card, Toolbar
Shadow in light, lightness step in dark (no shadow)
overlay
Popover, Menu, Drawer, Toast
Shadow in light, lightness step in dark
modal
Dialog
Shadow in light, lightness step in dark
tooltip
Tooltip
Shadow in light, lightness step in dark
Notes on the table:
The step numbers and hex values come from the comments in packages/ui/src/tokens/axon-colors.css. The comments on the --color-bg-* tokens describe their older pairing of fill and shadow. The elevation-level tokens are what parts bind to.
Each level exposes its shadow as --elevation-level-<level>-shadow. Canvas and surface have no shadow. Raised has a shadow in light only. Overlay and tooltip use the overlay shadow in both themes. Modal uses the modal shadow in both themes.
Sidebar is the one exception to "the owning part uses the level's fill". It paints its own fill in both themes.
Panels keep their border in both themes.
In dark mode, raised uses the same step as surface (step 3) and has no shadow. The panel border separates it from its parent.
Same level as the parent
A surface at its parent's level shows a wash fill and no shadow. A card inside a panel is at the panel's level, so it uses a wash fill and does not add a shadow.
A wash fill composites over whatever surface is behind it, so it works in any parent. Use one of these:
--color-bg-input
--color-fill-subtle, --color-fill-default or --color-fill-strong
--color-recess-subtle, --color-recess-default or --color-recess-strong
Do not use the opaque -solid twins for this. They match only when the parent is the page.
Recesses
Recesses are insets that sit below their parent. They are washes, so they composite over any level.
Token
Use
--color-recess-subtle
Zebra rows and table stripes
--color-recess-default
Inset wells and input fields on a panel
--color-recess-strong
Code blocks and empty states
The --color-recess-<weight>-solid tokens are opaque and match only on the page. See Colors for the swatches of the surface and fill tokens.
Status fills
Status fills use --color-status-<intent>-bg for destructive, warning, success and informative. They composite over any parent, so a status fill does not change with the level it sits on. Pair each background with the same intent's foreground. See Colors for the swatches.
Rules for apps and remotes
App and remote code never sets a fill on a remote's root or on a panel body. The shell owns the slot's frame.
Do not add a shadow to a surface at its parent's level. Use a wash fill.
Bind to the semantic fill token. Do not read a ramp step.
Level tokens from Chroma
Chroma will provide --elevation-level-<level>-fill and --elevation-level-<level>-shadow for each level (CORE-2374). They reach @prepared911/ui with the CORE-2375 advance, and they are not available yet. Until then, use the fill and shadow tokens in the table above. This page will list the new tokens when they ship.