Elevation
Depth by tone first, a 1 px border second, a shadow last.
Tone first, border second, shadow last.
Separate regions by stepping the surface tone. Add a 1 px line where two regions of the same tone meet. Use a shadow only for UI that floats above the page.
The layer ladder
Depth reads from tone alone. In light, layer-1 is white on a shaded canvas and nested layers step darker; in dark, every step is lighter. Adjacent layers always differ.
| Token | Light | Dark | fg.primary (light / dark) | Use for |
|---|---|---|---|---|
| surface.canvas bg-surface-canvas | 18.84:1 AAA19.59:1 AAA | The app background and the main area behind every page. | ||
| surface.layer-1 bg-surface-layer-1 | 19.67:1 AAA18.84:1 AAA | TopBar, SideNav column, PageHeader, cards and panels. | ||
| surface.layer-2 bg-surface-layer-2 | 18.84:1 AAA16.96:1 AAA | Regions inside a layer-1 surface: table headers, card footers, code blocks, wells. | ||
| surface.layer-3 bg-surface-layer-3 | 17.77:1 AAA15.31:1 AAA | A region inside layer-2: a selected row in a well, a segmented track inside a footer. | ||
| surface.overlay bg-surface-overlay | 19.67:1 AAA16.96:1 AAA | Floating UI above the page: menus, popovers, dialogs. Pairs with a shadow. | ||
| surface.inverse bg-surface-inverse | uses fg.inverse | Tooltips and toasts. Text on it is fg.inverse. |
Nested, in both themes
The same four steps in light and dark. Only the outer card has a border; the inner steps are separated by tone alone.
$12,480.00
$12,480.00
Which layer for which UI
| UI | Surface |
|---|---|
App background, the main area behind pages | canvas |
TopBar, SideNav column, PageHeader | layer-1 |
Cards, panels, the playground controls | layer-1 |
Table header, card footer, code block, inset well | layer-2 |
A selected or highlighted region inside a layer-2 well | layer-3 |
Menus, popovers, select lists, dialogs | overlay + shadow |
Tooltips, toasts | inverse |
Hovered row or nav item on a layer | that layer’s -hover token |
Hover tokens
Each layer has a -hover step for rows and items that respond to the pointer. Hover is one step toward the next layer, never a border or a shadow.
| Layer | Hover token | Light | Dark |
|---|---|---|---|
| surface.layer-1 | surface.layer-1-hover | ||
| surface.layer-2 | surface.layer-2-hover | ||
| surface.layer-3 | surface.layer-3-hover |