Color Tokens

Named variables that map semantic color roles (like "primary button background") to specific color values in a design system.

What are Color Tokens?

Color tokens are named references to color values in a design system. Instead of using a raw hex value like #3B82F6 directly in code or design files, you use a token like color.button.primary.background, which maps to that hex value. Tokens create a semantic layer between the abstract color value and its intended use.

Tokens typically come in two layers: primitive tokens (the full color palette, e.g. blue.500 = #3B82F6) and semantic tokens (role-based, e.g. color.interactive.default = blue.500). Semantic tokens can be remapped for theming without changing every individual component.

Why are Color Tokens important?

Color tokens are what make design systems maintainable and themeable at scale. Without tokens, updating your brand's primary color means finding and replacing every hex value across your codebase. With tokens, you update one mapping and the change propagates everywhere.

Tokens also create alignment between design tools and code. When a designer and a developer both reference color.text.muted, they're both referring to the same value, reducing handoff ambiguity and preventing design drift.

How to implement Color Tokens

Step 1: Build your primitive palette: Define every color value you'll use, organized by hue and shade (e.g., gray.100 through gray.900, blue.50 through blue.950).

Step 2: Define semantic tokens: Map primitive values to semantic roles. Keep semantic tokens at the level of intent, not description:

color.background.page → gray.50
color.text.default → gray.900
color.text.muted → gray.500
color.border.subtle → gray.200
color.interactive.default → blue.600

Step 3: Apply tokens in code: In CSS, use custom properties (--color-background-page). In Tailwind, configure semantic colors in your theme. In Figma, use variables.

Step 4: Add theme-specific overrides: For dark mode, define a separate mapping where color.background.page maps to gray.950 instead.

Examples

A button component using tokens:

.button-primary {
  background: var(--color-interactive-default);
  color: var(--color-text-on-interactive);
  border-color: var(--color-border-interactive);
}

When the theme switches to dark mode, only the token values change. The component code stays identical.

Best practices

Name semantic tokens by their role, not their appearance (color.text.muted, not color.text.gray)
Keep the primitive and semantic layers separate. Never reference a raw hex value in component code
Document the intended use of each token inline. Tokens without documentation get misused
Avoid tokens for every possible shade. A token like color.background.secondary.hover.pressed becomes impossible to maintain

FAQs

Design tokens are the concept: named design decisions that can be shared across platforms (web, iOS, Android, design tools). CSS variables are one implementation of tokens in the browser. A design token system might generate CSS variables, Sass variables, Swift constants, and Figma variables from a single source of truth.

Granular enough to capture meaningful distinctions, but not so granular that every component gets its own token. A reasonable starting point for most products is 15-30 semantic color tokens covering backgrounds, text, borders, interactive states, and semantic states (success, warning, error). Adding more tokens should be driven by real theming needs.

Sparingly. Using CSS color-mix() or oklch(from var(--color) l c h / 50%) to generate opacity variants at runtime is often cleaner than defining a separate token for every opacity level. Define opacity tokens only when a specific opacity value appears consistently enough to warrant a named reference.