Naming Colors in a Design System: Semantic vs Numeric vs Functional
brand-500, primary, action-base, accent-strong: the same color, four naming schools, very different futures. A practical guide to picking names that survive a rebrand.
Most token systems collapse not because the colors are wrong but because the names are. A name is a contract between design, engineering, and your future self. Pick the wrong contract and every rebrand becomes a global find-and-replace.
The four schools
- Literal -
blue-500,red-700. Easy to scan, impossible to rebrand. Tailwind's default. - Numeric scale -
brand-500,brand-700. Better; the number survives. But still leaks the implementation (why 500, not 6?). - Semantic -
action-primary,surface-raised,text-muted. Describes the role, not the color. Best for product UI. - Functional + reference -
color.text.primary={color.brand.700}. A two-tier system. Reference tokens hold the raw values; functional tokens hold the meanings.
The two-tier rule
The healthiest systems use two tiers:
- Reference layer - your numeric ramps (
brand-50...brand-950). Generated, never used directly in components. - Semantic layer - your meaningful aliases (
--surface,--text-primary). Components only consume these.
When the brand color shifts, you regenerate the reference layer once. The semantic layer keeps its names. Components don't change.
Naming patterns that scale
- Role + variant.
button.primary.bg,button.primary.bg.hover. - Surface levels.
surface.default,surface.raised,surface.sunken. - State suffixes.
...hover,...active,...disabled. - Polarity hints.
text.on-brandfor text that sits on top ofbrandbackgrounds.
Names to avoid
--green-button- bakes the color into the name. The day you rebrand to teal, every developer suddenly has a "green" teal button.--brand-2,--brand-3- meaningless ordinals.--c1,--c2- cryptic shorthand. Grep-hostile.
Migrating without pain
Already shipped with literal names? You can layer in semantic tokens incrementally. Add the new name, point it at the existing literal, migrate components one at a time, then retire the literal. Our Design Tokens exporter ships both layers for any palette so you can adopt the pattern without rebuilding everything.
Generate a complete two-tier token set from your brand color in Design System, then export it for Tailwind, Style Dictionary, or W3C DTCG.