Customizing the Theme with @theme
Extend Tailwind's design system in CSS using v4's @theme directive and design tokens.
In Tailwind v4 the configuration lives in your CSS, not a JavaScript file. You open a @theme block and declare design tokens as CSS variables. Tailwind reads those tokens and generates matching utilities for you automatically.
Tokens become utilities
The variable's namespace decides which utilities appear. Declare a color and you instantly get bg-*, text-*, border-*, ring-*, and fill-* variants of it — plus a plain CSS variable you can use anywhere.
@import "tailwindcss";
@theme {
--color-brand-500: #06b6d4;
--color-brand-700: #0e7490;
--font-display: "Georgia", serif;
--radius-card: 1.25rem;
}
/* now usable: bg-brand-500, text-brand-700, font-display, rounded-card */
/* and in raw CSS: color: var(--color-brand-500); */The token namespaces
| Namespace | Generates |
|---|---|
--color-* | bg-*, text-*, border-*… |
--font-* | font-* |
--spacing-* | p-*, m-*, gap-*, w-* |
--radius-* | rounded-* |
--breakpoint-* | sm:, md:… variants |
Still love JavaScript config?
You can keep a legacy tailwind.config.js and point at it with @config "./tailwind.config.js";. But for new work, CSS-first tokens are the recommended path: one source of truth that is also plain CSS.
Example
When to use it
- A design team centralizes brand colors, font stacks, and spacing tokens in a @theme block so all utility classes reflect the brand system automatically.
- A developer replaces the default sans-serif stack by overriding --font-sans in @theme to apply Inter across all font-sans usages project-wide.
- A product adds a custom 18px breakpoint as --breakpoint-xs in @theme to target small phones without inventing ad-hoc media queries.
More examples
Define brand tokens in @theme
Each CSS custom property in @theme generates a matching utility class: bg-brand-500, text-brand-700, font-display, and p-18 become available immediately.
@import "tailwindcss";
@theme {
--color-brand-500: #6366f1;
--color-brand-700: #4338ca;
--font-display: 'Cal Sans', sans-serif;
--spacing-18: 4.5rem;
}Override default sans font
Reassigning --font-sans in @theme replaces Tailwind's default system font stack so every font-sans class project-wide picks up the new value.
@import "tailwindcss";
@theme {
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
}Custom breakpoint token
Defining --breakpoint-xs in @theme creates a new xs: responsive prefix, extending Tailwind's breakpoint system without any JavaScript config.
@import "tailwindcss";
@theme {
--breakpoint-xs: 30rem; /* 480px */
}
/* Usage in markup */
/* <div class="text-sm xs:text-base"> */
Discussion