Guide
Design tokens in practice
How we structure color, type, spacing, and motion tokens for Tailwind v4 projects.
Design tokens are the contract between design and engineering. Here's how we structure them for Tailwind v4 projects.
The four layers
Primitive tokens: raw values (color scales, spacing scale)
Semantic tokens: --background, --foreground, --primary
Component tokens: button radius, card padding (rarely needed)
Utility classes: ds-display, ds-headline for one-off patterns
Color
We use OKLCH for perceptual uniformity. Each mode (light/dark) gets its own semantic mapping. Never copy-paste hex values between modes.
Typography
Three roles: display (Instrument Serif), body (Geist Sans), mono (Geist Mono). Size scale stays tight. 5–6 sizes cover 95% of UI.
Motion
Define duration and easing tokens once. Respect prefers-reduced-motion everywhere.
Related
- 01
AtroUI indie site kit: portfolio chrome you can own
We extracted the narrow personal homepage patterns from a real portfolio into AtroUI: ~640px chrome, command menu, ship log, personal hero, reading shelf, and more. A second altitude next to studio Blocks.
Essay · 8 min read - 02
Introducing AtroUI
We extracted the UI we actually ship on client sprints into a free React / shadcn registry. Own the source, edit CONTENT, keep the dark-first system.
Essay · 8 min read
Want this built for you?
Fixed-scope MVP sprints and AI integrations. Same stack as this guide.