Elevation
Three shadows, named for what they mean rather than how big they are. Tailwind's default shadow ramp is cleared, so these three are the only ones that exist.
import from src/brand/brand.css · --elevation-*
Pick by intent, not by size
Elevation is perceived as a quality, not read as a quantity, and the eye fuses adjacent steps. So there are three, and deliberately no step in between. A component picks the role that describes its relationship to the page.
a card, a chip — it sits on the page rather than floating
a popover, a dropdown, a tooltip — it floats above the page
a dialog, a sheet — it has taken the page over
Range, not resolution
"This feels flat, add another elevation" almost always means the existing steps should be more distinct, not that a fourth is needed. If adding depth produces five shadows, range has been confused with resolution. Adding a step means arguing that a whole class of UI needs it.
Shadows are deeper in dark mode, because a dark surface needs more contrast to read as lifted.
That pairing lives in src/brand/brand.css.
Radius
One knob, --radius, with two derived steps.
This brand is close to square on purpose.
rounded-sm
calc(--radius - 4px)
rounded-md
calc(--radius - 2px)
rounded-lg
--radius (0.25rem)
Z-index
A short named stack, never a numeric free-for-all. A bare
z-50 or z-[60] fails the lint gate.
| Utility | For |
|---|---|
| z-raised | content lifted above a decorative layer inside one component |
| z-dropdown | menus |
| z-sticky | a pinned header |
| z-overlay | a scrim |
| z-modal | dialogs and sheets |
| z-toast | transient notifications |
| z-tooltip | tooltips, above everything else that is content |
| z-cursor | a custom cursor, the top of the stack |