The fastest way to end up with a broken design system is to name your tokens after what they look like. Blue 500 is a description, not a decision. The day a designer changes the brand blue, or the day you ship dark mode, every one of those names becomes a lie.
Name the job
Text on surface. Border subtle. Background raised. These names survive a rebrand because they describe the role the colour plays, not the colour itself. When the value changes, the name stays true, and nobody has to hunt through the codebase deciding whether this particular blue was the brand blue or just a blue.
One value per role, per theme
Every semantic token needs a value in each theme you support. If you cannot answer what a token becomes in dark mode, the token is not finished. The gaps are where the bugs live: the one hardcoded hex in a testimonial section that turns white text into white on white.
Keep the ramp private
You still need the raw ramp. Keep it as the layer underneath, referenced only by semantic tokens, and never used directly in a component. If a component reaches past the semantic layer, that is the review comment.
This is duller than picking colours. It is also the difference between a system that survives its second year and one that gets rebuilt.
