Building a Design System with Tailwind CSS v4

Tailwind is often criticized for making stylesheets unreadable. Used without discipline, that criticism is fair. But with a solid token layer and a @layer components vocabulary, it becomes the fastest design system I've ever worked with.

Define Tokens in CSS Custom Properties

Rather than leaning on Tailwind's config for every color, I define semantic tokens in :root. This makes theming trivial and keeps your Tailwind classes meaningful rather than color-code cryptic.

:root {
  --accent-primary: #4F8CFF;
  --text-secondary: #A7B0C0;
  --bg-secondary:   #0D1117;
}

Component Classes via @layer components

For patterns that repeat more than twice — buttons, cards, tags, labels — I write a class in @layer components using @apply. This keeps JSX clean and changes propagate everywhere automatically.

Strict Spacing Scale

I only allow spacing values from a fixed set: 4, 8, 12, 16, 24, 32, 48, 64, 80. Everything else requires a code-review comment explaining why. Consistency > flexibility here.