Extending the Theme with Custom Tokens

11 min read

Building a Design System with @theme

In Tailwind v4, @theme is your design token registry. Every token you define becomes a utility class automatically. This is how you codify your brand's spacing, color, typography, and radius decisions in one place.

Color Tokens

css

@import "tailwindcss";

@theme {
  /* Brand palette */
  --color-brand-50:  #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a8a;

  /* Semantic aliases */
  --color-surface:   var(--color-neutral-50);
  --color-on-surface: var(--color-neutral-900);
  --color-primary:   var(--color-brand-500);
}

After this block, bg-brand-500, text-on-surface, and bg-surface are all valid Tailwind classes. Semantic aliases are the key to maintainable dark-mode theming.

Spacing, Radius, and Font Tokens

css

@theme {
  /* Custom spacing steps */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
  --spacing-128: 32rem;

  /* Brand radii */
  --radius-card:   1.25rem;
  --radius-chip:   9999px;

  /* Fonts */
  --font-display: "Cal Sans", "Inter", sans-serif;
  --font-mono:    "JetBrains Mono", monospace;
}

Replacing vs Extending

Use @theme default { } (with the default keyword) to wipe out a built-in scale and replace it entirely. Without default, your additions merge on top of the existing scale.

css

@theme default {
  /* Replaces ALL built-in colors — only these exist now */
  --color-ink:     #0f172a;
  --color-canvas:  #ffffff;
  --color-accent:  #6366f1;
}

Store your @theme block in a dedicated file (e.g., tokens.css) and import it after @import "tailwindcss";. This keeps your global stylesheet clean and makes tokens easy to audit.

Ready to test yourself?

Practice Tailwind CSS— quiz & coding exercises