Design Tokens

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

Stay updated with new patterns

Get notified when new UX patterns are added to the collection.