Space & shape
A 4px spatial base, real control sizes, one stacking vocabulary, a radius scale, and two elevations.
Spacing — 4px base
All spacing is a multiple of 4px, and the base is a token — --spacing: 0.25rem — so
Tailwind's spacing utilities (p-4, gap-2, …) derive from Lumen, not from a coincidence.
The common rungs:
4 · 8 · 12 · 16 · 24 · 32 · 48 · 64
Size — controls & the tap floor
The dimensional decisions the kit actually ships, as tokens (use h-(--size-control-md) etc.):
| Token | Value | Use |
|---|---|---|
--size-control-sm | 32px | Compact rows (Button sm) |
--size-control-md | 36px | The default control (Button md, Input) |
--size-control-lg | 44px | Hero / touch-first (Button lg) |
--size-tap-min | 24px | The hard floor — no pressable target below this (WCAG 2.5.8) |
Layers — one stacking vocabulary
Z-index is a scale, not an arms race. Use z-(--layer-modal) etc.; never a bare number.
| Token | Value | What lives there |
|---|---|---|
--layer-raised | 10 | Lifted cards, sticky affordances inside content |
--layer-sticky | 20 | Sticky headers/rails |
--layer-overlay | 40 | Scrims (the --overlay wash) |
--layer-modal | 50 | Sheets, dialogs |
--layer-popover | 60 | Menus, selects, popovers — may open above a modal |
--layer-toast | 70 | Toasts — outlive the modal that spawned them |
--layer-tooltip | 80 | Tooltips — beat everything |
Radius
The rounded-* utilities are bound to this scale (not Tailwind's defaults — Tailwind's md
is 6px, Lumen's is 8px).
| Token | Value |
|---|---|
sm | 6px |
md | 8px |
lg | 12px |
xl | 16px |
2xl | 22px |
full | 999px (pills, dots, avatars) |
Strokes
| Token | Value | Use |
|---|---|---|
--stroke-hairline | 1px | Borders, separators — the soft warm seam |
--stroke-emphasis | 2px | Focus rings, invalid borders |
Elevation
Two warm-tinted shadows — depth is restrained, never theatrical — plus the one scrim.
shadow-sm / shadow-lg utilities resolve to these.
| Token | Use |
|---|---|
--shadow-sm | Cards, fields, badges — the resting surface |
--shadow-lg | Hover lift, popovers, the Agent panel |
--overlay | The wash behind sheets/dialogs — warm ink by Day, deeper by Night; never pure black |
All of the numeric scales above are mirrored as data in the package (radius, spacing,
sizes, layers, icons from lumen) and machine-checked against the CSS by the
truth script — drift fails the build.