The @theme Directive

Tailwind v4 replaces tailwind.config.js with the @theme directive, defining design tokens as CSS variables that generate utilities.

4 min read Level 2/5 #tailwind#theme#config

What you'll learn

Add colors, fonts, and breakpoints via @theme
Understand how a token name maps to a generated utility
Reference theme tokens elsewhere with var()

Tailwind v4 has no tailwind.config.js by default. You configure the framework directly in your CSS entry file using the @theme directive.

Defining Tokens

Import Tailwind, then declare tokens. Each token is a CSS custom property in a namespaced form:

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 256);
  --font-display: "Satoshi", sans-serif;
  --breakpoint-3xl: 120rem;
}

That single block creates three new utilities: bg-brand / text-brand / border-brand, a font-display family, and a 3xl: responsive variant — all generated automatically from the token names.

Token Name to Utility

The namespace prefix decides which kind of utility is produced. --color-* feeds color utilities, --font-* feeds font-*, --breakpoint-* feeds responsive prefixes, --spacing-* feeds padding, margin, gap, and more:

@theme {
  --spacing-gutter: 2.5rem;
  --radius-card: 1.25rem;
  --text-mega: 4.5rem;
}

These give you p-gutter, gap-gutter, rounded-card, and text-mega. Learn the namespaces and the utilities follow predictably.

Tokens Are Real CSS Variables

Because @theme emits actual custom properties, you can use them in hand-written CSS too:

.hero {
  background: var(--color-brand);
  font-family: var(--font-display);
}

One definition serves both the utility system and any bespoke CSS, which keeps your design system genuinely single-sourced.

Design Tokens & CSS Variables →