Building a Design Tokens to CSS Pipeline

1. Why design tokens solve a synchronization problem

Design tokens are named, platform independent design decisions, for example a brand color, a spacing step or a font size, stored as structured data instead of CSS, Swift or Kotlin code. The core problem design tokens solve: without a central source, every platform team maintains its own copy of the same values, a web team in a Tailwind configuration, an iOS team in a Swift file, an Android team in XML resources. Changing the brand color requires three coordinated pull requests, and the probability that one platform gets forgotten grows with every additional iteration.

The central benefit of design tokens lies in separating the design decision from its platform representation. A token like color.brand.500 with the value oklch(0.55 0.18 275) exists exactly once, in a machine readable source, typically JSON. A transformation pipeline automatically generates the matching syntax for each target platform, CSS custom properties for web, a Swift enum for iOS, XML resources for Android, without a human retyping the value in multiple places by hand.

This article describes the full path from the token source to shipped CSS: structure of the JSON files, reference versus alias tokens, the actual transformation pipeline with Style Dictionary, and governance questions about who is even allowed to change design tokens before a change goes live.

2. Structuring the token source: categories and levels

A well structured token source typically follows a category property value hierarchy, as also proposed as a standard by the Design Tokens Community Group. The top level groups by category (color, spacing, typography), the second level by concrete property (brand, neutral, danger), and the bottom level contains the actual value, often with a numeric scale like 50 to 900 for color shades.

This structure is not a formality, it directly determines how well the later pipeline scales. A flat, unstructured list of tokens without categorization works for a small project with twenty values, but quickly becomes unwieldy for a design system with several hundred design tokens. Consistent categorization also enables automated validation, for example checking that every color category has a complete scale from 50 to 900 instead of gaps.

{
  "color": {
    "brand": {
      "500": { "value": "oklch(0.55 0.18 275)", "type": "color" },
      "600": { "value": "oklch(0.48 0.19 275)", "type": "color" }
    },
    "neutral": {
      "50":  { "value": "oklch(0.98 0.01 275)", "type": "color" },
      "900": { "value": "oklch(0.15 0.02 275)", "type": "color" }
    }
  },
  "spacing": {
    "unit": { "value": "0.25rem", "type": "dimension" },
    "md":   { "value": "1rem", "type": "dimension" },
    "lg":   { "value": "1.5rem", "type": "dimension" }
  }
}

3. Separating reference tokens and alias tokens

A crucial architectural principle for design tokens is the separation between reference tokens (also called base or global tokens) and alias tokens (also called semantic tokens). Reference tokens like color.blue.500 describe a raw, contextless value. Alias tokens like color.action.primary point to a reference token and give it a semantic meaning in the context of a concrete UI role.

This two tier structure makes theme switching and rebranding considerably easier. If color.action.primary should point to a different reference token in dark mode than in light mode, only the mapping in the alias layer changes, while every component still references the same semantic token color.action.primary and needs no changes to its own code. Without this separation, every component would have to reference raw color values directly, turning a global theme switch into a risky search and replace operation.

{
  "color": {
    "action": {
      "primary": {
        "value": "{color.brand.500}",
        "type": "color",
        "comment": "Semantic alias — points to a raw reference token"
      },
      "primary-hover": {
        "value": "{color.brand.600}",
        "type": "color"
      },
      "danger": {
        "value": "{color.red.500}",
        "type": "color"
      }
    }
  }
}

4. Building the transformation pipeline with Style Dictionary

Style Dictionary by Amazon is the most common tool for transforming design tokens from a JSON source into platform specific output formats. The configuration defines a separate build step for each target platform with a matching transformer and format, for example CSS custom properties for web, a Swift dictionary for iOS or an XML resource file for Android. The decisive advantage: the source remains a single source of truth, while any number of platform outputs are derived from it automatically.

This pipeline typically runs as part of the CI process, triggered on every change to the token files. That means a design change to a single JSON value automatically propagates into a new build for web, iOS and Android, without a developer having to manually create three separate pull requests. For teams with frequent design iterations, this automation considerably reduces coordination overhead.

// style-dictionary.config.js — one source, multiple platform outputs
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables',
        options: { outputReferences: true },
      }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'build/ios/',
      files: [{ destination: 'Tokens.swift', format: 'ios-swift/enum-swift5' }],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'build/android/',
      files: [{ destination: 'tokens.xml', format: 'android/resources' }],
    },
  },
};

// Build command: npx style-dictionary build

5. From tokens to CSS custom properties

The CSS target of the pipeline typically generates a single file with :root declarations, where every token appears as a custom property. The outputReferences option in Style Dictionary preserves the semantic reference structure from section three: instead of resolving color.action.primary directly into the raw hex or OKLCH value, the pipeline generates var(--color-brand-500) as the value of the alias property, keeping the relationship between semantic and reference token visible even in the shipped CSS.

This generated CSS file is typically imported as one of the first files in the ITCSS Settings layer, forming the foundation all component rules build upon. Important: this file is never edited manually, every change happens exclusively at the JSON source, followed by a fresh pipeline run. Directly editing the generated file would get overwritten without warning the next time the pipeline runs.

/* build/css/tokens.css — generated, never edited by hand */
:root {
  --color-brand-500: oklch(0.55 0.18 275);
  --color-brand-600: oklch(0.48 0.19 275);
  --color-neutral-50: oklch(0.98 0.01 275);
  --color-neutral-900: oklch(0.15 0.02 275);

  /* Semantic aliases reference the raw values, relationship stays visible */
  --color-action-primary: var(--color-brand-500);
  --color-action-primary-hover: var(--color-brand-600);
  --color-action-danger: var(--color-red-500);

  --spacing-unit: 0.25rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
}

6. Mapping themes and modes through token layers

Dark mode or brand variants can be elegantly mapped in a design tokens pipeline through additional theme files that only override the alias layer, without duplicating the reference layer. A file theme.dark.json might change color.action.primary to a lighter reference token, while the base palette in color.json stays unchanged and is shared by both themes.

The pipeline generates a separate CSS layer or class for each theme, for example [data-theme="dark"], containing only the changed alias values. This approach keeps the generated CSS file small, because the complete color palette is not duplicated, only the few semantic mappings that actually differ between the themes.

/* build/css/tokens.dark.css — generated from theme.dark.json */
[data-theme="dark"] {
  --color-action-primary: var(--color-brand-300);
  --color-surface: var(--color-neutral-900);
  --color-text: var(--color-neutral-50);
}

7. Token validation and CI integration

An automated pipeline for design tokens is only as reliable as its validation layer. A JSON schema enforcing mandatory fields like value and type for every token prevents structurally broken token files from ever entering the transformation pipeline. In addition, an automated contrast checker verifies whether color token combinations like text and background color meet WCAG contrast requirements, directly in CI, before a design change gets merged.

A second important CI step is a diff report that lists, on every pull request, which concrete design tokens changed and which generated CSS values were affected. For reviewers without deep CSS knowledge, this makes the impact of a token change tangible, without having to manually search through the entire generated output file.

8. Governance: who is allowed to change tokens

Governance is the most commonly underestimated part of a design tokens pipeline. Without clear ownership, whichever team happens to be building a component will, when in doubt, simply change an existing token instead of creating a new one or checking in with someone, which gradually causes meaning drift, for example when color.brand.500 no longer matches the actual brand color after several small adjustments.

A proven model is a dedicated design system team or a designated person with sole merge authority over the token source, while feature teams submit change requests through pull requests with a clear rationale. This governance structure turns design tokens into a managed product instead of a byproduct of individual feature development, which prevents the token source from turning into an unwieldy collection of individual adjustments over the long term.

9. Manual maintenance versus automated pipeline compared

The following table contrasts how manually maintained, platform specific values differ from an automated design tokens pipeline.

The effort for the initial pipeline setup usually pays for itself after only a few design iterations, especially for products with more than one target platform, where manual synchronization would otherwise become a recurring coordination burden between multiple teams.

10. Summary

Design tokens solve the synchronization problem of cross platform products by defining colors, spacing and typography once, centrally, as structured data, and transforming them automatically into platform specific formats. The separation between reference tokens and semantic alias tokens turns theme switching and rebranding into a local change in the alias layer, instead of a risky, project wide search and replace operation.

A pipeline with Style Dictionary automates the transformation from JSON to CSS custom properties, Swift and Kotlin, while JSON schema validation and contrast checks in CI catch structural and content errors before a change goes live. Clear governance over who is allowed to change design tokens finally prevents the central source itself from degrading into an unwieldy collection of individual adjustments.

11. FAQ: Design Tokens to CSS Pipeline