Building a Scalable Design System with Tailwind CSS v4

Why Design Systems Matter

A well-built design system is the difference between a product that feels cohesive and one that feels cobbled together. With Tailwind v4, the tooling finally matches the ambition.

CSS-First Configuration

Tailwind v4 moves configuration into CSS using @theme:

@theme {
  --color-primary: #2563eb;
  --color-primary-600: #1d4ed8;
  --font-display: 'Poppins', sans-serif;
}

Design Tokens Strategy

Structure your tokens in three tiers:

1. Primitive tokens — raw values (colors, sizes)

2. Semantic tokens — contextual (background, foreground)

3. Component tokens — specific (button-bg, card-border)

Dark Mode with CSS Variables

:root { --bg: #ffffff; --fg: #0f172a; }
.dark { --bg: #020617; --fg: #f8fafc; }

This way, dark mode is just a class toggle — no JavaScript required for colors.