Elevation
Choose a surface and a shadow for a resting card, a menu, or a dialog.
Elevation is mostly paper. Three surfaces stack from the sunken well to the room to the raised card, and three shadows add lift for resting cards, menus, and dialogs. This page shows which surface and which shadow to use for each job, so a new panel matches the ones around it.
Every shadow is built from one dark ink, --shadow-color, on steps of the alpha scale. In light the ink is oklch(0.15 0 0) at 8, 12, or 16%. In dark it drops to black at 24, 32, or 48%, because the light ink is as dark as a dark page and would not show. No look repaints it, so shadows have the same color in every look.
Surfaces
bg-surface-sunken
Sunken well.
bg-surface
Room paper.
bg-surface-raised
Raised card.
| Utility | Job |
|---|---|
bg-surface-sunken | The tray behind the sidebar, and wells such as a toggle group track or a code block |
bg-surface | Fields, and a flat room |
bg-surface-raised | The app's page, cards on it, and anything that floats: popover, menu, dialog |
The page, a card, and a menu share one surface, so elevation comes from the strong border and the shadow and not from a lighter fill. In light that surface is white, fields sit a step down, and the tray and wells a step below that. Dark mirrors the order on half steps: the page is neutral 925 and fields, the tray, and wells sit a half step lighter on 900, so the sidebar reads lighter than the page and a well reads on it. See Color for the full chrome ladder and Chrome and temperature for how paper warmth tints these surfaces.
Shadows
shadow-smResting card.
shadow-mdPopover, menu.
shadow-lgDialog, sheet.
| Utility | Layers | Job |
|---|---|---|
shadow-sm | 0 1px 3px and 0 1px 2px -1px, at 12% and 8% in light, 32% and 24% in dark | Resting card, toggle group thumb, toast |
shadow-md | 0 4px 6px -1px and 0 2px 4px -2px, at 12% and 8% in light, 32% and 24% in dark | Popover, dropdown menu, select, hover card |
shadow-lg | 0 10px 15px -3px and 0 4px 6px -4px, at 16% and 12% in light, 48% and 32% in dark | Dialog, sheet, drawer |
<div className="rounded-md bg-surface-raised p-5 shadow-sm" />The token set also includes shadow-xs (0 1px 2px 0 at 8%), which no kit component uses. Stay with the three above so surfaces at the same height cast the same shadow, and do not add a fourth geometry.
Overlay scrims use bg-scrim/(--alpha-32). The scrim is the same shadow ink as a wash, so it stays dark in dark mode and a look that repaints --sys-contrast does not tint it.
Next
Color covers the surface tokens and the alpha scale, and Radius covers the corners a shadow follows. Dialog, Popover, and Card show the shadows in place.