Design Systems

Design Tokens

The atomic values of a design system — colors, spacing, typography, and more — stored as named variables for consistency at scale.

#tokens#variables#CSS variables#design system#consistency#theming

What is it?

Design tokens are the named, stored values that represent the atomic decisions of a design system — colors, typography scales, spacing increments, border radii, shadows, and motion values. They are the bridge between design tools (Figma) and code (CSS/JS), ensuring that the same values are used consistently across all platforms and contexts.

Why it matters

Without tokens, teams use hard-coded values that diverge over time. One developer uses #2563eb, another uses #1d4ed8 — both "blue," but inconsistent. Tokens create a single source of truth. When a brand color changes, updating one token updates the entire product. Tokens also enable theming — dark mode, white-label, and accessibility overrides become straightforward.

Best Practices

Token hierarchy: primitive tokens (raw values) → semantic tokens (meaning-based) → component tokens (component-specific).
Semantic tokens: --color-brand-primary instead of --color-blue-500. The token name communicates intent, not just value.
Naming convention: [category]-[property]-[variant]-[state]: --color-button-primary-hover.
Separate primitive color palette from semantic color usage: --palette-blue-600 → --color-action-primary.
Spacing tokens: use a consistent scale (4, 8, 12, 16, 24, 32, 48, 64) and give each a name (--space-4, --space-8).
Typography tokens: size, weight, line-height, and letter-spacing as named tokens.
Motion tokens: duration-fast (150ms), duration-moderate (300ms), easing-standard, easing-decelerate.
Shadow tokens: shadow-sm, shadow-md, shadow-lg — not hard-coded rgba values.
Document every token with its intended use — tokens without documentation get misused.
Use CSS custom properties (CSS variables) as the implementation layer — they work across frameworks.

Common Mistakes

Hard-coding values directly in component styles — breaks the token contract.
Too many tokens — hundreds of barely-differentiated tokens are harder to use than 20 well-defined ones.
Purely visual token names: --color-blue — should be --color-action-primary.
Tokens without documentation — developers use the wrong token for the wrong context.
No dark mode semantic tokens — semantic tokens should map to the right primitive per theme.
Tokens for one platform only — good tokens work across iOS, Android, and web.

Checklist

Primitive tokens defined for: colors, spacing, typography, radius, shadow, motion

Semantic tokens map primitives to intent (not to visual value)

Naming convention is consistent and documented

Dark mode semantic tokens exist and map to appropriate primitives

Tokens are implemented as CSS custom properties

Every token has a documented intended use

Spacing scale is consistent (4px base grid)

No hard-coded values in component styles

Tokens are shared between Figma and code (Figma Variables or Style Dictionary)

Research & Theory

Style Dictionary (Amazon)

Open-source token transformation tool by Amazon. Takes a single token JSON source and outputs platform-specific formats (CSS, iOS, Android, React Native).

Why it's relevant

Style Dictionary is the industry standard for multi-platform token management.

Real-World Examples

GitHub Primer

Primer's token system uses functional names (fg.default, bg.subtle, border.default). Clear semantic meaning. Open source and extensively documented.

Radix UI

Token system with semantic color scales, dark mode built in, accessibility-tested contrast ratios. Used by many design systems as a foundation.

Stripe

Stripe's internal design system uses tokens to maintain consistency across web, mobile, and dashboard products. Strict token naming enforced via linting.