Design Tokens

Platform-agnostic variables that store design decisions for consistent implementation across products and teams

Design tokens are the visual design atoms of a design system — specifically, they are named entities that store visual design attributes. They act as a single source of truth for design decisions, replacing hard-coded values with semantic references that can be maintained, scaled, and transformed across different platforms and technologies.

What Are Design Tokens?

Instead of:

.button {
  background-color: #0066cc;
  padding: 12px 24px;
  border-radius: 4px;
}

You use:

.button {
  background-color: var(--color-primary-base);
  padding: var(--spacing-3) var(--spacing-6);
  border-radius: var(--radius-small);
}

Types of Design Tokens

Core Tokens (Global)

Foundation-level values without context:

{
  "color": {
    "blue-500": "#0066cc",
    "gray-100": "#f5f5f5"
  },
  "spacing": {
    "4": "16px",
    "8": "32px"
  }
}

Semantic Tokens (Alias)

Reference core tokens with meaning:

{
  "color": {
    "primary": "{color.blue-500}",
    "background": "{color.gray-100}"
  },
  "spacing": {
    "button-padding": "{spacing.4}"
  }
}

Component Tokens

Specific to component implementations:

{
  "button": {
    "background": "{color.primary}",
    "padding-x": "{spacing.button-padding}",
    "border-radius": "{spacing.sm}"
  }
}

Token Categories

Colors

{
  "color": {
    "primary": {
      "50": "#e6f0ff",
      "500": "#0066cc",
      "900": "#002244"
    },
    "semantic": {
      "error": "#dc3545",
      "success": "#28a745",
      "warning": "#ffc107"
    }
  }
}

Typography

{
  "font": {
    "family": {
      "base": "'Inter', sans-serif",
      "heading": "'Poppins', sans-serif"
    },
    "size": {
      "sm": "14px",
      "base": "16px",
      "lg": "20px"
    },
    "weight": {
      "normal": 400,
      "bold": 700
    }
  }
}

Spacing

{
  "spacing": {
    "xs": "4px",
    "sm": "8px",
    "md": "16px",
    "lg": "24px",
    "xl": "32px"
  }
}

Sizing

{
  "size": {
    "icon": {
      "sm": "16px",
      "md": "24px",
      "lg": "32px"
    },
    "button": {
      "height": "44px"
    }
  }
}

Effects

{
  "shadow": {
    "sm": "0 1px 2px rgba(0,0,0,0.1)",
    "md": "0 4px 6px rgba(0,0,0,0.1)",
    "lg": "0 10px 15px rgba(0,0,0,0.1)"
  },
  "blur": {
    "sm": "4px",
    "md": "8px"
  }
}

Token Formats

Design Tokens Format (DTF)

Industry standard specification:

{
  "$schema": "https://design-tokens.org/schema.json",
  "colors": {
    "primary": {
      "$value": "#0066cc",
      "$type": "color",
      "$description": "Primary brand color"
    }
  }
}

Style Dictionary Format

Amazon's popular format:

{
  "color": {
    "base": {
      "gray": {
        "light": { "value": "#CCCCCC" },
        "medium": { "value": "#999999" },
        "dark": { "value": "#111111" }
      }
    }
  }
}

Implementation Strategies

CSS Custom Properties

:root {
  --color-primary: #0066cc;
  --spacing-base: 16px;
  --font-size-lg: 1.25rem;
}

.component {
  color: var(--color-primary);
  padding: var(--spacing-base);
  font-size: var(--font-size-lg);
}

JavaScript/TypeScript

export const tokens = {
  color: {
    primary: '#0066cc',
    secondary: '#6c757d'
  },
  spacing: {
    sm: '8px',
    md: '16px',
    lg: '24px'
  }
} as const;

Sass Variables

$color-primary: #0066cc;
$spacing-base: 16px;
$border-radius-sm: 4px;

.button {
  background: $color-primary;
  padding: $spacing-base;
  border-radius: $border-radius-sm;
}

Token Transformation

Build Tools

Transform tokens for different platforms:

// Input tokens.json
const tokens = {
  "color": {
    "primary": "#0066cc"
  }
};

// Output: CSS
:root {
  --color-primary: #0066cc;
}

// Output: iOS Swift
struct Colors {
  static let primary = UIColor(hex: "#0066cc")
}

// Output: Android XML
<color name="color_primary">#0066cc</color>

Popular Tools

Style Dictionary - Amazon's token transformer
Theo - Salesforce's token generator
Design Tokens Plugin - Figma to code
Tokens Studio - Figma plugin for managing tokens

Benefits

Consistency

Single source of truth ensures visual consistency across:

Different pages and components
Multiple platforms (web, iOS, Android)
Design tools and code

Maintainability

Change once, update everywhere:

// Change primary color in tokens.json
"color": {
  "primary": "#0052cc" // was #0066cc
}
// Automatically updates all uses

Scalability

Easy to add new themes
Support multiple brands
Enable dark mode with token swapping

Communication

Shared language between designers and developers
Self-documenting design decisions
Clear design system governance

Theme Switching

Enable multiple themes through token swapping:

/* Light theme */
[data-theme="light"] {
  --color-background: #ffffff;
  --color-text: #000000;
}

/* Dark theme */
[data-theme="dark"] {
  --color-background: #1a1a1a;
  --color-text: #ffffff;
}

Common Patterns

Naming Conventions

[category]-[property]-[variant]-[state]

Examples:
color-primary-500
spacing-inline-lg
font-size-heading-1
button-background-hover

Token Aliasing

Reference other tokens for flexibility:

{
  "color-brand": "{color.blue-500}",
  "color-action": "{color-brand}",
  "button-primary-bg": "{color-action}"
}

Best Practices

Do's ✅

Start with core tokens - Build foundation first
Use semantic naming - color-danger not color-red
Document token usage - When and why to use each token
Version your tokens - Track changes over time
Validate token usage - Lint for hard-coded values

Don'ts ❌

Don't over-tokenize - Not every value needs to be a token
Don't break contracts - Removing tokens breaks implementations
Don't mix concerns - Keep tokens focused on visual properties
Don't forget platforms - Consider all target platforms

Design tokens are fundamental for:

Pagination - Consistent spacing and colors
Buttons - Standardized sizes and styles
Tabs - Unified visual language

Tools & Resources

Key Takeaways

Design tokens create a single source of truth for design decisions
They enable consistency across platforms and teams
Semantic naming makes tokens self-documenting
Token transformation adapts values for different platforms
Proper organization with core, semantic, and component tokens
Version and document tokens for maintainability

On this page