The design system topic covers how the theme manages visual identity through a structured token architecture. Rather than scattering color values and spacing numbers across component files, the theme uses a three-layer system that separates raw values from their semantic meaning and from the utility framework that consumes them.
Who this is for
- Implementors — customizing a site’s visual identity by overriding tokens at the right layer, without touching component code.
- Developers — understanding the token contract so new components consume tokens correctly and remain themeable.
- AI agents — generating styles that use semantic tokens (
--st-*) rather than raw values, ensuring generated code is theme-compatible.
Key concepts
- Three-layer model — visual properties flow through three layers: primitive tokens (
--pt-*) define raw values, semantic tokens (--st-*) assign meaning to those values, and the Tailwind@themebridge exposes semantic tokens as utility classes. - Components consume semantic tokens — components never reference primitive tokens or raw color values directly. They use
--st-*tokens, which makes them automatically responsive to theme changes. - Site-level overrides — sites customize their appearance by overriding primitive or semantic tokens in
src/site/styles/. The core token files remain untouched, keeping theme upgrades clean. - Lint enforcement — token usage rules are enforced by the validation pipeline. Components that bypass the token system or reference wrong-layer tokens fail the lint check.
In This Topic
- Design Tokens — Reference for the three-layer design token architecture — naming conventions, layer model, file organization, override mechanism, and lint rules.
- Override Precedence — Reference for the CSS token override contract — which tokens go in which site files, validation checks, error and warning behavior, and how to declare intentionally new site tokens.
- Theming How-To — How to customize design tokens for a client site — creating theme overrides, token naming conventions, and testing changes.