Customizing the Theme with @theme

CSS-First Theme Configuration

In Tailwind v4, design tokens are declared with the @theme directive inside your CSS file. Every token you define becomes a utility class automatically. Tokens map to CSS custom properties (variables) under the hood.

@import "tailwindcss";

@theme {
  --color-brand: #0ea5e9;
  --color-brand-dark: #0369a1;

  --font-sans: "Inter", sans-serif;
  --font-display: "Cal Sans", sans-serif;

  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;

  --radius-card: 1.25rem;
}

After this block, you can use bg-brand, text-brand-dark, font-display, p-18, and rounded-card in your HTML — they are generated from your tokens.

Extending vs Replacing

By default @theme extends the built-in scale. To replace the entire color palette (removing defaults), use @theme default { ... }. This gives you full control when you want a completely custom design system.