Design Tokens & Brand Foundations
Learn how to create and manage design tokens — the single source of truth for your visual design language that bridges design and development.
Understanding Design Tokens
Design tokens are named entities that store visual design attributes — colors, typography, spacing, shadows, animation timings, and more. Instead of hardcoding '#3B82F6' everywhere, you define a token called 'color-primary-500' that maps to that value. If the brand color changes, update the token once and it propagates everywhere. Tokens exist at multiple levels: Global tokens (raw values like 'blue-500'), Alias tokens (semantic names like 'color-interactive'), and Component tokens (specific usage like 'button-background'). Leading tools like Figma Tokens, Style Dictionary, and Theo help manage and transform tokens across platforms — the same token set can generate CSS variables, iOS Swift values, and Android XML values simultaneously.
Token Categories & Structure
- Color Tokens: Primary, secondary, neutral, semantic (success, warning, error, info), surface, text, border, and interactive state colors
- Typography Tokens: Font family, font weight, font size (using a type scale like 12/14/16/18/20/24/32/48), line height, letter spacing
- Spacing Tokens: Use a consistent scale (4px base) — spacing-1 (4px), spacing-2 (8px), spacing-3 (12px), spacing-4 (16px), spacing-6 (24px), spacing-8 (32px)
- Shadow Tokens: Elevation levels from subtle (cards) to prominent (modals, dropdowns) — shadow-sm, shadow-md, shadow-lg, shadow-xl
- Border Tokens: Border width, border radius (none, sm, md, lg, full/pill), and border color for different component states
- Motion Tokens: Duration (fast: 150ms, normal: 300ms, slow: 500ms), easing curves (ease-in-out, spring), and transition properties
- Breakpoint Tokens: Mobile (< 640px), tablet (640-1024px), desktop (1024-1440px), wide (> 1440px)
Implementing Design Tokens
- Source of Truth: Store tokens in a platform-agnostic format (JSON or YAML) — this file is your single source of truth
- CSS Custom Properties: Transform tokens into --color-primary: #3B82F6 for web projects — they support runtime theming
- Dark Mode: Create a separate set of alias tokens that map to different global tokens — --color-surface maps to white in light mode and gray-900 in dark mode
- Multi-brand: Use the same component library with different token sets — each brand gets its own token file
- Version Control: Track tokens in Git alongside code — changes are reviewable, auditable, and reversible
- Automation: Use tools like Style Dictionary to auto-generate platform-specific token files from your single JSON source