Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Dark Mode and Theming

The @theme Directive and Design Tokens

Understand the Tailwind CSS v4 @theme directive: theme variable namespaces, how variables become utilities, CSS variables you can reuse, and @theme inline.

In Tailwind v3 your design choices lived in a JavaScript file, tailwind.config.js. In Tailwind v4 they live in your CSS, inside the @theme directive, as ordinary CSS custom properties. This lesson explains what a theme variable is, how a name like --color-brand automatically gives you bg-brand, text-brand and border-brand, and what the namespaces mean.

What is a theme variable?

A theme variable is a CSS custom property declared inside @theme. It is special in two ways: its name decides which utilities Tailwind generates, and it is also exposed as a real CSS variable on the page.

CSS
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 259);
}

From this one line you can write bg-brand, text-brand, border-brand, ring-brand, fill-brand, from-brand and more, including opacity modifiers such as bg-brand/50. In your own CSS you can use var(--color-brand).

One variable, many utilities

The last line proves the variable exists in the browser as --color-brand, so JavaScript and plain CSS can read it.

Namespaces decide what you get

The part before the first dash after the double hyphen is the namespace. It tells Tailwind which utilities to create.

Namespace Example Utilities created
--color-* --color-brand bg-brand, text-brand, border-brand, fill-brand ...
--font-* --font-display font-display (font family)
--text-* --text-huge text-huge (font size)
--font-weight-* --font-weight-ultra font-ultra
--tracking-* --tracking-tighter2 tracking-tighter2
--leading-* --leading-snug2 leading-snug2
--spacing --spacing: 0.25rem all spacing utilities (p-4, w-10, gap-3 ...)
--breakpoint-* --breakpoint-3xl 3xl: variant
--container-* --container-8xl max-w-8xl, @8xl:
--radius-* --radius-card rounded-card
--shadow-* --shadow-glow shadow-glow
--ease-* --ease-snappy ease-snappy
--animate-* --animate-wiggle animate-wiggle

A variable outside these namespaces is still a CSS variable, but it creates no utilities. Use that for values you want to reference yourself.

Radius, shadow and font tokens

The spacing scale is one variable

In v4, a single variable controls the whole spacing scale: --spacing, which defaults to 0.25rem. A utility like p-4 is computed as calc(var(--spacing) * 4). That means any number works, not only the ones in a predefined list: p-7, w-13, gap-4.5 all exist. Change the base and every spacing utility scales.

CSS
@theme {
  --spacing: 0.3rem;   /* p-4 is now 1.2rem */
}

Overriding, extending and resetting

Declaring a variable that already exists overrides it: --color-blue-500: oklch(...) changes bg-blue-500 everywhere. Declaring a new name adds to the defaults. To remove defaults, reset a whole namespace to initial.

CSS
@theme {
  --color-*: initial;           /* remove every default color */
  --color-white: #fff;
  --color-ink: #111827;
  --color-brand: #4f46e5;
}

With this, bg-red-500 no longer exists, which is a good way to enforce a strict brand palette. To start from nothing, use --*: initial; and define everything yourself.

Using theme variables in your own CSS

Because theme variables are real CSS variables, you can use them anywhere:

CSS
.hero {
  background: linear-gradient(var(--color-brand), var(--color-ink));
  padding: calc(var(--spacing) * 12);
}

Tailwind only writes a variable to the final CSS when it is used, either by a utility or by var(). Unused tokens are dropped to keep the file small. If you need them all kept (for runtime lookups from JavaScript, say), use @theme static { ... }.

@theme inline: variables that reference variables

Sometimes a token's value is another variable, such as a font set by a framework (var(--font-inter)). Because of how CSS variable resolution works, a utility generated from --font-sans: var(--font-inter) could end up looking up --font-inter in the wrong place. Writing @theme inline makes Tailwind put the value straight into the utility instead of the variable reference.

CSS
@theme inline {
  --font-sans: var(--font-inter), system-ui;
  --color-primary: var(--primary);      /* --primary is defined elsewhere */
}

This is exactly the tool you need for switchable themes, where the real color lives in a plain CSS variable that changes with a class.

A mental model

flowchart LR
  A["@theme<br/>--color-brand"] --> B["utilities<br/>bg-brand, text-brand ..."]
  A --> C["CSS variable<br/>var(--color-brand)"]
  B --> D["generated stylesheet<br/>(only what you use)"]
  C --> D

A theme variable feeds both the utilities and the CSS variable layer.

Common mistakes

  • Putting @theme inside a selector or media query. It must be top level.
  • Misspelling the namespace (--colour-brand, --colors-brand): nothing is generated and no error is shown.
  • Naming a color --color-primary-500 and then writing bg-primary: the number is part of the name.
  • Expecting a variable declared in :root (not @theme) to create a utility. It will not.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which declaration makes bg-brand available?

    The --color-* namespace inside @theme creates color utilities; :root alone only defines a plain variable.
  2. 2. How does p-4 get its value in Tailwind v4?

    One --spacing variable (0.25rem by default) multiplied by the number.
  3. 3. What does --color-*: initial; do inside @theme?

    Setting a namespace wildcard to initial clears those defaults.
  4. 4. When do you need @theme inline?

    inline puts the resolved value in the utility so a variable that changes elsewhere (such as a theme class) is read correctly.

Summary

  • @theme declares design tokens as CSS variables; their names decide which utilities exist.
  • Namespaces such as --color-*, --font-*, --text-*, --radius-*, --shadow-*, --breakpoint-* and --animate-* map to utility families.
  • A single --spacing variable drives the whole spacing scale.
  • Override a token by redeclaring it, add by choosing a new name, remove defaults with --namespace-*: initial.
  • Use @theme static to keep unused variables, and @theme inline when a token references another variable.

Next: Custom Colors, Fonts and Spacing