Structural vs. Thematic Tokens: Job vs. Value
Structural tokens describe the role, like text-primary; thematic tokens describe the value, like blue-500. Split them so retheming does not require hunting hexes. The footgun is using only thematic tokens, which hardcodes intent and breaks dark mode.
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.
Interview question
If a button uses the thematic token blue-500 directly for its fill, what problem occurs when supporting dark mode?
- a.The structural mapping layer must be rebuilt for every component
- b.Each button needs an override or dark variant to change its colorCorrect
- c.The theme file loses its ability to map tokens across themes
- d.The blue-500 primitive must be changed to a different hex code globally
Why? this is the answer
The card explains that referencing a thematic token directly forces component-level overrides or dark variants, whereas structural tokens make components theme-agnostic. Distractor B seems plausible because retheming involves hunting hexes, but changing the primitive globally would alter every instance of blue-500, not just the button in dark mode.
Just read this? Test yourself on what you have been reading.
- #design systems
- #tokens
- #theming
- #frontend architecture
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on design systems — each one lists the topics its interview covers.
See open roles