Tailwind v4 @theme Config

Configure custom design tokens, color palettes, and fonts directly in CSS using the Tailwind v4 @theme directive and standard CSS custom properties.

Tailwind CSS6 min readConcept 12 of 16

What the @theme Directive Is in Tailwind CSS v4

In Tailwind CSS v4, project configuration moves from legacy JavaScript files (tailwind.config.js) into standard CSS stylesheets using the @theme directive.

Inside a @theme block, developers declare custom design tokens as CSS variables (such as --color-brand-primary: #0ea5e9; or --font-display: 'Inter', sans-serif;).

Tailwind v4 automatically scans these CSS custom properties and generates corresponding utility class modifiers (bg-brand-primary, font-display, p-18) without requiring build-time JS configuration wrappers.

Why CSS-First Configuration Simplifies Build Tooling and Developer Experience

Replacing tailwind.config.js with pure CSS @theme declarations yields substantial architecture benefits:

1. **Zero JS Config Overhead**: Eliminate complex Node.js build configuration imports, CJS vs ESM module mismatches, and heavy JS bundler plugins.

2. **Native CSS Interoperability**: Theme variables defined in @theme exist as real runtime CSS custom properties, allowing non-Tailwind CSS rules or web components to reference var(--color-brand-primary) directly.

3. **Instant Hot Reloading**: CSS changes update instantly in modern build tools like Vite without restarting JavaScript bundler instances.

How to Declare Theme Tokens, Namespace Variables, and Custom Breakpoints in v4

Configure your Tailwind v4 stylesheet using these core namespace rules:

1. **Color Tokens (--color-*)**: Declare --color-brand: #0ea5e9; inside @theme. Tailwind generates bg-brand, text-brand, border-brand, and ring-brand utilities automatically.

2. **Spacing and Radius Tokens (--spacing-*, --radius-*)**: Declare --spacing-18: 4.5rem; or --radius-xl: 1rem; to extend spacing scales with p-18 or rounded-xl.

3. **Custom Breakpoints (--breakpoint-*)**: Declare --breakpoint-3xl: 120rem; inside @theme. Tailwind builds corresponding 3xl: and max-3xl: responsive media query prefixes.

4. **Resetting Default Themes**: To erase default Tailwind color palettes and enforce a strict design system, use wildcard reset syntax --color-*: initial; before defining your custom tokens.

Tailwind v4 Theme Engine Demo

Explore how Tailwind v4 uses standard CSS @theme declarations and custom CSS variables to define brand tokens natively in stylesheet files.

/* 1. Main CSS File (app.css) using Tailwind v4 @theme */ @theme { --color-brand: #0ea5e9; /* Maps to bg-brand, text-brand */ --font-display: 'Inter', sans-serif; --spacing-18: 4.5rem; } /* 2. JSX Component markup referencing v4 theme utilities */ <button className="bg-brand text-slate-950 font-display p-4 rounded-xl"> Click Brand Token </button>
Panel 1: Theme Token SwitcherActive Value: #0ea5e9
Panel 2: CSS Variable MappingGenerated Class: bg-brand
var(--color-brand)#0ea5e9
Panel 3: Rendered UI ResponseLive Theme Component

Brand Primary Action

Updating --color-brand instantly re-styles UI tokens.

Tailwind v4 replaces JS configuration files with CSS @theme directives. Declaring custom CSS variables in @theme automatically builds brand utility classes.

Check yourself

Pick an answer to lock it in, then read why. Getting one wrong is part of how it sticks.

  1. 1Where are custom design tokens configured in Tailwind CSS v4?
  2. 2Declaring `--color-brand: #0ea5e9;` inside a `@theme` block automatically generates which utility classes?
  3. 3How do you strip all default Tailwind colors to enforce a custom color palette in v4?

Remember this

  • Tailwind v4 replaces tailwind.config.js with pure CSS @theme blocks.
  • Namespace CSS variables like --color-brand generate bg-brand and text-brand utilities automatically.
  • Tokens declared in @theme exist as native CSS custom properties accessible anywhere in your CSS.
  • Use --color-*: initial; to wipe default colors when building custom design systems.

Done with this concept?

Mark it complete to track your progress. No login needed.