Configuring Tailwind CSS v4 theme tokens in your CSS

Older versions of Tailwind CSS were configured in a JavaScript file. Tailwind CSS v4 takes a CSS-first approach: your design tokens live in the same stylesheet that imports Tailwind. This keeps colors, fonts and spacing next to the CSS that uses them, and it makes it easy to share values with plain CSS variables.

Start with one import

In your main stylesheet, import Tailwind:

@import "tailwindcss";

That single line replaces the three directives older versions needed.

Define tokens with the theme directive

Declare your design tokens inside a @theme block as CSS variables:

@theme {
  --color-accent: #2b50d9;
  --font-serif: "Source Serif 4", Georgia, serif;
  --radius-md: 8px;
}

The variable name decides which utilities Tailwind generates. A --color-* variable becomes color utilities such as bg-accent and text-accent. A --font-* variable becomes a font family utility such as font-serif. A --radius-* variable becomes a rounding utility such as rounded-md.

Support dark mode with CSS variables

A theme token holds one value, but a dark theme needs two. The solution is to keep the real values in ordinary CSS variables, swap them for the dark theme, and point the Tailwind tokens at them:

:root {
  --bg: #ffffff;
  --fg: #242424;
}
 
:root[data-theme="dark"] {
  --bg: #121212;
  --fg: #ededed;
}
 
@theme inline {
  --color-bg: var(--bg);
  --color-fg: var(--fg);
}

The inline option tells Tailwind to use the referenced variable directly in the generated utilities. Because of that, bg-bg follows --bg, and everything updates the moment the data-theme attribute changes. No extra dark-mode classes are needed on each element.

A naming gotcha with fonts

If you load fonts with a framework helper that exposes its own CSS variable, give that variable a different name from your Tailwind token. For example, expose the font as --font-source-serif and then reference it from the token:

@theme inline {
  --font-serif: var(--font-source-serif), Georgia, serif;
}

Using the same name for both can create a variable that refers to itself, and the font silently stops working.

Takeaway

With v4, the stylesheet is the single place where your design system lives. Define tokens in @theme, keep switchable values in plain CSS variables, and connect them with @theme inline. Details can change between releases, so check the official documentation for the version you have installed.