Content
Tailwind Design System
Build and maintain a tokenized design system using Tailwind CSS v4's native @theme directive and CSS custom properties. Tokens enforce design decisions so that spacing, color, radii, shadows, and typography remain consistent across every component — without relying on per-developer taste or memory.
When to use
- Starting a new design system or component library on Tailwind CSS v4
- Migrating from arbitrary Tailwind classes to a token-driven approach
- Adding dark mode, theming, or brand variants to an existing Tailwind project
- Auditing an existing codebase for design inconsistency (radius drift, color proliferation, spacing anarchy)
- Defining a type scale with fluid sizing using
clamp() - Setting up shadow, blur, and motion tokens for a cohesive depth system
When NOT to use
- Projects locked to Tailwind CSS v3 without upgrade path —
@themeis v4 only - Quick prototypes where speed matters more than consistency — use default Tailwind utilities
- CSS-in-JS systems (Emotion, styled-components) — tokens transport differently there
- Design work in Figma without a code component — define tokens in Figma variables first, then mirror here
Core concepts
Token categories
Every design system needs tokens in these categories:
| Category | Token prefix | Examples |
|---|---|---|