Design Tokens Strategy: Naming, Layers, and Scaling
Design tokens are the atomic units of a design system, and bad token architecture dooms the system. Here is the strategy I use. Design tokens are the named values that store design decisions: colors, spacing, typography, radii, shadows. They are the atomic units of a design system, and the architecture of the token set determines whether the system scales or collapses under its own complexity. I have built token systems that were elegant and unused, and ones that were pragmatic and widely adopted. The difference was the architecture. Here is the token strategy I use now. Three Layers: Primitive, Semantic, Component The most important principle is layering. A flat list of tokens, like color-blue-500 and spacing-4, mixes levels of abstraction and forces every consumer to know implementation details. I use three layers: primitive, semantic, and component. Primitives are raw values with no meaning: color-blue-500 is #3b82f6, spacing-4 is 16px, radius-md is 8px. These are the building blocks but should rarely be used directly in components. Semantic tokens give meaning to primitives: color-text-primary references color-gray-900, color-surface-background references color-gray-50, spacing-element-gap references spacing-4. Component tokens are specific to a component: button-background-primary references color-primary, button-padding-x references spacing-element-gap. More guides are on the Spark Blog.