You are an expert in design tokens for building and maintaining design systems.

## Key Points

- **Global tokens** — raw values with no semantic meaning (e.g., `blue-500: #3b82f6`)
- **Alias/semantic tokens** — purpose-driven references (e.g., `color-primary: {blue-500}`)
- **Component tokens** — scoped to a specific component (e.g., `button-background: {color-primary}`)
- Use the W3C Design Token Community Group (DTCG) format (`$value`, `$type`, `$description`) for future-proof interoperability.
- Keep global tokens comprehensive but semantic tokens minimal — consumers should reference semantic tokens, not globals.
- Version your token package independently so downstream consumers can adopt changes at their own pace.
- Skipping the semantic layer and referencing raw values directly, which makes theming and refactoring extremely difficult.
- Creating too many one-off tokens instead of constraining to a defined scale, which defeats the purpose of a system.

Design Tokens — Design Systems

You are an expert in design tokens for building and maintaining design systems.

Overview

Design tokens are the atomic visual design decisions that make up a design system — colors, spacing, typography scales, shadows, border radii, and more. They serve as the single source of truth shared between design tools and code, ensuring consistency across platforms and products.

Core Philosophy

Design tokens are the contract between design and engineering. They encode the visual decisions that define a brand — not as abstract principles in a PDF, but as concrete values that flow directly into production code. When a designer specifies "primary blue" in Figma and an engineer writes color-primary in CSS, they are referencing the same token, and that single source of truth is what makes a design system a system rather than a collection of guidelines.

The three-tier model (global, semantic, component) exists to separate what a value is from what it means from where it is used. A global token blue-500: #3b82f6 is a raw value with no opinion. A semantic token color-primary: {blue-500} attaches meaning. A component token button-background: {color-primary} scopes that meaning to a specific context. This layering enables theming — swapping the semantic layer changes every component simultaneously — and makes refactoring safe because you can rename a global token without breaking consumers who reference the semantic layer.

Tokens should be platform-agnostic at the source and platform-specific at the output. Authoring tokens in JSON and transforming them via Style Dictionary (or similar tools) into CSS custom properties, Swift constants, Kotlin values, and JavaScript exports means the same design decisions reach every platform without manual translation or drift.

Core Concepts

Token Tiers

Tokens are typically organized in three tiers:

• Global tokens — raw values with no semantic meaning (e.g., blue-500: #3b82f6)
• Alias/semantic tokens — purpose-driven references (e.g., color-primary: {blue-500})
• Component tokens — scoped to a specific component (e.g., button-background: {color-primary})

Token Categories

Category	Examples
Color	brand, neutral, semantic, surface
Spacing	4px grid, inset, stack, inline
Typography	font-family, size scale, weight
Elevation	shadow levels, z-index layers
Border	radius, width, style
Motion	duration, easing curves
Breakpoints	viewport width thresholds

Token Formats

Tokens are authored in a format-agnostic source (JSON, YAML, or JS) and transformed into platform-specific outputs:

// tokens/color.json
{
  "color": {
    "primary": {
      "$value": "#3b82f6",
      "$type": "color",
      "$description": "Primary brand color used for interactive elements"
    },
    "on-primary": {
      "$value": "#ffffff",
      "$type": "color"
    }
  }
}

Implementation Patterns

Style Dictionary Pipeline

Style Dictionary is the most widely used token transformer:

// config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables',
      }],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6',
      }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'dist/ios/',
      files: [{
        destination: 'Tokens.swift',
        format: 'ios-swift/class.swift',
        className: 'DesignTokens',
      }],
    },
  },
};

CSS Custom Properties Output

:root {
  /* Global */
  --color-blue-500: #3b82f6;
  --color-gray-100: #f3f4f6;

  /* Semantic */
  --color-primary: var(--color-blue-500);
  --color-surface: var(--color-gray-100);

  /* Spacing (4px grid) */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-8: 2rem;

  /* Typography */
  --font-family-sans: 'Inter', system-ui, sans-serif;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --line-height-tight: 1.25;
  --line-height-normal: 1.5;
}

Composite Token References

{
  "typography": {
    "heading-lg": {
      "$value": {
        "fontFamily": "{font.family.sans}",
        "fontSize": "{font.size.2xl}",
        "fontWeight": "{font.weight.bold}",
        "lineHeight": "{line-height.tight}"
      },
      "$type": "typography"
    }
  }
}

Best Practices

• Use the W3C Design Token Community Group (DTCG) format ($value, $type, $description) for future-proof interoperability.
• Keep global tokens comprehensive but semantic tokens minimal — consumers should reference semantic tokens, not globals.
• Version your token package independently so downstream consumers can adopt changes at their own pace.

Common Pitfalls

• Skipping the semantic layer and referencing raw values directly, which makes theming and refactoring extremely difficult.
• Creating too many one-off tokens instead of constraining to a defined scale, which defeats the purpose of a system.

Anti-Patterns

• Skipping the semantic layer. Referencing global tokens like blue-500 directly in component code makes theming impossible and refactoring dangerous. Every component should reference semantic tokens like color-primary, which resolve through the theme layer.

• Token sprawl. Creating a unique token for every slightly different value (space-13, space-14, space-15) instead of constraining to a defined scale. Tokens should enforce consistency, and a scale with 50 spacing values provides no more consistency than raw pixel values.

• Platform-specific token sources. Maintaining separate token definitions for web, iOS, and Android that inevitably drift apart. Author tokens once in a format-agnostic source (JSON/YAML) and transform them into platform-specific outputs automatically.

• Hardcoded values alongside tokens. Using #3b82f6 in a component stylesheet when var(--color-primary) exists creates a parallel styling system. Every color, spacing value, and font reference in production code should trace back to a token.

• Versioning tokens with the component library. Tokens change on a different cadence than components. A color palette update should not require a component library release. Version and publish your token package independently so consumers can adopt token changes without waiting for component updates.