Tokens named `blue-500` are a trap. Six months from now marketing decides the brand is green, and now every component that hard-coded `blue-500` is broken in a way your linter can't catch. We've inherited three codebases this year where a 'simple rebrand' turned into a six-week refactor for exactly this reason.
Semantic naming is the whole game
Use names that describe the role, not the value: `primary`, `surface`, `surface-elevated`, `ink`, `ink-muted`, `border`, `border-strong`, `accent`, `danger`. Now a rebrand is one file. Change the value of `primary` from `oklch(0.55 0.18 240)` to `oklch(0.55 0.15 150)` and the entire app turns from blue to green without touching a single component file.
We've shipped four full rebrands this year using this approach. The longest one took eleven hours, including QA. The shortest took ninety minutes.
The two-token rule
Every semantic colour comes in pairs: a background and a matching foreground. `primary` is always paired with `primary-foreground`. `surface` with `ink`. `danger` with `danger-foreground`. Components only ever consume the pair together, never one without the other. This is what guarantees contrast survives a rebrand — when you swap `primary` from blue to a much darker green, the paired `primary-foreground` swaps from white to a chosen value that still passes WCAG AA.
Ship dark mode from day one, even if you only release light
The constraint is the point. Forcing yourself to define every token in both light and dark modes from day one surfaces every place where you cheated and used a hard-coded colour. If a component looks broken in dark mode, it's almost always because it referenced a value directly instead of a token. Catch it now, not the day marketing announces the dark theme.
A naming scheme that has survived four years
We use a three-part convention: `{role}-{variant}-{state?}`. So `surface`, `surface-elevated`, `surface-elevated-hover`. `ink`, `ink-muted`, `ink-inverse`. `border`, `border-strong`, `border-focus`. The variants stay constant across the design system, so once a developer learns the pattern they can guess the token name without checking the docs.
What to do this week
Open your styles file and search for any hex code or any colour name like `blue-`, `gray-`, `red-`. Every match is a future rebrand bug. Replace them one component at a time with semantic tokens. It's boring work but it's the cheapest insurance you'll ever buy against a marketing pivot.