Introducing a new way to review your PRs.

Read the announcement

tailwindlabs / tailwindcss

A utility-first CSS framework for rapid UI development.

View on GitHub

19 documents · Updated Nov 20, 2026

docs / theme-and-design-tokens

Theme and design tokens

The theme is the shared design contract between CSS input and generated CSS. It turns custom properties into named design tokens, lets utilities and variants resolve those tokens, and keeps modern CSS themes compatible with older JavaScript configuration. The broader generation flow is described in Compiler and CSS generation, with CSS directive details in CSS directives and parsing and candidate behavior in Utility and variant compilation.

Theme model

The theme is a name-to-value model built from @theme blocks and, when needed, legacy configuration. A token is a CSS custom property whose prefix identifies a namespace and whose remaining name identifies a value, such as --color-red-500 or --breakpoint-md. The model also records whether a value should be emitted, inlined, treated as a default, or kept for reference.

The compiler collects all theme blocks before it generates utilities. It replaces the first @theme block with a :root, :host rule that contains the final emitted tokens. Later theme blocks contribute values to the same model instead of producing separate theme rules. Keyframes declared in a theme are preserved and emitted at the top level.

The model accepts initial as a removal signal. A wildcard such as --spacing-*: initial clears values in one namespace. This lets a project replace part of the default theme without leaving old token names available to utility matching.

References: packages/…/theme.ts• L41-85 packages/…/index.ts• L546-600 packages/…/index.ts• L654-675

Token namespaces

Token namespaces group values by the kind of design choice they represent. Utility families read an ordered list of one or more namespaces, so adding a token can create a matching utility value without adding a new utility rule. Shared namespaces let one scale serve several related utilities.

NamespaceDesign roleExample token
--color-*Color palette and semantic color values--color-blue-500
--spacing-* and --spacingSpacing scale and its base multiplier--spacing-4, --spacing
--font-*Font families and related font data--font-sans
--text-*Font sizes and optional line-height data--text-sm, --text-sm--line-height
--breakpoint-*Responsive variant thresholds--breakpoint-md
--container-*Container width values--container-lg
--radius-*, --shadow-*, --ease-*Shape, depth, and motion values--radius-md, --shadow-sm, --ease-out
--opacity-*Named opacity modifiers--opacity-50
--animate-*Animation shorthand values linked to keyframes--animate-spin
Utility-specific namespaces such as --width-*, --height-*, and --gap-*Values for a focused utility family--width-prose

Some utility families use fallback namespaces. For example, a border color can come from a border-specific token or from --color-*. Size utilities can use a dedicated size, spacing, or container token. The namespace order is therefore part of the utility contract, not only a naming convention.

The current utility map also keeps alignment utilities separate from token-backed value utilities. Valid static classes such as content-baseline and items-baseline remain available, while justify-content exposes only values accepted for that property. This prevents a class from generating CSS that the browser rejects.

Namespaces also support compound values. A token such as --font-sans--font-feature-settings belongs to the font-sans value and supplies related data when a utility needs it. The theme model keeps this relationship while resolving the main value.

References: packages/…/utilities.ts• L246-282 packages/…/utilities.ts• L380-489 packages/…/utilities.ts• L491-533 packages/…/utilities.ts• L1085-1096 packages/…/utilities.ts• L2108-2132 packages/…/variants.ts• L1010-1125 packages/…/theme.css• L1-20 packages/…/theme.css• L325-395 packages/…/theme.css• L397-499

CSS theme input

CSS theme input uses @theme as the boundary for design tokens. The block accepts custom property declarations and @keyframes; other CSS rules are rejected. The compiler parses options on the block to control how the values participate in output and resolution.

FormEffect
@themeRegisters tokens and normally emits them as CSS variables.
@theme inlineResolves token uses to their values instead of relying on a CSS variable reference.
@theme referenceMakes tokens available for resolution without emitting their declarations in that theme output.
@theme defaultSupplies values that can be replaced by explicit project values.
@theme staticKeeps the token eligible for output even when normal use tracking would omit it.
@theme prefix(name)Adds a validated prefix to generated token names and related utility selectors.

An imported theme can be loaded as a reference. This shares token definitions with the importing stylesheet without copying the theme declarations into the output. Prefix input can also be supplied through an import and is applied to the theme and utility names together.

The default theme is a CSS input file. It provides the common scales for color, spacing, type, breakpoints, containers, effects, motion, and related defaults. A deprecated block retains older single-name tokens such as --blur, --shadow, and --radius for compatibility.

References: packages/…/index.ts• L86-105 packages/…/index.ts• L477-519 packages/…/index.ts• L546-587 packages/…/theme.css• L1-510

Token resolution

Token resolution connects a candidate name or a CSS function path to a theme value. A utility asks for a candidate within one or more namespaces. The resolver first finds the matching token in namespace order, then returns either its CSS variable form or its literal value when inline resolution is required.

The normal output favors var(--token) so the browser can use the emitted theme value. Inline values are used for @theme inline tokens and for positions such as media query parameters where a CSS variable cannot provide the required value. A token in reference mode supplies its value as a fallback when its variable is not emitted.

The --theme(...) function resolves a CSS variable path and accepts a fallback. The older theme(...) function remains available for paths from the compatibility model. Both functions are replaced during compilation. Color resolution can also apply an opacity modifier through color-mix.

This diagram shows how a theme token becomes a generated declaration or a resolved CSS function value.

flowchart LR
    A[CSS @theme token] --> B[Theme model]
    B --> C{Resolution context}
    C -->|Utility value| D[var(--token)]
    C -->|Inline or at-rule value| E[Literal token value]
    C -->|CSS theme function| F[Resolved function result]
    D --> G[Generated utility CSS]
    E --> G
    F --> G

References: packages/…/theme.ts• L168-274 packages/…/design-system.ts• L215-235 packages/…/css-functions.ts• L87-168 packages/…/css-functions.ts• L177-223

Utility generation

Generated utilities use theme namespaces as their value source. A functional utility maps a class value to the first matching token in its declared namespace list, while a color utility adds shared opacity handling. Some families also accept a bare value derived from a base token such as --spacing, or a fraction that does not need its own token. If no token matches, the utility can still accept an arbitrary value when that utility family allows it.

The same namespace mapping supplies suggestions for editor completion. Custom tokens and default tokens therefore appear in the same value set. Numeric keys support both current escaped-dot names and the older underscore form where compatibility requires it.

The compiler tracks token use while it processes candidates and CSS values. This allows the final CSS to avoid unrelated theme variables while retaining tokens marked static or tokens needed by another used token. A token used by an animation also keeps the keyframes that define that animation available.

When a utility has several namespaces, the order gives its value sources a clear priority:

  1. A dedicated utility namespace is checked first.
  2. A shared scale such as spacing, color, or container is checked next.
  3. A supported bare value, fraction, or arbitrary value is used only when the utility family allows it.

For size utilities, this contract is explicit: size-* checks --size before --spacing; width utilities check a width-specific namespace before spacing and container values; height utilities use height-specific values before spacing. The same resolution order drives both generated CSS and completion suggestions.

References: packages/…/utilities.ts• L294-366 packages/…/utilities.ts• L392-489 packages/…/utilities.ts• L543-592 packages/…/utilities.ts• L1085-1096 packages/…/design-system.ts• L108-112 packages/…/index.ts• L768-817 packages/…/ast.ts• L1858-1885

Compatibility behavior

The compatibility layer converts older JavaScript theme configuration into the same CSS-token model. It walks theme values, maps old theme names to current namespaces, preserves nested font and text data, and marks imported values as inline reference defaults. This lets old configuration feed current utilities without creating a second source of truth.

When an older configuration replaces a default namespace, the compatibility layer removes only the affected default values before adding the configured values. It also converts legacy opacity values and replaces <alpha-value> with a usable CSS value. Special defaults, such as shared border or transition defaults, use dedicated --default-* tokens.

Legacy theme(...) paths with dot notation are resolved only when compatibility support is needed. Legacy screen, container, and theme variant settings can extend the current variant system, while legacy keyframes are added to the same theme keyframe set.

References: packages/…/apply-config-to-theme.ts• L22-109 packages/…/apply-config-to-theme.ts• L112-239 packages/…/apply-compat-hooks.ts• L147-175 packages/…/theme-variants.ts• L4-67 packages/…/apply-keyframes-to-theme.ts• L6-22

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the ordered namespace lists used by utility matchers aligned with the names emitted by the default theme and the JavaScript compatibility mapping. Check both dedicated and shared fallback namespaces.
  • When changing inline, reference, default, or static behavior, check both emitted theme variables and values resolved inside at-rules.
  • When changing bare-value or fraction support for a utility family, verify that its base token and completion values still describe the same accepted inputs.
  • When changing a token with nested data, preserve the double-dash relationship used by font and text companion values.
  • When changing default replacement, verify that explicit configuration removes only the replaced default namespace and does not remove project-defined tokens.
  • When changing animation tokens or keyframes, keep CSS keyframes and compatibility keyframes in the same theme output path.
  • When changing token use tracking, check dependent variables and externally named variables used by generated utilities.
  • When changing static property-backed utilities, confirm that the generated class still maps to a CSS value accepted by the target property. Do not add a value only because a related alignment property accepts it.

Important failure modes

TriggerConsequenceGuard
A utility points to a namespace that does not contain the requested tokenThe candidate produces no utility rule unless it has an allowed arbitrary or bare-value pathKeep utility namespace declarations and theme token names in sync
A @theme block contains a rule other than a custom property or keyframesCompilation stops with a theme input errorKeep design tokens and keyframes directly inside @theme
A theme function names a missing token without a fallbackCompilation fails during function substitutionUse a valid CSS variable path or provide a fallback
A referenced token is used where its CSS variable is not emittedThe browser can receive an unresolved variableUse the reference fallback or force inline resolution when the value must be literal
A legacy config namespace is not mapped to its current namespaceOld config values do not affect current utility generationUpdate the compatibility namespace map with the token contract
A token name uses an invalid prefix or unsupported key pathTheme parsing or compatibility conversion rejects the inputUse a lowercase prefix and valid CSS token segments
A static utility exposes a CSS value that the target property does not acceptThe generated rule is ignored by the browserKeep static utility values aligned with the CSS property grammar

Key files

FileWhy to read it
packages/…/theme.tsDefines the shared theme model, token lookup, flags, namespace views, and keyframe storage.
packages/…/index.tsShows how CSS theme input is collected, merged, emitted, and connected to compilation.
packages/…/design-system.tsShows how the theme becomes the value and use-tracking service for utility generation.
packages/…/css-functions.tsDefines theme-aware CSS functions and their resolution rules.
packages/…/utilities.tsShows how utility families map candidate values to ordered theme namespaces and valid static CSS values.
packages/…/theme.cssDefines the default token scales and deprecated compatibility tokens.
packages/…/apply-config-to-theme.tsConverts legacy JavaScript theme values into CSS token names and defaults.
packages/…/apply-compat-hooks.tsConnects legacy config and plugins to the current design system.