Design tokens that survive a rebrand
Name tokens after their job, not their appearance — and other decisions you only get to make once.
Every design system eventually meets a rebrand, a dark mode, or a high-contrast requirement. Whether that is a week of work or a quarter of it comes down to decisions made in the first fortnight of the token layer.
Three tiers, no shortcuts
Primitives hold raw values. Semantic tokens describe roles. Component tokens describe use. A component should never reach past the semantic layer, however tempting it is on a deadline. The moment a card reads a raw hex value, your theming story has a hole in it.
- Primitive: --grey-900, --orange-500
- Semantic: --color-surface, --color-accent, --color-fg-muted
- Component: --button-bg-hover, --card-border
Name by role, always
A token called --color-blue-primary becomes a lie the first time marketing goes green. --color-accent stays true. This sounds pedantic until you are running find-and-replace across four repositories at eleven at night.
If the name describes what it looks like, it will be wrong eventually. If it describes what it does, it will not.
Validate contrast in CI
Token changes are the highest-leverage way to break accessibility across an entire product in one commit. A contrast check on every semantic pair, running on every pull request, costs an afternoon to build and catches the mistake before a designer ever sees it.