What is the difference between primitive and semantic design tokens?

Primitive tokens store raw values (e.g., --color-blue-600: #2563eb). Semantic tokens reference primitives with a role-based name (e.g., --color-action: var(--color-blue-600)). Semantic tokens are what you audit for accessibility, because they represent the actual usage contract: "action color on action-surface must pass contrast."

Which design token format should I use?

For most web projects, CSS custom properties are the simplest option. If you use Tailwind, extend theme.colors in your tailwind.config. If you need cross-platform support (iOS, Android, web), use Style Dictionary. For design-to-dev handoff with Figma, use the Figma Tokens plugin JSON format.

How do design tokens help with dark mode accessibility?

Semantic tokens let you define a parallel dark-mode set where each color is re-tested against the dark surface. Rather than inverting colors, you verify that --color-text on --color-background still meets contrast in both light and dark contexts. The contrast checker tool supports testing both modes independently.

Design Tokens for Accessible Color Systems

What Are Design Tokens?

Design tokens are the atoms of your design system — named key-value pairs that represent design decisions. For color, they bridge the gap between raw hex values and semantic meaning.

Three-Tier Token Architecture

**Tier 1 — Primitive tokens** (raw values):


--color-blue-600: #2563eb;
--color-blue-50: #eff6ff;

**Tier 2 — Semantic tokens** (roles):


--color-action: var(--color-blue-600);
--color-action-surface: var(--color-blue-50);

**Tier 3 — Component tokens** (usage):


--button-bg: var(--color-action);

Baking In Accessibility

The key insight is to audit at the semantic tier, not the primitive tier. Instead of "does blue-600 pass on white?", ask "does our action color pass on our surface color?"

Create token pairs that are always tested together:

`--color-text` on `--color-background` → must be ≥ 4.5:1

`--color-text-secondary` on `--color-background` → must be ≥ 4.5:1

`--color-action` on `--color-action-surface` → must be ≥ 3:1 (UI component)

Export Formats

**Tailwind** — extend theme.colors with your semantic names

**CSS Variables** — use `:root` with optional dark-mode overrides

**W3C Design Tokens** — the emerging community standard JSON format

**Figma Tokens** — sync directly with the Figma Tokens plugin

**Style Dictionary** — transform tokens for any platform (iOS, Android, web)

Dark Mode Strategy

Don't just invert colors. Instead, create a parallel token set where each semantic color meets contrast requirements on the dark surface:


:root { --color-text: #1e293b; --color-background: #f8fafc; }
.dark { --color-text: #f1f5f9; --color-background: #0f172a; }

Test both modes independently with the contrast checker.