Key insights
- Name tokens by meaning, not value.
color-primarysurvives a rebrand, whilecolor-blue-500becomes a lie the moment blue turns teal. - Structure tokens in three layers — primitives (raw values), semantic (meaning), and component (usage) — each referencing the layer above.
- Change one primitive and it cascades through every component that points to it: one edit instead of 47 hunted-down values.
- Define a scale and snap everything to it. A stray 13px padding or 17px gap collapses to 12 and 16, so consistency stops being a guess.
- Dark mode isn't inverting colors — it's swapping one token set for another. Same components, alias tokens, a completely different feel.
- Tokens are your single source of truth for color, spacing, and type — the design system is only as strong as they are.
Do / Don't
- Do: Name tokens by role —
color-primary,spacing-md,font-body— so they hold through a rebrand - Do: Layer tokens primitives → semantic → component so a single change cascades
- Do: Snap arbitrary spacing and font sizes onto a fixed scale
- Don't: Bake literal values into names like
color-blue-500orspacing-16 - Don't: Treat dark mode as inverting colors instead of swapping token sets
- Don't: Hardcode raw values across components instead of referencing tokens
