Customising the theme with @theme

The theme is the set of values Tailwind builds utilities from: colors, fonts, breakpoints, shadows. In Tailwind 4 the theme is configured right in CSS with the @theme directive: each variable inside it creates new classes.

Where it goes

In a Vite project the theme lives in the main CSS file src/style.css, right after Tailwind is imported:

@import "tailwindcss";
 
@theme {
  --color-brand-500: #e11d48;
  --color-brand-600: #be123c;
}

Now you have bg-brand-500, text-brand-600, border-brand-500 and every other utility that takes a color — including the opacity modifier bg-brand-500/20.

Namespaces

The start of the variable name decides which classes appear:

Colors, a font and a breakpoint

With the browser script the same goes into <style type="text/tailwindcss">. Let us add a brand color, a heading font and one more breakpoint:

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
<style type="text/tailwindcss">
  @theme {
    --color-brand-500: #e11d48;
    --color-brand-600: #be123c;
    --font-display: Georgia, "Times New Roman", serif;
    --breakpoint-xs: 30rem;
  }
</style>
 
<div class="max-w-xs rounded-xl bg-white p-4 shadow">
  <h2 class="font-display text-2xl">Headphones</h2>
  <p class="text-gray-600 xs:text-brand-600">$79</p>
  <button class="mt-3 rounded-lg bg-brand-500 px-4 py-2 text-white hover:bg-brand-600">Add to cart</button>
</div>

The heading uses a serif font, the button is crimson, and the price takes the brand color on screens from 480 pixels. A loaded web font, for example from Google Fonts, goes into --font-display the same way — by its family name.

Variables are available in CSS

Theme variables are available as ordinary CSS variables — you can use them in your own CSS: color: var(--color-brand-500). That way your CSS and the utilities take the color from one place.

Replacing the defaults

To remove all default colors and keep only yours, reset the namespace with initial:

@import "tailwindcss";
 
@theme {
  --color-*: initial;
  --color-white: #fff;
  --color-ink: #111827;
  --color-brand: #e11d48;
}

Classes like bg-blue-500 stop working after this — only white, ink and brand remain.

Common mistake

Declaring theme variables in :root instead of @theme:

:root {
  --color-brand: #e11d48;
}

The variable exists, but the bg-brand class does not: Tailwind creates utilities only from @theme. A plain :root is for variables that need no classes. In Tailwind 3 the theme was configured in tailwind.config.js — version 4 does not need that file.