Semantic vs. Primitive Design Tokens

WHY IT EXISTS: Design systems need to scale without leaking raw values into components. If every button hardcodes a hex code, a rebrand or dark mode requires touching hundreds of files. Primitive tokens store the raw palette and scale, while semantic tokens decouple the intent from the implementation, letting you change the underlying value in one place without rewriting component code.

THE MENTAL MODEL: Think of primitives as the ingredients in a pantry and semantics as the recipe names. Flour and sugar are primitives; cake batter and bread dough are semantics. A recipe does not care which brand of flour you bought, only that it is the correct type. When the brand changes, the recipe still works.

HOW IT WORKS: Primitive tokens define the atomic values of your system. These are your colors at every shade, your type scale in fixed steps, your spacing increments, and your raw shadows. Semantic tokens reference those primitives to express purpose. For example, a primitive set might include --color-blue-500 and --color-red-500. A semantic layer would expose --color-text-link and --color-text-error, both pointing to primitives. In code, a button component uses --color-surface-primary, not --color-blue-500. If the brand shifts from blue to purple, you update the primitive reference inside the semantic token, and every button updates automatically without a single component file changing.

WHEN TO USE IT: Use primitive tokens when defining the base design language and global constants. Use semantic tokens inside components and layouts to express intent. Any system supporting multiple themes, brands, or modes should adopt semantic tokens. They are essential when the same primitive value must serve different roles in different contexts, such as a light gray used for both borders and disabled text but needing independent overrides later.

WHEN NOT TO USE IT: Avoid semantic tokens for one-off marketing pages or prototypes that will not evolve. Adding a full semantic layer too early creates indirection without benefit. Also, do not create semantic tokens that map one-to-one with primitives without meaningful abstraction, such as --color-red mapping only to --color-red-500, because that is just a longer name for the same thing and adds cognitive overhead.

ONE CANONICAL EXAMPLE: A design system supports light and dark mode. The primitive palette includes --color-gray-100 through --color-gray-900. The semantic token --color-surface-default maps to --color-gray-100 in light mode and --color-gray-900 in dark mode. A card component references --color-surface-default. When the user toggles themes, the card background inverts automatically because the component is bound to meaning, not to a specific shade.