Design Tokens

Design tokens are the atoms of a design system — named values that represent visual design decisions like color, spacing, typography, and motion. Instead of hardcoding #1a73e8 throughout your codebase, you use color.primary.base. When the brand color changes, you update one token and every component across every platform updates.

---

Token Taxonomy

Global Tokens (primitive):
  color.blue.500: "#1a73e8"
  color.blue.600: "#1557b0"
  spacing.4: "16px"
  font.size.lg: "18px"
  
Semantic Tokens (contextual):
  color.primary: "{color.blue.500}"
  color.error: "{color.red.500}"
  spacing.component.padding: "{spacing.4}"
  font.heading.size: "{font.size.lg}"
  
Component Tokens (specific):
  button.primary.background: "{color.primary}"
  button.primary.text: "{color.white}"
  button.padding.horizontal: "{spacing.4}"
  card.border.radius: "{radius.md}"

Hierarchy:
  Global → Semantic → Component
  Concrete → Abstract → Specific

---

Token Definition (Style Dictionary)

{
  "color": {
    "brand": {
      "primary": {
        "value": "#1a73e8",
        "type": "color",
        "description": "Primary brand color, used for CTAs and key UI elements"
      },
      "secondary": {
        "value": "#34a853",
        "type": "color"
      }
    },
    "neutral": {
      "50": { "value": "#fafafa" },
      "100": { "value": "#f5f5f5" },
      "200": { "value": "#eeeeee" },
      "900": { "value": "#212121" }
    }
  },
  "spacing": {
    "xs": { "value": "4px" },
    "sm": { "value": "8px" },
    "md": { "value": "16px" },
    "lg": { "value": "24px" },
    "xl": { "value": "32px" }
  },
  "typography": {
    "heading": {
      "fontFamily": { "value": "'Inter', sans-serif" },
      "fontWeight": { "value": "700" },
      "fontSize": {
        "h1": { "value": "32px" },
        "h2": { "value": "24px" },
        "h3": { "value": "20px" }
      }
    }
  }
}

---

Multi-Platform Transformation

// style-dictionary.config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables',
      }],
    },
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/scss/',
      files: [{
        destination: '_variables.scss',
        format: 'scss/variables',
      }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'build/ios/',
      files: [{
        destination: 'StyleDictionary.swift',
        format: 'ios-swift/class.swift',
      }],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'build/android/',
      files: [{
        destination: 'colors.xml',
        format: 'android/colors',
      }],
    },
  },
};

// Output examples:
// CSS: --color-brand-primary: #1a73e8;
// SCSS: $color-brand-primary: #1a73e8;
// Swift: static let colorBrandPrimary = UIColor(hex: "#1a73e8")
// Android: <color name="color_brand_primary">#1a73e8</color>

---

Theming

/* Light theme */
:root {
  --color-background: var(--color-neutral-50);
  --color-surface: var(--color-white);
  --color-text-primary: var(--color-neutral-900);
  --color-text-secondary: var(--color-neutral-600);
  --color-border: var(--color-neutral-200);
}

/* Dark theme */
[data-theme="dark"] {
  --color-background: var(--color-neutral-900);
  --color-surface: var(--color-neutral-800);
  --color-text-primary: var(--color-neutral-50);
  --color-text-secondary: var(--color-neutral-400);
  --color-border: var(--color-neutral-700);
}

---

Anti-Patterns

Anti-Pattern	Consequence	Fix
No semantic layer	Global tokens tightly coupled to components	Three-tier hierarchy
Too many tokens	Cognitive overload, hard to maintain	100-200 tokens maximum
No naming convention	Inconsistent, confusing names	Consistent taxonomy
Single platform output	Token value locked to one technology	Multi-platform pipeline
Design tool disconnected	Figma and code tokens drift	Automated sync (Tokens Studio)

Design tokens are the contract between design and engineering. When they are maintained as a single source of truth, every platform stays in sync and design changes cascade automatically.