Categories of Design Tokens

WHY IT EXISTS A single flat list of tokens mixes raw values with usage decisions, so changing a theme forces edits everywhere and meaning gets lost. Categorizing tokens into tiers separates what a value is from what it means and where it applies, which is what makes large design systems maintainable and themeable.

THE MENTAL MODEL Picture three concentric layers. The innermost is primitives: the raw vocabulary of the system, like grey-100 through grey-900 or space-1 through space-8. The middle layer is semantic tokens: meaning assigned by aliasing a primitive, such as color-text-default or color-action-danger. The outer layer is component tokens: decisions scoped to one element, like button-bg-primary or card-padding. Each layer only references the one beneath it.

HOW IT WORKS Primitives carry literal values and almost never change. Semantic tokens never hold raw values; they point at primitives and carry intent, so a theme is essentially a different set of semantic mappings. Component tokens point at semantics, letting a specific element diverge without forking the palette. Tools resolve this chain at build time into platform outputs like CSS custom properties.

WHEN IT MATTERS Tiering matters most for multi-theme and multi-brand products, dark mode, and cross-platform delivery. It also helps onboarding, since the layer a token lives in signals how broadly a change will ripple. Small projects can collapse layers, but the structure is what prevents chaos at scale.

ONE CONCRETE EXAMPLE For dark mode, you keep all primitives identical and define a second set of semantic tokens: color-bg-surface aliases grey-50 in light mode and grey-900 in dark mode. Components reference only the semantic token, so flipping the theme swaps one layer while primitives and component names stay frozen.