Naming Colors in a Design System: Semantic vs Numeric vs Functional

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-brand for text that sits on top of brand backgrounds.

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.