---
title: "Tailwind v4: Theme and Design Tokens"
slug: "tailwind-theme"
category: "frontend"
tags: ["tailwind", "css", "frontend", "design-tokens", "theming", "custom-properties", "oklch"]
status: "stable"
last_updated: 2026-10-01
summary: "Define tokens once in @theme to get CSS variables and utilities; know when to use inline, static, and initial; switch themes at runtime by overriding variables."
related: ["[[frontend/tailwind]]", "[[frontend/css]]", "[[frontend/css-custom-properties]]", "[[frontend/tailwind-dark-mode]]", "[[frontend/shadcn-theming]]", "[[comparisons/tailwind-vs-css-modules]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
> 2. **Read raw.** Append `.md` to any page URL for markdown. Check `status` and `last_updated` in the frontmatter, then read the rules.
> 3. **Apply as defaults.** First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
> 4. **Cite.** Link the page by title and URL, e.g. [Python](https://llmbestpractices.com/coding/python), with `last_updated` for time-sensitive rules. License CC BY 4.0.

## Overview

`@theme` replaces the JavaScript theme object: each declaration becomes a CSS variable on `:root` and, when its name matches a namespace, a utility class. The hub is [[frontend/tailwind]]; the variable mechanics are in [[frontend/css-custom-properties]].

## Declare design tokens in `@theme`

Use `@theme` for any value that should map to a utility, and plain `:root` for variables that should not.

```css
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.72 0.18 264);
  --font-display: "Schibsted Grotesk", system-ui, sans-serif;
  --radius-card: 0.75rem;
  --shadow-card: 0 1px 3px rgb(0 0 0 / 0.1);
  --breakpoint-3xl: 120rem;
}
```

The namespace picks the utility: `--color-*` gives `bg-brand`, `--font-*` gives `font-display`, `--radius-*` gives `rounded-card`, `--shadow-*` gives `shadow-card`, `--text-*` gives font sizes, `--breakpoint-*` gives variants, `--spacing` is the base unit for `px-4` and friends. Declaring the same tokens in `@layer base` generates no utilities.

`@theme` must be top level. Nesting it in a selector or media query is invalid.

## Choose `inline`, `static`, or `initial` deliberately

- `@theme inline`: use when a token points at another variable, for example `--color-background: var(--background)`. Without `inline`, the utility references the theme variable and can resolve to an unexpected value.
- `@theme static`: Tailwind emits only the variables your code uses; `static` forces all of them out, for values read only from JavaScript.
- `--color-*: initial;`: clears a whole default namespace so only your values generate utilities. `--*: initial;` clears the entire default theme.

## Define colors in oklch

Write color tokens as `oklch(lightness chroma hue)`; the v4 default palette is oklch too. Lightness steps look even across hues, so a dark-mode counterpart is a lightness change. `oklch()` has been Baseline widely available since November 2025. Keep scales short (three to five steps per hue plus semantic names such as `danger`); every token is something to maintain.

## Read tokens from plain CSS

Because tokens are variables, bespoke CSS reads them directly, which keeps CMS markup and third-party widgets on the design system.

```css
.prose blockquote {
  border-left: 4px solid var(--color-brand);
  margin-block: --spacing(4);
  color: --alpha(var(--color-ink) / 70%);
}
```

`--spacing()` and `--alpha()` are Tailwind functions; the old `theme()` function is deprecated.

## Switch themes by overriding the variable

Utilities read `var(--color-surface)`, so overriding the variable on a scope restyles everything under it with no rebuild.

```css
@theme {
  --color-surface: oklch(0.98 0 0);
  --color-ink: oklch(0.2 0 0);
}

[data-theme="dark"] {
  --color-surface: oklch(0.12 0 0);
  --color-ink: oklch(0.92 0 0);
}
```

For the toggle script and the `dark:` variant, see [[frontend/tailwind-dark-mode]].

## Share tokens across projects

Put tokens in their own CSS file and import it after Tailwind: `@import "../brand/theme.css";`. In a monorepo this file can be a package; no config merging is involved.

## Avoid token drift

Two tokens for the same color (`--color-blue-600` and `--color-primary`) split a design system. Search `@theme` for duplicates when adding tokens, and name tokens by role (`--color-surface`) at the component layer.

## Related

- [[frontend/tailwind]]
- [[frontend/tailwind-dark-mode]]
- [[frontend/css-custom-properties]]
- [[frontend/shadcn-theming]]
- [[frontend/css]]
- [[comparisons/tailwind-vs-css-modules]]