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.
| Namespace | Design role | Example token |
|---|---|---|
--color-* | Color palette and semantic color values | --color-blue-500 |
--spacing-* and --spacing | Spacing 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.
| Form | Effect |
|---|---|
@theme | Registers tokens and normally emits them as CSS variables. |
@theme inline | Resolves token uses to their values instead of relying on a CSS variable reference. |
@theme reference | Makes tokens available for resolution without emitting their declarations in that theme output. |
@theme default | Supplies values that can be replaced by explicit project values. |
@theme static | Keeps 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:
- A dedicated utility namespace is checked first.
- A shared scale such as spacing, color, or container is checked next.
- 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, orstaticbehavior, 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
| Trigger | Consequence | Guard |
|---|---|---|
| A utility points to a namespace that does not contain the requested token | The candidate produces no utility rule unless it has an allowed arbitrary or bare-value path | Keep utility namespace declarations and theme token names in sync |
A @theme block contains a rule other than a custom property or keyframes | Compilation stops with a theme input error | Keep design tokens and keyframes directly inside @theme |
| A theme function names a missing token without a fallback | Compilation fails during function substitution | Use a valid CSS variable path or provide a fallback |
| A referenced token is used where its CSS variable is not emitted | The browser can receive an unresolved variable | Use the reference fallback or force inline resolution when the value must be literal |
| A legacy config namespace is not mapped to its current namespace | Old config values do not affect current utility generation | Update the compatibility namespace map with the token contract |
| A token name uses an invalid prefix or unsupported key path | Theme parsing or compatibility conversion rejects the input | Use a lowercase prefix and valid CSS token segments |
| A static utility exposes a CSS value that the target property does not accept | The generated rule is ignored by the browser | Keep static utility values aligned with the CSS property grammar |
Key files
| File | Why to read it |
|---|---|
| packages/…/theme.ts | Defines the shared theme model, token lookup, flags, namespace views, and keyframe storage. |
| packages/…/index.ts | Shows how CSS theme input is collected, merged, emitted, and connected to compilation. |
| packages/…/design-system.ts | Shows how the theme becomes the value and use-tracking service for utility generation. |
| packages/…/css-functions.ts | Defines theme-aware CSS functions and their resolution rules. |
| packages/…/utilities.ts | Shows how utility families map candidate values to ordered theme namespaces and valid static CSS values. |
| packages/…/theme.css | Defines the default token scales and deprecated compatibility tokens. |
| packages/…/apply-config-to-theme.ts | Converts legacy JavaScript theme values into CSS token names and defaults. |
| packages/…/apply-compat-hooks.ts | Connects legacy config and plugins to the current design system. |