Skip to content

Design

Building design systems with Tailwind CSS v4

March 9, 202610 min readRasel Hossain
Design

Quick answer

A Tailwind v4 design system starts with @theme tokens for colors, spacing, radii and typography defined as CSS variables, then semantic aliases, then composable component primitives like buttons and cards. Document usage, lint against raw values, and version the system like code.

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.

Written by

Rasel Hossain — author photo

Rasel Hossain

Full Stack Developer & AI Automation Engineer — 6+ years, 168 projects delivered on Fiverr, SaaS platforms and automation in production.

Published:

#Tailwind CSS#Design Systems#CSS#Frontend

How to do it

  1. 1

    Define primitives

    Set raw palette, spacing, radii and type values as @theme custom properties.

  2. 2

    Add semantic aliases

    Map raw values to meaning (surface, primary, danger) so rebrands touch one layer.

  3. 3

    Build primitives

    Create button, input, card, badge and dialog components consuming only aliases.

  4. 4

    Govern it

    Lint against raw values, document each token, and review new variants weekly.

Frequently asked questions

Should I migrate from Tailwind v3 config to v4 @theme?

Yes for active projects — the migration is mostly mechanical (tokens move from config to CSS) and the payoff is a single source of truth for theming. Budget a day for a medium codebase, mostly for auditing hardcoded values the config migration exposes.

How many tokens does a small product need?

Fewer than you think: around seven surface colors, one primary, four semantic states, a spacing scale, three radii and a short type scale. Start there and add only when two or more screens need the same new value.

How do I stop developers bypassing the system?

Lint rules that forbid arbitrary values and raw hex codes, plus fast code review. Make the right choice the easy choice: if the primitive covers the need, nobody reaches for custom CSS.

Do I need Storybook for a small design system?

Not necessarily. A single documented page showing every primitive with its variants is enough for teams under ten. Add Storybook when you need isolated testing or cross-team consumption.

More articles

Related reading from the same areas — practical notes on shipping software.

View all articles

Liked the article?

Have a similar problem in your business? Let's talk about building the fix.

Start a project