The Ultimate Guide to Design Tokens

What Are Design Tokens?

The building blocks of every modern design system.

Design tokens are the atomic building blocks of a design system. They store visual design decisions — colors, typography, spacing, shadows, motion, and more — as platform-agnostic data rather than hard-coded values. Think of them as a single source of truth that bridges design tools and code.

The term was coined by Salesforce in 2014 when building the Lightning Design System. They needed a way to keep their design language consistent across web, iOS, Android, and React Native — all from one set of definitions. The concept has since been adopted by virtually every major design system.

The Variable Analogy

Without tokens

color: #3B82F6;

Hard-coded in 47 files. Change one, miss 46.

With CSS variables

color: var(--brand-blue);

Better! But only works for web, and names lack intent.

With design tokens

color: {color.action.primary}

Platform-agnostic, semantic, single source of truth.

Consistency

Every button, card, and heading uses the same values. Change a token once and it propagates everywhere — across web, mobile, and design tools.

Scalability

Add a dark theme, a high-contrast mode, or a brand refresh by swapping token values — without touching component code.

Multi-platform

Define tokens once in JSON, then generate CSS, SCSS, Swift, Kotlin, Compose, and any other format your team needs.

Speed

Designers change a Figma variable, it syncs to code via tokens. No more manually translating specs into CSS values.

Token Taxonomy

Every visual property your system needs to control.

Design tokens cover every visual property in your design system. Here is a comprehensive breakdown of token types, what they control, and examples of each.

Color

Brand colors, background colors, text colors, border colors, status colors (success, warning, error), and color scales.

Typography

Font families, font sizes, line heights, letter spacing, and font weights. Often organized into a type scale (xs through 5xl).

xs — 12px

sm — 14px

md — 16px

lg — 18px

Spacing

Padding, margin, gap, and layout spacing. Typically uses a consistent scale (4, 8, 12, 16, 24, 32, 48, 64).

Border Radius

Corner rounding values, from sharp (0) to fully rounded (9999px). Most systems define 4-6 radius tokens.

Elevation

Box shadows and z-index layers that create depth. Usually 3-5 levels from subtle to prominent.

Motion

Animation durations (100ms, 200ms, 300ms), easing curves (ease-in-out, spring), and transition properties.

duration.fast → 100ms

duration.normal → 200ms

easing.standard → cubic-bezier(0.4, 0, 0.2, 1)

Less common but valuable token types

Opacity — Transparency levels for overlays, disabled states, hover effects

Z-index — Stacking context values (dropdown, modal, tooltip, toast)

Border width — Stroke thicknesses (1px, 2px, 3px)

Breakpoints — Responsive design thresholds (sm, md, lg, xl)

Grid — Column counts, gutter widths, max-widths

Asset references — Icon sets, illustration styles, image treatments

The Three Tiers of Design Tokens

From raw values to component-specific decisions.

Most mature design systems organize tokens into three tiers. Each tier adds a layer of abstraction, making your system more flexible and maintainable. Hover over each tier to explore.

Tier 1

Global / Primitive

Raw values with no implied usage. Think of these as your design palette — the complete set of options.

color.blue.500#3B82F6

color.neutral.900#171717

size.spacing.164rem

font.weight.semibold600

Tier 2

Alias / Semantic

Purpose-driven names that reference primitives. These encode intent — what a value is used for.

color.action.primary{color.blue.500}

color.text.default{color.neutral.900}

spacing.page.gutter{size.spacing.16}

font.heading.weight{font.weight.semibold}

Tier 3

Component

Scoped to specific UI components. These are the most specific tokens and reference alias tokens.

button.primary.bg{color.action.primary}

button.primary.text{color.text.inverse}

card.padding{spacing.page.gutter}

heading.h1.weight{font.heading.weight}

How tiers enable theming

The power of tiers becomes clear when you need to support multiple themes. In a dark theme, you keep the same alias and component tokens but swap which primitives they point to:

Light Theme

color.bg.default → {color.white}     → #FFFFFF
color.text.default → {color.gray.900} → #111827
color.action.primary → {color.blue.600} → #2563EB

Dark Theme

color.bg.default → {color.gray.950}  → #030712
color.text.default → {color.gray.100} → #F3F4F6
color.action.primary → {color.blue.400} → #60A5FA

Naming Conventions

The difference between a system people love and one they abandon.

Good token names are the difference between a system people love and one they abandon. Names should be predictable, scannable, and self-documenting. Explore the most common conventions below.

CTI (Category–Type–Item)

The most popular convention for design tokens. Organizes tokens in a hierarchical taxonomy from broad category to specific item.

Pattern{category}.{type}.{item}

Examples

color.background.primarysize.font.heading-1size.spacing.mediumcolor.border.interactive

Used by

Style DictionarySalesforce Lightning

Naming principles that always apply

Name for purpose, not appearance: color.action.primary not color.blue
Use consistent delimiters (dots, dashes, or slashes — pick one)
Include state information when relevant: default, hover, active, disabled, focus
Document the intent of each token in your token spec

Don't embed raw values in names: color.blue500
Don't mix naming conventions within the same tier
Don't use abbreviations that aren't universally understood
Don't use ordinal numbers: spacing.1, spacing.2

Interactive Token Playground

See how token values shape a UI in real time.

Adjust the tokens below and watch the preview update in real time. Try the presets to see how the same component structure can feel completely different just by changing token values. The generated code is ready to copy into your project.

Presets

Color Tokens

Primary#3B82F6

Surface#FFFFFF

Text#111827

Layout Tokens

Border Radius: 12px

Spacing: 24px

Typography Tokens

Font Size: 15px

Font Weight

Shadow Token

Live Preview

Card Heading

This preview updates in real time as you adjust the design tokens. Every visual property is driven by token values.

Badge

Tag

Generated CSS Custom Properties

:root {
  --color-primary: #3B82F6;
--color-surface: #FFFFFF;
--color-text: #111827;
--radius: 12px;
--spacing: 24px;
--font-size: 15px;
--font-weight: 500;
--shadow: 0 4px 12px rgba(0,0,0,0.10);
}

Token Formats & Platform Output

One definition, every platform.

Design tokens are defined in a platform-agnostic format (usually JSON) and then transformed into platform-specific outputs. The W3C Design Tokens Community Group (DTCG) is standardizing a universal format. Below are the same token set expressed in different formats.

/* CSS Custom Properties */
:root {
  --color-primary: #3B82F6;
  --color-primary-hover: #2563EB;
  --color-surface: #FFFFFF;
  --color-text: #111827;
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 16px;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --font-size-sm: 0.875rem;
  --font-size-md: 1rem;
  --font-size-lg: 1.25rem;
  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.07);
}

The W3C Design Tokens Format (DTCG)

The W3C DTCG specification is the emerging standard for design token files. Key features include:

$value — The token's value (replaces "value" from earlier drafts)
$type — Declares the token type: color, dimension, fontFamily, fontWeight, duration, cubicBezier, shadow, etc.
$description — Human-readable description of the token's intent
References — Use {color.blue.500} syntax to create alias tokens that point to other tokens
Grouping — Nest tokens in a hierarchy using JSON objects

Design Tokens in the Wild

How the biggest companies structure their tokens.

The best way to learn is from existing design systems. Here's how the biggest companies structure their tokens. Click each system to explore details.

Tools & Ecosystem

From Figma to production in an automated pipeline.

A healthy design token workflow connects design tools, token definitions, and code output. Here are the key tools in the ecosystem.

Token build & transformation tools

Style Dictionary

by Amazon · Open Source

The most popular token build tool. Reads JSON/JSONC token files and transforms them into any platform format via a plugin system. Supports the W3C DTCG format.

styledictionary.com

Token Transformer

by Tokens Studio · Open Source

Converts Tokens Studio for Figma output into Style Dictionary compatible format. Handles references, math operations, and composite tokens.

sd-transforms on GitHub

Design tool integration

Figma Variables

Built-in · Figma

Native variable system supporting color, number, string, and boolean types. Modes (light/dark) and scoping (which properties a variable can bind to) built in.

Figma Variables Guide

Tokens Studio for Figma

Plugin · Tokens Studio

Advanced Figma plugin for managing design tokens with Git sync, multi-file token sets, theming, math operations, and direct export to Style Dictionary format.

tokens.studio

Typical token workflow

Design in FigmaVariables & styles

Export as JSONTokens Studio / REST API

TransformStyle Dictionary

Output to platformsCSS, iOS, Android, etc.

Consume in codeComponents & themes

Best Practices

Patterns from dozens of production design systems.

After studying dozens of production design systems, here are the practices that separate good token systems from great ones.

Do

Start with a small set of global tokens and grow gradually. You can always add more — removing tokens is painful.
Use semantic tokens for theming. Component code should reference alias tokens, not primitives.
Version your tokens and treat token changes like API changes. Breaking changes need migration paths.
Document each token with its intended use case. A token named color.feedback.warning.bg is clearer with a description like "Background for warning banners and inline alerts."
Automate your token pipeline: Figma → JSON → build tool → code output. Manual steps introduce drift.
Validate tokens in CI. Lint for missing references, unused tokens, contrast ratios, and naming violations.
Create a living reference page (like this one!) that shows token values and their visual output side by side.

Don't

Don't create a token for every single CSS property. Tokens are for design decisions, not exhaustive CSS mappings.
Don't skip the alias tier and go straight from primitives to components. You'll lose the ability to theme.
Don't use token names that describe the value: color.blue-500 breaks when your brand changes to purple.
Don't mix token formats in the same project. Pick one source format (JSON, YAML) and generate all others.
Don't change token values without communication. Token changes can ripple across dozens of components.
Don't design your token architecture around a specific tool. Tools change; a sound architecture endures.
Don't conflate design tokens with a component library. Tokens feed components, but they're a separate concern.

Token Maturity Model

Most teams evolve their token practice over time. Here's a rough maturity model to help you gauge where you are and what to aim for next.

Ad-hoc

Hard-coded values scattered across CSS files. No shared vocabulary between design and engineering.

Variables

CSS custom properties or SCSS variables exist, but naming is inconsistent. No multi-platform output.

Structured

Tokens defined in JSON with clear naming conventions. Build tool generates platform outputs. Single tier (global only).

Semantic

Multi-tier tokens (global + alias). Themes are supported by swapping alias mappings. Figma variables synced to code.

Systematic

Full three-tier architecture with component tokens. Automated pipeline from design to code. Token changes are versioned, linted, and reviewed in CI.