Design Token

Problem

Brand colors, spacing values, and typography settings are hardcoded throughout the codebase with slight variations like “#3B82F6”, “#3b81f5”, and “rgb(59, 130, 246)” for the same blue. Rebranding or design system updates require finding and changing hundreds of magic numbers across web, mobile, and email templates, inevitably missing some and creating inconsistent user experiences.

Solution

Define design decisions like colors, spacing, and typography as named variables consumed across platforms. This centralizes design choices and ensures consistency while making large-scale changes manageable.

Example

This example demonstrates design tokens defined as JSON that can be transformed into platform-specific formats like CSS, JavaScript, or native mobile code.

{
  "color": {
    "primary": "#3B82F6",      // Brand primary color used across all platforms
    "secondary": "#8B5CF6"     // Brand secondary color
  },
  "spacing": {
    "sm": "8px",               // Small spacing unit
    "md": "16px",              // Medium spacing unit
    "lg": "24px"               // Large spacing unit
  }
}

Benefits

• Ensures visual consistency across web, mobile, and other platforms.
• Centralizes design decisions making rebranding or updates manageable.
• Creates single source of truth shared between design and development.
• Enables automatic platform-specific output from shared token definitions.
• Improves collaboration between designers and developers.

Tradeoffs

• Requires tooling and build processes to transform tokens for each platform.
• Can become overly granular with too many specific token definitions.
• May not capture all design nuances or context-specific variations.
• Needs governance to prevent token sprawl and maintain organization.
• Initial setup requires coordination across design and engineering teams.