Structural vs. Thematic Tokens: Job vs. Value

WHY IT EXISTS: Design systems start with a simple problem: a button needs a color. If you hardcode hex codes inside components, changing the brand palette means opening dozens of files and praying you do not miss one. Token systems were invented to centralize values, but early flat token lists only renamed the hex code without separating what a color does from what it is. That meant dark mode, white-labeling, or a rebrand still required global find-and-replace surgery. Structural and thematic tokens split the concern so the intent of a color survives even when the underlying palette changes.

THE MENTAL MODEL: Think of structural tokens as job titles and thematic tokens as the people filling those jobs. A structural token like color-background-primary describes the role: this is the main surface color. A thematic token like color-blue-500 describes the actual paint in the can. You hire the paint for the job by mapping the structural token to the thematic token in a theme file. When the brand changes, you swap the thematic assignment, not the component code.

HOW IT WORKS: In code, you define two layers. The thematic layer holds your primitive palette: raw colors, spacing scales, and font stacks. The structural layer aliases those primitives to semantic names that match UI patterns. Your components consume only structural tokens. A theme object or CSS custom property file connects the two, so color-background-primary resolves to color-blue-500 in the default theme and to color-gray-900 in dark mode. This indirection is a single point of change.

WHEN TO USE IT: Use this split when you support multiple themes, such as light and dark modes, or when you maintain a multi-brand component library where the same card component must render in Brand A blue and Brand B coral. It also pays off in large codebases where designers and engineers need to talk about intent rather than values. If your product will never retheme and has one palette, the extra layer is overhead.

WHEN NOT TO USE IT: Do not add structural tokens to a tiny side project that has one theme and three components. The abstraction earns its keep only when the cost of a global color hunt exceeds the cost of maintaining the mapping layer. Also avoid over-engineering by creating structural tokens for one-off decorative elements that never repeat; if a gradient only appears in a single marketing hero, it does not need a semantic alias.

ONE CANONICAL EXAMPLE: Imagine a button component that uses color-background-primary for its fill. In the default theme, that structural token points to color-blue-500. In dark mode, the same structural token points to color-blue-400 so the button stays accessible against a dark surface. If you had used color-blue-500 directly in the button, dark mode would require overriding the component or creating a dark variant. With structural tokens, the button is theme-agnostic and the theme file owns the decision.