Theme Variables and Colors

This section documents Tailwind CSS v4.x — the CSS-first configuration line, whose v4.0 release shipped in January 2025 — as published at the official Tailwind CSS documentation, which is the reference these pages are written and verified against. No specific patch version is pinned.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production, since Tailwind iterates quickly.

This section’s bibliography lists the reference material consulted while preparing these pages.

Tailwind v4 is configured in CSS. The @theme block holds your design tokens, and unlike a plain :root rule, every token in it also generates matching utility classes and variants.

@theme vs. :root

A custom property defined in :root is just a value you can read with var(). The same property defined in @theme does two things: it is emitted as a real CSS variable on :root, and it teaches Tailwind to generate utilities from it.

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 259);
  --font-display: "Satoshi", ui-sans-serif, sans-serif;
  --text-hero: 4.5rem;
  --radius-card: 1.25rem;
}

Those four tokens produce bg-brand / text-brand / border-brand (plus the / opacity modifier), font-display, text-hero, and rounded-card — and var(--color-brand) still works in hand-written CSS.

<article class="bg-brand/10 font-display text-hero rounded-card p-6">
  Styled entirely from generated theme utilities.
</article>

A value you only need as a variable (never as a utility) belongs in :root; a value that should drive utilities belongs in @theme.

Namespaces and what each generates

Token names are namespaced by prefix. The namespace decides which utilities and variants Tailwind builds. See theme variable namespaces.

Namespace What it generates

--color-*

Color utilities — bg-, text-, border-, fill-, stroke-, ring- — all accepting the / opacity modifier

--font-*

font-* font-family utilities

--text-*

text-* font-size utilities (each may carry a paired line-height, letter-spacing, and font-weight)

--font-weight-*

font-* weight utilities such as font-medium, font-bold

--spacing

a single multiplier: every spacing and sizing utility (p-4, m-2, gap-6, w-10, size-8, inset-2) is calc(var(--spacing) * n)

--radius-*

rounded-* border-radius utilities

--shadow-*

shadow-* box-shadow utilities

--blur-*

blur-* filter utilities

--breakpoint-*

responsive variants — sm:, md:, lg: …​ — plus matching max-* variants

--container-*

container-query variants (@sm:, @md: …​) used with @container, and the max-w-* width scale

--animate-*

animate-* utilities (pair each with a @keyframes rule defined inside @theme)

--ease-*

ease-* transition-timing-function utilities

Extending, overriding, clearing, and replacing

@import "tailwindcss";

/* 1. Extend -- add tokens next to the defaults */
@theme {
  --color-avocado-500: oklch(0.84 0.18 118);
  --breakpoint-3xl: 120rem;
}

/* 2. Override a single default -- reuse the exact key name */
@theme {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --color-red-500: oklch(0.63 0.24 25);
}

/* 3. Clear one namespace, then define your own scale */
@theme {
  --color-*: initial;
  --color-white: #fff;
  --color-ink: oklch(0.20 0.02 260);
}

/* 4. Replace the whole theme -- no default tokens at all */
@theme {
  --*: initial;
  --spacing: 0.25rem;
  --color-bg: white;
}

Two modifiers change how tokens are emitted:

/* inline: paste the value into each utility instead of a var() reference --
   use when the token resolves from another variable that changes at runtime */
@theme inline {
  --color-surface: var(--surface-light-or-dark);
}

/* static: always output every custom property, even ones no utility uses
   (the default is to emit only referenced tokens) */
@theme static {
  --color-brand: oklch(0.62 0.19 259);
}

The default palette

The default palette ships 22 color families — red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, slate, gray, zinc, neutral, stone — each with the shades 50, 100, 200 …​ 900, 950, all defined in OKLCH for a wider, more perceptually uniform gamut.

Opacity is applied with the / modifier, which replaces v3’s bg-opacity- / text-opacity- utilities:

<div class="bg-sky-500">solid</div>
<div class="bg-sky-500/75">75% opaque background</div>
<p class="text-black/50">half-opacity text</p>
<div class="border border-white/10 ring-2 ring-blue-500/[71.37%]">arbitrary opacity value</div>

Using tokens outside utilities

Because every theme token is a real custom property on :root, you can consume it directly. See also CSS Custom Properties and Media Queries.

/* plain CSS -- read the generated variables */
.legacy-widget {
  color: var(--color-blue-500);
  font-size: var(--text-2xl);
  border-radius: var(--radius-lg);
}
<!-- inside an arbitrary value -->
<div class="rounded-[calc(var(--radius-xl)-1px)]
            shadow-[0_0_0_3px_var(--color-blue-500)]">
  nested rounded corner
</div>
// from JavaScript -- e.g. to feed a chart or canvas library
const styles = getComputedStyle(document.documentElement);
const brand  = styles.getPropertyValue("--color-brand").trim();
const twoXl  = styles.getPropertyValue("--text-2xl").trim();

Animations: @keyframes inside @theme

Define an --animate- token and its @keyframes together inside @theme; Tailwind lifts the keyframes to the top level and generates the animate- utility.

@import "tailwindcss";

@theme {
  --animate-wiggle: wiggle 1s ease-in-out infinite;

  @keyframes wiggle {
    0%, 100% { transform: rotate(-3deg); }
    50%      { transform: rotate(3deg); }
  }
}
<div class="animate-wiggle">shake</div>

Each @theme variable feeds two outputs at once:

flowchart LR T["@theme token
--color-brand: oklch(0.62 0.19 259)"] --> U["Utility classes
bg-brand, text-brand, border-brand, ring-brand"] T --> V["CSS custom property on :root
var(--color-brand)"] U --> H["HTML class lists"] V --> C["custom CSS, arbitrary values, JS via getComputedStyle"]

Links: Theme — Colors — Theme variable namespaces.