token-architecture

Token Architecture

Design tokens are the single source of truth for visual decisions. They bridge design intent and code. This skill structures how tokens are named, layered, and distributed.

When to Use

• When starting a new design system
• When design-system-alignment identifies inconsistency
• When adding theming (dark mode, brand variants)
• When shipping across web, iOS, and Android

The Three-Layer Model

Layer 1: Global Tokens (the palette)

Raw values. Named by what they are, not what they do.

--color-green-500: #2D6B4F;
--space-4: 16px;
--radius-md: 12px;

These never appear in component CSS.

Layer 2: Semantic Tokens (the meaning)

Map global tokens to roles. Named by what they do.

--color-surface: var(--color-green-100);
--color-text-primary: var(--color-green-900);
--color-accent: var(--color-green-500);

Theming happens here — dark mode swaps semantic mappings, not global values.

Layer 3: Component Tokens (the specifics)

Map semantic tokens to component contexts. Optional but valuable at scale.

--button-bg: var(--color-accent);
--card-bg: var(--color-surface);

Naming Convention

--{category}-{property}-{variant}-{state}

Categories: color, space, font, radius, shadow, motion. Never use hex values in names or ambiguous abbreviations.

Theming

Dark mode is a semantic token remap:

[data-theme="dark"] {
  --color-surface: var(--color-grey-900);
  --color-text-primary: var(--color-grey-100);
}

Global tokens stay. Semantic tokens swap. Component tokens inherit.

Accessibility

• Always define foreground/background pairs together and verify AA contrast
• Motion tokens must include --motion-duration-none: 0ms for reduced-motion

What You Deliver

• Token file (CSS custom properties, JSON, or both) with all three layers
• Naming convention document
• Theme variants if applicable

Integration

• Informed by: design-lead, ui-composition
• Feeds into: design-builder, design-system-alignment