A primitive token is a raw value with no opinion about where it is used: blue-600, gray-900, space-4. A semantic token names a purpose and points at a primitive: color-action-bg, color-text-muted, space-inline.

Components only ever reference semantic tokens. That means re-theming is a matter of re-pointing semantics at a different set of primitives, not of editing components. A second brand, a dark mode and a high-contrast mode all fall out of the same mechanism.

Keep the primitive layer out of your application code. If a component can see --blue-600, the abstraction has already leaked.

Good token names survive a palette change. color-red becomes a lie the moment red is replaced by orange, and every consumer who trusted the name has to audit their code. color-danger keeps meaning whatever it points at.

The convention that works is category → role → variant, most general first: color, surface, border, text, space, font, radius, shadow, duration, easing. Within color, roles are action, text, surface, border, feedback; within a role, variants are primary, subtle, strong, muted.

Keep the set small. A scale with forty greys is not a system, it is a palette with commitment issues. If a designer asks for one more step, the answer is usually that one of the existing steps should be reused.

Keep the source of truth as JSON (or the W3C Design Tokens format) and generate everything else from it: CSS custom properties for the web, a TypeScript module for JavaScript and chart libraries, Swift and Kotlin objects for native, and a Figma plugin payload for design.

The generated CSS is committed or served, but it is never edited by hand. Hand-edited generated output is how a design system silently forks into four slightly different colour palettes.

Because components use semantic tokens, a theme is only a new set of semantic-to-primitive bindings. Switching theme means setting one attribute on the root: data-theme="dark". No component changes, no conditional class names, no duplicated CSS.

Default to the user preference with prefers-color-scheme and let them override it — a manual toggle that wins over the system preference, remembered in localStorage. When you add a theme, re-check contrast in it: a muted grey that reads well on paper can disappear on a dark surface.

A token rename breaks every consumer, exactly like renaming an exported function. Treat it the way you would treat any public API: ship the new name, keep the old one as an alias for one major version, then delete it in the next major with a codemod and a migration note.

Resist the urge to rename for tidiness. A rename with no user-visible benefit costs every downstream team a migration and buys the design system a cleaner file. If the old name is genuinely misleading — it says "red" but points at orange — that is worth doing, and worth doing slowly.

Run through this list once per theme and once per platform. It is short on purpose.