How to Name Color Tokens Clearly
A good color token name explains a role, not just a value. Raw outputs from a converter or image palette are useful for discovery, but they become much easier to maintain once they are renamed for what they actually do in the interface.
Why raw values are not enough
A token named after a literal value becomes harder to maintain the moment the color changes. A token such as `blue-500-overlay` may stop being blue over time, while a role-based name like `surface-selected` still makes sense even if the exact underlying value is adjusted later.
Name the role first
Useful token names usually answer one of these questions: Is this for text, surface, border, icon, accent, or feedback? Is it a default, subtle, selected, or strong variant? Those answers give teammates more context than the raw color string ever could.
The converted or extracted value still matters, but it belongs inside the token definition, not in the token name itself unless your system intentionally uses scale-based naming.
Practical examples
- `text-primary` is clearer than `navy-900` when the role matters more than the hue label.
- `surface-overlay-strong` is clearer than `rgba-blue-20` when the token is reused across states.
- `accent-brand` is easier to discuss in handoff than a raw converted value copied into a document.