Creating Scalable Color Tokens for Design Systems

The first design system I built shipped with exactly one mistake that haunted everything afterward: we used blue-500 directly in component code. Buttons were blue-500. Links were blue-500. The focus ring was blue-500. It felt clean and DRY. Then marketing rebranded from blue to teal, and we spent two sprints chasing every literal hex reference across forty repositories — and still missed a few, because some had been hardcoded as #3B82F6 rather than the variable. That whole episode could have been a one-line change. The reason it wasn't is the entire reason design system color tokens exist.

A color token is just a named reference to a color value. But the value of tokens isn't in the naming — it's in the layers of naming, and in being disciplined about which layer a component is allowed to touch. Get the layering right and a rebrand, a dark mode launch, or a contrast fix becomes a small, contained change. Get it wrong and you get the forty-repo cleanup.

Three layers: primitive, semantic, component

The mental model that has held up across every system I've worked on is a three-tier hierarchy. Each tier references the one below it, and components are only ever allowed to consume the top tier.

• Primitive tokens (also called base or global tokens) are your raw palette. blue-500: #3B82F6, gray-900: #111827, red-600: #DC2626. They describe what the color is and nothing about where it's used. A primitive should never appear directly in a button's CSS.
• Semantic tokens describe intent — the job the color does. color-text-primary, color-bg-surface, color-border-default, color-action-primary, color-feedback-error. A semantic token points at a primitive: color-action-primary → blue-600.
• Component tokens are optional and describe a specific part of a specific component. button-primary-bg, card-border-color, input-focus-ring. They point at semantic tokens, not primitives.

Here's the rule that makes the whole thing work, and the one most teams skip: components reference semantic or component tokens, never primitives. The moment a button reaches past the semantic layer to grab blue-500 directly, you've reintroduced the forty-repo problem one component at a time.

Why bother with the semantic middle layer at all? Because it's the seam where theming happens. When you flip to dark mode, you don't repaint every component — you repoint a few dozen semantic tokens at different primitives. The components don't know anything changed. That indirection is the single highest-leverage decision in the entire system.

Build the scale before you name anything

Before semantics, you need primitives worth pointing at — and that means a numeric scale, conventionally 50 through 950. The convention popularized by Tailwind (50, 100, 200 … 900, 950) has effectively become the industry default, and it's worth adopting just so new engineers feel at home. 50 is the lightest tint, 500 is roughly the pure brand hue, 950 is nearly black.

The mistake beginners make is generating a scale by naively lightening and darkening in sRGB — adding white for tints, black for shades. You get muddy mid-tones and steps that don't feel evenly spaced, because perceived lightness isn't linear in RGB. A 400 ends up looking almost identical to a 500, while 700 to 800 is a cliff. The fix is to space your steps in a perceptual model. Tools that work in HSL get you most of the way; tools that use OKLCH (now well-supported in CSS) get you the rest, because OKLCH keeps perceived lightness consistent as hue changes. If you want to eyeball harmonious tints and shades quickly while you're prototyping a scale, the color palette generator is a fast way to see the relationships between hues before you commit them to tokens.

A few hard-won rules for scales:

• Anchor your scale to contrast, not aesthetics. Decide early which step is your "text on white" color and verify it hits the ratios you need. In most neutral ramps, 600 or 700 is where you cross 4.5:1 against white. Knowing that lets you write semantic rules like "body text uses gray-700" with confidence.
• Keep the same number of steps across every hue. If blue has a 950 and green stops at 900, your semantic mappings get irregular and dark mode becomes a special-case nightmare.
• Don't over-generate. Eleven steps per hue is plenty. I've seen teams ship twenty-step scales where half the steps are visually indistinguishable and nobody ever uses 425.

Naming: describe the job, not the look

The single most important naming principle is this: semantic and component tokens should name the purpose, never the appearance. A token called color-text-red breaks the day error text becomes orange — the name now lies. A token called color-feedback-error survives that change untouched, because "error" is still true regardless of which red (or orange) it resolves to.

A naming structure that scales reads from broad category to specific modifier, because it sorts and audits cleanly:

• category-property-variant-state
• color-bg-surface, color-bg-surface-raised, color-bg-surface-sunken
• color-action-primary, color-action-primary-hover, color-action-danger
• color-text-primary, color-text-secondary, color-text-disabled, color-text-on-action

That last one — color-text-on-action — is a token people forget and regret. When your action color is a saturated blue, text on that blue needs to be white or near-white, and that pairing has nothing to do with color-text-primary. Make it an explicit token or you'll watch engineers hardcode #FFFFFF onto buttons and then file accessibility bugs when someone introduces a light-yellow "warning" action.

For primitives, naming the appearance is correct and expected — blue-500 should describe what it is, because that's the whole point of the primitive layer. The "describe intent" rule applies above it.

Implementing with CSS custom properties

CSS custom properties are the natural home for tokens because they cascade and can be overridden by context — which is exactly how theming works. The pattern is two layers of variables: primitives defined once at the root, semantics defined at the root and re-defined under a theme selector.

Define primitives globally — --blue-600: #2563EB, --gray-900: #111827, and so on. Then map semantics to them: --color-action-primary: var(--blue-600) and --color-text-primary: var(--gray-900). Components only ever read the semantic variables: color: var(--color-text-primary). They never name a primitive and never name a hex code.

In Tailwind v4 this maps cleanly onto the new @theme directive, which both declares the tokens and generates utilities from them, exposing every token as a runtime CSS variable. You define --color-text-primary: var(--color-gray-900) inside @theme, use text-primary in markup, and override the variable under a .dark selector in your base layer. The official Tailwind theme variables documentation covers the mechanics, and the same two-layer discipline applies regardless of framework.

Dark mode is a token-mapping problem, not a color problem

The reason the semantic layer earns its keep is that dark mode becomes almost trivial once it exists. You do not touch a single component. You override the semantic tokens inside a .dark (or [data-theme="dark"]) scope so they resolve to different primitives.

In light mode, --color-bg-surface: var(--white) and --color-text-primary: var(--gray-900). In dark mode, under the .dark selector, --color-bg-surface: var(--gray-900) and --color-text-primary: var(--gray-100). Every component that reads color-bg-surface flips automatically, because the cascade does the work.

Two things that bite people here:

• Don't simply invert the scale. Pure-white text on pure-black (#000 on #FFF inverted) is harsh and causes halation — that smeary glow around text on OLED screens. Dark surfaces should be a dark gray like #121212 to #1A1A1A, and your brightest text a soft off-white rather than #FFFFFF. This is why your scale needs a real 950 and 50 rather than literal black and white at the ends.
• Desaturate accents for dark backgrounds. A blue-600 that looks confident on white can vibrate uncomfortably on a near-black surface. Dark themes usually point their action token at a lighter, slightly less saturated step — blue-400 instead of blue-600. Because this is one token remap, you can tune it globally in seconds.

The pitfalls that actually break at scale

After enough rebrands and theme launches, the failure modes rhyme:

• Leaking primitives into components. The original sin. Lint for it — a rule that forbids primitive token names and raw hex in component files is worth writing on day one.
• Semantic tokens that secretly encode a value. color-blue-action is a primitive wearing a semantic costume. If the name contains a hue, it's not really semantic, and it'll break on rebrand.
• Skipping the semantic layer "to move fast." Components bound straight to primitives feel fine until your first theme. Then you're refactoring under deadline pressure — the most expensive time to do it.
• Contrast tested only in light mode. A pairing that passes 4.5:1 on white can fail on a dark surface, and vice versa. Every semantic text-on-background pair needs checking in every theme. The WCAG thresholds are 4.5:1 for normal text and 3:1 for large text and UI components, per the W3C WCAG contrast guidance — and your token system is where you should bake those guarantees in, not where you should discover violations.
• Too many tokens. A system with four hundred semantic tokens is as unusable as one with four. If two tokens always resolve to the same value and always will, they're one token. Add specificity only when a real divergence appears.

The honest summary is that tokens don't make color decisions for you — they make color decisions cheap to change. The structure is what buys you the ability to rebrand on a Friday, ship dark mode in a sprint, and fix a contrast bug in one line instead of forty repositories. Spend your effort on the semantic layer and the naming, keep components honest about which tier they touch, and the system will absorb changes you can't even predict yet.