Multi-Theme and Multi-Brand Token Architecture

A theme changes the color mode of the same brand (light and dark versions of the same product). A brand is a different visual identity — the same design system components rendered with different colors, typography, and spacing to serve different products or customers. Both use the same token architecture but at different abstraction levels.

Primitive tokens are the complete palette of raw values available to the system. They include every color step (color-blue-50 through color-blue-900), every spacing unit, every font size. Primitive tokens are never used directly in components — they are only referenced by semantic tokens. The palette is defined once and shared across all themes and brands.

Semantic tokens express intent: color-background-page, color-text-primary, color-action-primary. Each semantic token references a primitive token value appropriate for the current theme. Components are built against semantic tokens exclusively. This is the layer where theming happens.

In the light theme: color-background-page references color-white, color-text-primary references color-gray-900, color-action-primary references color-blue-500. These mappings are defined in a theme-specific token file that overrides the semantic layer for the light context.

In the dark theme: color-background-page references color-gray-950, color-text-primary references color-gray-50, color-action-primary references color-blue-400 (slightly lighter for contrast on dark backgrounds). Only the semantic mappings change — the primitive palette and all components remain unchanged.

Brand A uses blue as primary (color-action-primary: {color-blue-500}). Brand B uses green (color-action-primary: {color-green-500}). The button component reads var(--color-action-primary) — it is completely unaware of which brand is active. Brand overrides only change semantic token mappings, never component code.

CSS custom properties make runtime theme switching trivial. Store the current theme in a data attribute: document.documentElement.setAttribute('data-theme', 'dark'). CSS rules override semantic tokens under [data-theme="dark"]. The browser resolves all var() references to the new values immediately — zero JavaScript re-rendering required.

For different brands served as separate deployments, use build-time theming: generate separate CSS token files per brand with Style Dictionary, and load the correct brand CSS at application startup. This approach is appropriate when the brand is determined at deploy time (different domains, subdomains, or whitelabel instances), not at user interaction time.

A multi-brand, multi-theme system requires a two-dimensional matrix: Brand A Light, Brand A Dark, Brand B Light, Brand B Dark. CSS custom properties handle this elegantly with nested selectors: [data-brand="a"][data-theme="dark"] overrides semantic tokens for that specific combination. Four combinations are four CSS blocks, not four codebases.

As the design system evolves, tokens are added, renamed, or removed. Version control tokens in the same repository as code. When deprecating a token, keep the old name as an alias pointing to the new name for one release cycle, add a deprecation comment, and update consuming code. Coordinate token changes across design and engineering through a structured changelog.

Governance defines who can add or change tokens and what review process is required. Primitive tokens require design team approval. Semantic tokens require both design and engineering review. Component tokens can be managed by the component owner. Without this governance, duplicate tokens emerge and the "single source of truth" guarantee breaks down.

Why should components reference semantic tokens instead of primitive tokens?

Themes change color modes within a brand; brands are different visual identities. Primitive tokens are the raw palette, semantic tokens express meaning and enable theming. Components use only semantic tokens. Dark mode and brand overrides change only semantic token mappings — components are unchanged. Runtime theming uses CSS custom properties with [data-theme] selectors; build-time branding generates separate CSS per brand. Token governance and versioning keep the system consistent as it evolves.