Back to Playbook

Design Tokens

Methodology for storing design decisions as platform-agnostic data variables.

Why it matters

Design tokens are the single source of truth for your design system. Instead of hardcoding hex values or pixel sizes, you use tokens (like `color-primary` or `spacing-md`). This allows you to update the entire system across multiple platforms (Web, iOS, Android) by changing a single value.

Token Playground

Change the primitive values to see how they cascade through semantic aliases to update the UI components.

brand-500
16px
space-base
8px
radius-md
Token Cascade
brand-500 color-primary button-bg
Tokenized Card
This card uses the same tokens for spacing and radius, ensuring consistency across the UI.
Generated CSS

Token Tiers

Primitive (Global)

The raw values. E.g., `blue-500: #0066CC`. These are the building blocks of your palette.

Semantic (Alias)

Tokens with meaning. E.g., `color-action-primary: blue-500`. Describes *what* the color is for.

Component

Specific to a component. E.g., `button-bg-primary: color-action-primary`. Allows granular control.

Platform

The final output format. CSS variables for web, XML for Android, JSON for iOS.

Primitive vs. Semantic

Understanding the distinction between these two layers is key to a flexible system.

Primitive

What it is

Raw values that represent the available choices in your system. They have no inherent meaning.

blue-500: #2C6CB2 space-16: 16px
Semantic

What it does

Aliases that describe the intended use of a token. They reference primitive tokens.

color-action-primary: {blue-500} space-inset-md: {space-16}

Naming Conventions

A consistent naming scheme is critical for a scalable system. We recommend a structure that moves from general to specific.

category - type - item - state
Category
The core attribute (e.g., color, font, space).
Type
The element being styled (e.g., text, bg, border).
Item
The specific variation or role (e.g., primary, success, card).
State
The interaction state (e.g., hover, active, disabled).
Examples
color-bg-button-primary-hover space-inset-card-lg font-size-heading-xl

Aliasing Strategies

Aliasing allows you to change values in one place and have them propagate. Choosing the right depth of aliasing balances flexibility with complexity.

Direct (1-Level)

Semantic tokens point directly to primitive values. Simple and easy to maintain, but less flexible for complex theming.

$primary: $blue-500

Indirect (2-Level)

Component tokens point to semantic tokens, which point to primitives. Allows changing a component without affecting other elements using the same semantic color.

$btn-bg: $primary
$primary: $blue-500

Thematic (Contextual)

Tokens change value based on context (e.g., light/dark mode). Semantic tokens point to a theme-specific primitive.

$bg: $theme-bg
[Light] $theme-bg: $white
[Dark] $theme-bg: $gray-900

Platform Specifics

While tokens are defined once, they must be transformed to match the syntax conventions of each platform.

Web (CSS)
iOS (Swift)
Android (XML)
--color-primary
--space-md
--font-size-lg
colorPrimary
spaceMd
fontSizeLg
color_primary
space_md
font_size_lg

Theming

Design tokens make theming effortless. By swapping the values of your semantic tokens, you can completely change the look of your application without touching the markup.

Dark Mode

The most common theme. Simply redefine your semantic color tokens (e.g., bg-default) for a dark context.

Brand Themes

Support multiple sub-brands by swapping out brand-specific primitive tokens (e.g., brand-primary).

Density

Adjust spacing and sizing tokens to create "Compact" or "Comfortable" density modes for different user needs.

CSS Implementation
:root {
  --bg-default: #ffffff;
  --text-primary: #111827;
}

[data-theme="dark"] {
  --bg-default: #111827;
  --text-primary: #ffffff;
}

Tools & Management

Tokens Studio

A powerful Figma plugin that allows you to create, manage, and sync design tokens directly within your design files.

Style Dictionary

An Amazon-built build system that allows you to define styles once and use them for any platform or language.

Supernova

A design system platform that automates the handoff of design tokens and assets from Figma to code.

GitHub Actions

Automate the transformation and distribution of tokens whenever changes are pushed to your repository.

Versioning

Treat your design tokens as a product. Use semantic versioning to communicate changes and ensure stability for consumers.

Major (v1.0.0)

Breaking changes. Renaming tokens, removing tokens, or significantly changing a core value that affects layout.

Minor (v1.1.0)

New features. Adding new tokens (e.g., a new color ramp or spacing value) in a backward-compatible way.

Patch (v1.0.1)

Bug fixes. Tweaking a hex value to fix contrast or adjusting a border radius slightly.

Deprecation Strategy
v1.0 color-primary → Active
v2.0 color-brand-primary → Introduced (alias old token)
v3.0 color-primary → Removed

Documentation

Tokens are only useful if people know how to use them. Good documentation includes not just the value, but the *intent* behind the token.

color-text-subtle
var(--color-neutral-text-secondary)
#475467
Description

Used for secondary text, captions, and helper text that needs to recede from the primary content.

Usage
Metadata, timestamps, placeholders
Headings, primary body text

Governance

A clear governance model ensures your token system remains clean and scalable over time. Without it, you risk token bloat and inconsistency.

Ownership

Design Systems team owns the core tokens (primitives & semantics). Product teams can suggest changes but shouldn't modify them directly.

Contribution

Establish a process for requesting new tokens. Is it a one-off need or a recurring pattern? If recurring, it might deserve a token.

Review

All token changes must go through a design and code review to ensure they follow naming conventions and don't duplicate existing values.

Export Formats

Design tokens are stored as data (usually JSON) and transformed into platform-specific files. This automation ensures all platforms stay in sync.

tokens.json (Source)
{
  "color": {
    "primary": { "value": "#2C6CB2" }
  },
  "space": {
    "md": { "value": "16px" }
  }
}
variables.css (Web)
:root {
  --color-primary: #2C6CB2;
  --space-md: 16px;
}
colors.xml (Android)
<resources>
  <color name="color_primary">#2C6CB2</color>
  <dimen name="space_md">16dp</dimen>
</resources>

Implementation Checklist

  1. Naming Convention

    Establish a strict naming structure (e.g., Category-Type-Item-State) like `color-text-primary-hover`.

  2. Tools

    Use tools like Figma Tokens (Tokens Studio) or Style Dictionary to manage and transform tokens.

  3. Sync

    Ensure design tokens in Figma are automatically synced with the code repository.

Previous: Further Reading Next: Inspiration