Design Tokens for Color — Complete Guide

What color design tokens are, how they differ from CSS variables, and how to build a token system that scales.

What Are Design Tokens?

A design token is a named value that stores a design decision — a color, a spacing value, a font size — so that it can be reused across design tools, code and documentation. Tokens are the "single source of truth" for design decisions in a design system.

For color specifically, tokens like --color-primary, --color-text-muted or --color-danger allow a single change to propagate everywhere — from CSS to Figma to mobile apps to print materials.

Design Tokens vs CSS Variables

These are often conflated, but they're different concepts:

  • CSS custom properties are the technical implementation — variables in CSS
  • Design tokens are the design abstraction — named values with meaning, exported to multiple platforms

A design token like "color-primary" might be implemented as a CSS variable in web, an Android resource in Kotlin, a color asset in iOS, and a color style in Figma. The token is the abstraction; the CSS variable is one implementation.

The Three Token Layers

Primitive Tokens

Raw values with no meaning. Examples: --blue-500: #155EEF, --gray-900: #15243B. These are the building blocks — never used directly in components.

Semantic Tokens

Named by their role: --color-primary, --color-text, --color-danger. These reference primitive tokens and are what components actually use.

Component Tokens

Scoped to specific components: --button-primary-bg, --card-border-color. Optional — most design systems skip this layer.

Why the Layer Distinction Matters

Primitives provide flexibility (many possible colors). Semantics provide meaning (which color to use when). Components provide scoping (which color belongs to which component).

If you use primitives directly in components, changing a design decision requires updating many files. If you use semantic tokens, one change propagates everywhere.

Essential Color Tokens

Every design system needs at minimum these semantic tokens:

  • Primary — brand color, buttons, links
  • Primary Hover — hover state
  • Primary Active — active/pressed state
  • Secondary — supporting brand color
  • Accent — attention-grabbing color for CTAs
  • Background — page background
  • Surface — cards and panels
  • Border — dividers and outlines
  • Text — body and heading text
  • Text Muted — secondary text
  • Text Inverse — text on colored surfaces
  • Success — success messages and states
  • Warning — warning messages and states
  • Danger — errors and destructive actions
  • Info — informational messages

Naming Conventions

Good token names are:

  • Semantic — describe the role, not the color
  • Consistent — same structure across all tokens
  • Hierarchical — color-text-muted not muted-text-color
  • Stable — do not rename after adoption

Avoid tokens named after colors (--blue) — they become meaningless when you want to change the brand color to green.

Implementation Example

/* Primitives */
:root {
  --blue-500: #155EEF;
  --blue-600: #0F4BD1;
  --gray-900: #15243B;
  --gray-100: #F8FAFF;
  --white: #FFFFFF;
  --green-500: #0F9D58;
  --red-500: #D93025;
}

/* Semantic */
:root {
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-600);
  --color-text: var(--gray-900);
  --color-background: var(--gray-100);
  --color-surface: var(--white);
  --color-success: var(--green-500);
  --color-danger: var(--red-500);
}

/* Components use semantic tokens */
.button-primary {
  background: var(--color-primary);
  color: var(--color-surface);
}
.button-primary:hover {
  background: var(--color-primary-hover);
}

Token Tools and Formats

  • Style Dictionary — Amazon's open-source token build tool
  • Tokens Studio — Figma plugin for token management
  • W3C Design Tokens Format — emerging standard for token files
  • Theo — Salesforce's token tool
  • CSS custom properties — direct implementation for web

Theming With Tokens

Tokens enable theming (dark mode, brand variants, white-labeling) by overriding semantic values without touching primitives or components:

[data-theme="dark"] {
  --color-text: var(--gray-100);
  --color-background: var(--gray-900);
}

Building Your Color Token System

  1. Define primitives from your base color (50-900 scale)
  2. Identify semantic roles needed for your product
  3. Map primitives to semantic tokens
  4. Document the system
  5. Export to Figma, code and mobile platforms
  6. Set up theming via semantic overrides

Generate Your Tokens

Use our Design Token Generator or CSS Variables Generator to build a complete token system from any base color.

Frequently Asked Questions

Related Articles