Design Tokens: Scaling Design Systems Across Platforms [2026]

A design token is the smallest addressable unit of a design decision. Not "use blue for interactive elements" — that is a principle. A design token is color-brand-primary: #1A73E8 — a named, stored, referenceable value. The distinction matters because design principles cannot be consumed by code, cannot be automatically applied across platforms, and cannot be updated in one place and propagated everywhere. Design tokens can.

When Salesforce coined the concept in 2014 through their Lightning Design System, the problem they were solving was precise: a complex, multi-team, multi-platform product ecosystem was maintaining visual consistency through documentation alone, and that documentation was always out of date. Design tokens replaced documentation with automation — a single source of truth that both Figma and every platform's codebase read from.

This guide covers design token taxonomy (the three-tier hierarchy that makes tokens maintainable), the Style Dictionary toolchain, multi-brand and multi-platform token management, the design-to-code automation pipeline, and governance for scaling design tokens at enterprise level.

Why Design Tokens Change Design System Maintenance

The before-and-after of design token adoption is most clearly visible in a simple scenario: updating the primary brand color.

Without design tokens: Update the color in Figma (but only in components that use the named style, not any hardcoded instances). Notify developers. Each developer updates the hardcoded color values in their platform (web CSS, iOS Swift, Android XML). Miss a few instances — not noticed until a visual regression test or code review. Process takes hours and introduces risk of inconsistency between platforms.

With design tokens: Update the value of color-brand-primary in the token file. Run the Style Dictionary build pipeline. New values are automatically output to CSS custom properties, Swift color constants, and Android XML resources. All platform codebases pull the updated values. Process takes minutes and is inherently consistent.

The efficiency gain scales with the complexity of the change and the number of platforms. A full brand color palette refresh across three platforms with five developers takes hours without tokens and minutes with them — with lower error rates in both cases.

Design Token Taxonomy: The Three-Tier Hierarchy

The most important architectural decision in a token system is how tokens are organized. A flat list of tokens with no hierarchy is difficult to maintain, difficult to understand, and impossible to use efficiently for theming. The three-tier hierarchy resolves these problems.

Tier 1: Primitive Tokens (Global Tokens)

Primitive tokens are raw values without semantic meaning. They define the universe of possible values in the system — every color that can be used, every spacing value, every font size.

{
  "color": {
    "blue-100": { "value": "#EBF3FF" },
    "blue-200": { "value": "#C7DCFF" },
    "blue-500": { "value": "#1A73E8" },
    "blue-600": { "value": "#1557B0" },
    "blue-700": { "value": "#1045A1" },
    "gray-50":  { "value": "#FAFAFA" },
    "gray-100": { "value": "#F5F5F5" },
    "gray-900": { "value": "#212121" }
  },
  "spacing": {
    "scale-1": { "value": "4px" },
    "scale-2": { "value": "8px" },
    "scale-3": { "value": "12px" },
    "scale-4": { "value": "16px" },
    "scale-6": { "value": "24px" },
    "scale-8": { "value": "32px" }
  }
}

Primitive tokens should never be used directly in component code. They exist to be referenced by semantic tokens.

Tier 2: Semantic Tokens (Alias Tokens)

Semantic tokens map primitive values to their intended purpose. They answer the question "what is this value for?" rather than "what value is this?"

{
  "color": {
    "interactive-primary":       { "value": "{color.blue-500}" },
    "interactive-primary-hover": { "value": "{color.blue-600}" },
    "interactive-primary-active":{ "value": "{color.blue-700}" },
    "background-default":        { "value": "{color.gray-50}" },
    "background-surface":        { "value": "#FFFFFF" },
    "text-primary":              { "value": "{color.gray-900}" },
    "text-secondary":            { "value": "{color.gray-600}" }
  },
  "spacing": {
    "component-padding-sm":  { "value": "{spacing.scale-2}" },
    "component-padding-md":  { "value": "{spacing.scale-4}" },
    "component-padding-lg":  { "value": "{spacing.scale-6}" },
    "layout-gap-sm":         { "value": "{spacing.scale-3}" },
    "layout-gap-md":         { "value": "{spacing.scale-6}" }
  }
}

The power of semantic tokens: when the brand's primary blue changes from #1A73E8 to #0057D9, only the primitive color.blue-500 needs to change. The semantic token interactive-primary still references {color.blue-500}, and all components that use interactive-primary automatically get the new value.

Semantic tokens also enable theming. A dark mode theme can override semantic tokens to point to different primitives:

{
  "color": {
    "background-default":  { "value": "{color.gray-900}" },
    "text-primary":        { "value": "{color.gray-50}" },
    "interactive-primary": { "value": "{color.blue-300}" }
  }
}

The light theme and dark theme are just two sets of semantic token values pointing to different primitives.

Tier 3: Component Tokens

Component tokens are semantic tokens scoped to specific UI components. They enable fine-grained control over individual component behavior without polluting the semantic layer.

{
  "button": {
    "background":          { "value": "{color.interactive-primary}" },
    "background-hover":    { "value": "{color.interactive-primary-hover}" },
    "background-disabled": { "value": "{color.gray-200}" },
    "text-color":          { "value": "#FFFFFF" },
    "padding-vertical":    { "value": "{spacing.component-padding-sm}" },
    "padding-horizontal":  { "value": "{spacing.component-padding-md}" },
    "border-radius":       { "value": "6px" }
  },
  "input": {
    "border-default":      { "value": "{color.gray-300}" },
    "border-focus":        { "value": "{color.interactive-primary}" },
    "border-error":        { "value": "{color.red-500}" },
    "background":          { "value": "{color.background-surface}" },
    "padding-vertical":    { "value": "{spacing.component-padding-sm}" },
    "padding-horizontal":  { "value": "{spacing.component-padding-md}" }
  }
}

Component tokens give product teams the ability to theme individual components (change the button padding for a specific product brand) without modifying the global semantic layer.

Style Dictionary: The Standard Token Build Tool

Style Dictionary, developed and open-sourced by Amazon, is the industry standard for transforming design token source files (JSON or YAML) into platform-specific output formats. A single token definition produces CSS variables, Swift constants, Android XML, Flutter Dart, and any custom format required.

Basic Configuration

// config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'ds',
      buildPath: 'build/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables'
      }]
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'build/ios/',
      files: [{
        destination: 'DesignTokens.swift',
        format: 'ios-swift/class.swift',
        className: 'DesignTokens'
      }]
    },
    android: {
      transformGroup: 'android',
      buildPath: 'build/android/src/main/res/values/',
      files: [
        {
          destination: 'colors.xml',
          format: 'android/colors'
        },
        {
          destination: 'dimens.xml',
          format: 'android/dimens'
        }
      ]
    }
  }
};

Running npx style-dictionary build transforms the source tokens into all specified output formats simultaneously, ensuring consistent values across all platforms.

Custom Transforms

Style Dictionary's transform system allows custom value processing. Common examples:

• Converting px values to rem for CSS output
• Converting dp values to Swift CGFloat for iOS
• Applying platform-specific color format transformations

StyleDictionary.registerTransform({
  name: 'size/px-to-rem',
  type: 'value',
  matcher: token => token.attributes.category === 'spacing',
  transformer: token => {
    const baseFont = 16;
    const pxValue = parseFloat(token.value);
    return `${pxValue / baseFont}rem`;
  }
});

Tokens Studio: Bridging Figma and Code

Tokens Studio (formerly Figma Tokens) is the Figma plugin that enables designers to manage design tokens within Figma and synchronize them with the token source files in the code repository.

The Tokens Studio Workflow

1. Designer creates or updates tokens in Tokens Studio within Figma
2. Tokens Studio applies token values to Figma component variables
3. Tokens Studio exports token JSON to the Git repository (or directly pushes via its Git integration)
4. CI/CD pipeline detects the token file change
5. Style Dictionary builds platform-specific outputs
6. Package version increments and publishes to the internal package registry
7. Consuming applications receive updated token values

This pipeline converts token updates from a manual coordination task (designer tells developer to update color X to value Y; developer updates in CSS, Swift, and Android files; developer commits and notifies teams) to an automated propagation (designer updates token value; pipeline distributes to all consumers automatically).

Themes and Multi-Brand Support

Tokens Studio natively supports multiple token sets and theme switching. The multi-brand token structure:

tokens/
  global/
    primitives.json      # All raw values
  semantic/
    light.json           # Light theme semantic tokens
    dark.json            # Dark theme semantic tokens
  brands/
    brand-a/
      brand.json         # Brand A color overrides
    brand-b/
      brand.json         # Brand B color overrides
  components/
    button.json          # Component-level tokens
    input.json

Tokens Studio allows designers to activate different theme combinations in Figma — switch between Brand A light, Brand A dark, Brand B light, Brand B dark — and immediately see the visual impact across all components.

Multi-Platform Token Pipeline

For organizations with web, iOS, Android, and potentially Flutter or other targets, the token pipeline must produce correct output for each platform without requiring manual platform-specific maintenance.

Platform Output Comparison

Token Definition	CSS Output	iOS Swift Output	Android XML Output
color-brand-primary: #1A73E8	--color-brand-primary: #1A73E8;	static let brandPrimary = UIColor(hex: "#1A73E8")	<color name="colorBrandPrimary">#1A73E8</color>
spacing-md: 16px	--spacing-md: 1rem;	static let spacingMd: CGFloat = 16	<dimen name="spacingMd">16dp</dimen>
font-size-body: 16px	--font-size-body: 1rem;	static let fontSizeBody: CGFloat = 16	<dimen name="fontSizeBody">16sp</dimen>

Automated CI/CD Pipeline

The complete automated pipeline for token distribution:

# .github/workflows/tokens.yml
name: Design Token Pipeline

on:
  push:
    paths:
      - 'tokens/**/*.json'

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Build tokens
        run: npx style-dictionary build

      - name: Run visual regression tests
        run: npm run test:visual

      - name: Version and publish
        run: |
          npm version patch
          npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Notify consuming teams
        run: |
          curl -X POST "${{ secrets.SLACK_WEBHOOK }}" \
          -d '{"text": "Design tokens updated: ${{ github.event.head_commit.message }}"}'

Design System Scaling: Governance for Token Systems

Semantic Versioning for Token Packages

Token packages should follow Semantic Versioning:

• Major version (2.0.0): Renamed or removed tokens that break consuming implementations
• Minor version (1.1.0): New tokens added; no breaking changes to existing tokens
• Patch version (1.0.1): Value corrections; no structural changes

Before removing or renaming a token:

1. Mark it deprecated: true in the token metadata
2. Add a deprecated-in: "1.4.0" and remove-in: "2.0.0" note
3. Provide the replacement token name in documentation
4. Announce the deprecation in design system release notes
5. Remove in the next major version only

ESLint Rules for Token Compliance

Enforce token usage in the codebase by detecting hardcoded values that should be tokens:

// .eslintrc.js
module.exports = {
  rules: {
    'no-restricted-syntax': [
      'error',
      {
        selector: "Literal[value=/^#[0-9a-fA-F]{3,8}$/]",
        message: 'Use a design token instead of a hardcoded color value.'
      },
      {
        selector: "TemplateElement[value.cooked=/^#[0-9a-fA-F]{3,8}$/]",
        message: 'Use a design token instead of a hardcoded color value.'
      }
    ]
  }
};

This rule produces a build error when any hardcoded hex color is introduced in source code, enforcing token usage without relying on manual code review.

Metrics for Token System Health

Metric	Definition	Target
Token override rate	Lines of code using hardcoded values vs token references	Under 3%
Token adoption rate	Teams using token package vs total product teams	Above 90%
Token coverage	UI elements using semantic tokens vs total UI elements	Above 95%
Update propagation time	Time from token change to all platforms receiving update	Under 15 minutes
Breaking change frequency	Major version releases per year	Under 2 per year

The token override rate is the most sensitive indicator of design system health. When developers begin overriding tokens with hardcoded values — even for "just this one exception" — the override rate increases and visual consistency degrades. ESLint enforcement, combined with code review practices that treat token overrides as technical debt requiring justification, keeps the rate in the target range.

In product work at Smart Maple, token systems with automated pipelines have eliminated the coordination overhead of cross-platform visual updates — changes that previously required developer involvement across three codebases are now designer-initiated, pipeline-automated, and deployed without engineering coordination time. The system investment pays back within the first significant brand update that would otherwise require three separate code deployments.