Token Pipelines: From JSON to Every Platform

With tokens stored as DTCG JSON, something has to turn them into what each platform consumes: CSS custom properties for the web app and marketing site, Swift for the iOS driver app, Kotlin or XML for Android. That something is a token pipeline. It’s a small piece of code that every design system team ends up owning, and getting it right early saves months of drift later.

What a pipeline does

1. Parse every source file and deep-merge them into one tree.
2. Resolve aliases like {color.blue.600}, rejecting broken or circular references.
3. Transform names and values for each platform: color.action.bg becomes --nw-color-action-bg in CSS and colorActionBg in Swift; 1rem becomes 16 points on iOS.
4. Format the result as a file: a block of custom properties, a Swift enum, an Android resource file.

Here’s the heart of the CSS side, small enough to read in one go:

const tokens = {
  color: {
    $type: 'color',
    blue: { 600: { $value: { colorSpace: 'srgb', components: [0.122, 0.353, 0.878], hex: '#1f5ae0' } } },
    white: { $value: { colorSpace: 'srgb', components: [1, 1, 1], hex: '#ffffff' } },
    action: {
      bg: { $value: '{color.blue.600}' },
      text: { $value: '{color.white}' },
    },
  },
  space: { $type: 'dimension', 4: { $value: { value: 1, unit: 'rem' } } },
};

// Walk the tree and collect every token with its path.
function flatten(node, path = [], type) {
  const t = node.$type ?? type;
  if ('$value' in node) return [{ path, type: t, value: node.$value }];
  return Object.entries(node)
    .filter(([key]) => !key.startsWith('
    
  

))
    .flatMap(([key, child]) => flatten(child, [...path, key], t));
}

const cssName = (path) => `--nw-${path.join('-')}`;
function cssValue({ type, value }) {
  if (typeof value === 'string' && value.startsWith('{')) {
    return `var(${cssName(value.slice(1, -1).split('.'))})`; // keep the reference
  }
  if (type === 'color') return value.hex;
  if (type === 'dimension') return `${value.value}${value.unit}`;
  return String(value);
}

const lines = flatten(tokens).map((t) => `  ${cssName(t.path)}: ${cssValue(t)};`);
console.log(`/* Generated from tokens. Do not edit. */\n:root {\n${lines.join('\n')}\n}`);

Look at the output. The path becomes the name, so color.blue.600 comes out as --nw-color-blue-600; earlier lessons shortened primitives to --nw-blue-600 for readability, but in a generated system the name is whatever the group structure says, which is one more reason to design groups and names together. More importantly, semantic tokens come out as var(--nw-color-blue-600), not as a hex value. That choice is important enough to deserve its own section.

Keep the references

A pipeline can either resolve aliases to final values or keep them as references in the output. For CSS, keep them. Resolved output flattens your tiers: the browser sees --nw-color-action-bg: #1f5ae0, so overriding a primitive at runtime does nothing, and a developer inspecting a button in DevTools can’t see which primitive it comes from. Referenced output preserves the exact structure you designed, including the subtree theming from the themes lesson.

Native platforms are different. Swift and Kotlin constants are usually resolved to final values, because those platforms handle themes through their own mechanisms (asset catalogs, Compose color schemes).

A real pipeline with Style Dictionary

You could grow the script above into a full tool, but most teams use Style Dictionary, the most widely used open-source token build system. Recent versions read DTCG files natively and auto-detect the format. A Northwind-style config builds the light theme into :root and the dark theme under its attribute selector:

import StyleDictionary from 'style-dictionary';

const themes = {
  light: ':root',
  dark: '[data-theme="dark"]',
};

for (const [name, selector] of Object.entries(themes)) {
  const sd = new StyleDictionary({
    include: ['tokens/primitives.tokens.json'],
    source: [`tokens/semantic-${name}.tokens.json`],
    platforms: {
      css: {
        transformGroup: 'css',
        prefix: 'nw',
        buildPath: 'dist/css/',
        files: [{
          destination: `theme-${name}.css`,
          format: 'css/variables',
          filter: name === 'light' ? undefined : (token) => token.isSource,
          options: { selector, outputReferences: true },
        }],
      },
    },
  });
  await sd.buildAllPlatforms();
}

The key ideas: primitives come in through include, so references can resolve, while the theme’s semantic file comes in through source. For dark, the filter keeps only source tokens, so the dark file contains the remapped semantic tokens and not a second copy of every primitive. outputReferences: true keeps var() references in the output. Style Dictionary may warn that the dark file references tokens it filtered out; here that is intended, because the light file already defines the primitives on :root.

Checks that run with the build

Once tokens are data, CI can test design decisions like code. Northwind’s pipeline runs three checks on every pull request: the naming lint from earlier, a reference check that fails on broken or circular aliases, and a contrast check that resolves each documented text and background pair in every theme and fails below 4.5:1. That last one caught a dark-mode regression in the Tidewater brand before any designer saw it.

In the exercise, you complete the dark theme’s build config. That finishes the token architecture; the next section builds components on top of it.