Tailwind v4 moves configuration into CSS with @theme, which means design tokens live next to your other styles instead of a config file. I rebuilt the shared UI layer for three client products on this model last year — a SaaS dashboard, a school management system and an e-commerce admin — and the difference from the old config-file approach is most visible six months later, when new developers still use the system correctly without being told.
Tokens first, components second
Every successful design system I have seen follows the same layering: primitive tokens, semantic aliases, then components. Primitive tokens are the raw palette — the exact hex values, spacing scale, radii and font stacks. Semantic aliases give them meaning: background becomes surface, critical red becomes danger, the brand purple becomes primary. Components consume only aliases, never raw values.
In Tailwind v4 this maps directly to @theme blocks. Define primitive custom properties for the palette and spacing, then define semantic utilities that reference them. The payoff is that a rebrand or a dark-mode pass touches the alias layer only — components do not change. On one project a client color change took twenty minutes instead of two days because of exactly this separation.
The token set that covers 90 percent
You do not need a hundred tokens. The set that covers nearly every screen I build is small: five to seven surface colors with their foreground pairs, one primary action color with hover and active states, semantic colors for success, warning, danger and info, a four-to-six step spacing scale, three radii, and a type scale with exactly three sizes for UI plus display sizes for marketing.
- Colors: surface, elevated, muted, border, foreground pairs plus primary and semantic states
- Spacing: a 4-point base scale with named steps used consistently for padding, gaps and margins
- Radii and shadows: three radii and two shadow depths — more choice means less consistency
- Typography: one font stack, three UI sizes, defined line-heights, and tabular numbers for data
- Motion: two durations and one easing curve shared by every transition
Document each token with its purpose and one do-and-donot example. A token without documentation gets misused within a month — I have watched it happen. The documentation can live in a simple uses-style page or a Storybook-style gallery; what matters is that a developer choosing a color can find the right alias in under a minute.
Component primitives that compose
On top of tokens, build a small set of primitives: button, input, select, card, badge, dialog and table. Each primitive accepts a short list of variants (size, tone, emphasis) and nothing else. Resist the urge to add one-off props — every special case added to a primitive is consistency debt that compounds across every screen that uses it.
My rule from production work: if a design needs a variant that only one screen will use, build it as a composition of primitives in that screen, not as a new primitive variant. The design system stays small, the special screen stays possible, and the next designer can see exactly what was customized. Composition over configuration applies to UI just as much as to APIs.
Dark mode, theming and governance
Because v4 tokens are CSS variables, dark mode becomes a variable swap rather than a class puzzle. Define the semantic aliases per color scheme and let components inherit. Test contrast ratios in both modes — the muted foreground color that passes on light surfaces often fails on dark ones, and that is the single most common theming bug I fix in audits.
Governance is what keeps the system alive. Lint against raw color and spacing values so new code cannot bypass tokens, review new primitives in a weekly design sync, and version the system like any other dependency. The system pays for itself quickly once these habits exist: new features ship faster because layout decisions are already made, and design reviews focus on behavior instead of spacing. Pair the rollout with a performance budget so the system stays fast as it grows.


