{"id":"l-ds-2-5","courseId":"design-systems","lang":"en","kind":"lesson","summary":"Set up a token build pipeline that turns DTCG JSON into CSS custom properties per theme and native formats per platform, keeping references intact so runtime theming still works.","html":"

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.

\n

What a pipeline does

\n
\n Token JSON files flow through parse, resolve, transform and format steps, producing CSS for web, Swift for iOS and Kotlin for Android.\n \n *.tokens\n .json\n \n Parse\n \n Resolve\n \n Transform\n \n Format\n \n CSS\n \n Swift\n \n Kotlin\n \n \n \n \n \n \n \n
A token pipeline: one source, one output per platform
\n
    \n
  1. Parse every source file and deep-merge them into one tree.
    2. \n
  2. Resolve aliases like {color.blue.600}, rejecting broken or circular references.
    3. \n
  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. \n
  4. Format the result as a file: a block of custom properties, a Swift enum, an Android resource file.
    5. \n
\n

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

\n
JavaScript
const tokens = {\n  color: {\n    $type: 'color',\n    blue: { 600: { $value: { colorSpace: 'srgb', components: [0.122, 0.353, 0.878], hex: '#1f5ae0' } } },\n    white: { $value: { colorSpace: 'srgb', components: [1, 1, 1], hex: '#ffffff' } },\n    action: {\n      bg: { $value: '{color.blue.600}' },\n      text: { $value: '{color.white}' },\n    },\n  },\n  space: { $type: 'dimension', 4: { $value: { value: 1, unit: 'rem' } } },\n};\n\n// Walk the tree and collect every token with its path.\nfunction flatten(node, path = [], type) {\n  const t = node.$type ?? type;\n  if ('$value' in node) return [{ path, type: t, value: node.$value }];\n  return Object.entries(node)\n    .filter(([key]) => !key.startsWith('$'))\n    .flatMap(([key, child]) => flatten(child, [...path, key], t));\n}\n\nconst cssName = (path) => `--nw-${path.join('-')}`;\nfunction cssValue({ type, value }) {\n  if (typeof value === 'string' && value.startsWith('{')) {\n    return `var(${cssName(value.slice(1, -1).split('.'))})`; // keep the reference\n  }\n  if (type === 'color') return value.hex;\n  if (type === 'dimension') return `${value.value}${value.unit}`;\n  return String(value);\n}\n\nconst lines = flatten(tokens).map((t) => `  ${cssName(t.path)}: ${cssValue(t)};`);\nconsole.log(`/* Generated from tokens. Do not edit. */\\n:root {\\n${lines.join('\\n')}\\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.

\n

Keep the references

\n

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.

\n

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).

\n

A real pipeline with Style Dictionary

\n

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:

\n
build-tokens.mjs
import StyleDictionary from 'style-dictionary';\n\nconst themes = {\n  light: ':root',\n  dark: '[data-theme=\"dark\"]',\n};\n\nfor (const [name, selector] of Object.entries(themes)) {\n  const sd = new StyleDictionary({\n    include: ['tokens/primitives.tokens.json'],\n    source: [`tokens/semantic-${name}.tokens.json`],\n    platforms: {\n      css: {\n        transformGroup: 'css',\n        prefix: 'nw',\n        buildPath: 'dist/css/',\n        files: [{\n          destination: `theme-${name}.css`,\n          format: 'css/variables',\n          filter: name === 'light' ? undefined : (token) => token.isSource,\n          options: { selector, outputReferences: true },\n        }],\n      },\n    },\n  });\n  await sd.buildAllPlatforms();\n}
\n

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.

\n\n\n

Checks that run with the build

\n

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.

\n

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.

\n","toc":[{"id":"sec-1","text":"What a pipeline does","level":2},{"id":"sec-2","text":"Keep the references","level":2},{"id":"sec-3","text":"A real pipeline with Style Dictionary","level":2},{"id":"sec-4","text":"Checks that run with the build","level":2}],"takeaways":["A token pipeline parses source files, resolves aliases, transforms names and values per platform, and writes one output format per platform.","Keep references in CSS output (outputReferences) so semantic tokens still point at primitives at runtime and subtree theming keeps working.","Build each theme from shared primitives plus that theme’s semantic file, and emit only the theme’s own tokens under its selector.","Generated files are build output; nobody edits them by hand, and CI rebuilds them on every change."],"further":[{"title":"Style Dictionary (official repository and docs)","url":"https://github.com/style-dictionary/style-dictionary"},{"title":"Design Tokens Community Group repository","url":"https://github.com/design-tokens/community-group"},{"title":"Using CSS custom properties (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties"}],"quiz":[{"q":"

The pipeline writes --nw-color-action-bg: #1f5ae0; instead of --nw-color-action-bg: var(--nw-color-blue-600);. What breaks?

","options":[{"text":"Nothing; the color is identical.","why":"The color is identical today, but overriding the primitive at runtime no longer flows through, and the tiers are no longer visible in the output."},{"text":"The CSS becomes invalid because hex values aren’t allowed in custom properties.","why":"Custom properties accept any valid token stream, including hex colors."},{"text":"Browsers can’t cache the stylesheet.","why":"Caching doesn’t depend on what’s inside custom properties."},{"text":"Runtime overrides of primitives stop reaching semantic tokens, and debugging which primitive a token uses gets harder.","why":"Correct. With references preserved, the output keeps the tier structure; with resolved values, every link is flattened."}],"answer":3},{"q":"

Why does the dark theme build use include for primitives and source for the dark semantic file, then filter on isSource?

","options":[{"text":"Primitives are needed to resolve references, but only the dark semantic tokens should be written under the dark selector.","why":"Correct. Emitting primitives again under [data-theme="dark"] would duplicate hundreds of lines without changing anything."},{"text":"Files in include are loaded faster.","why":"Speed isn’t the point; the difference is whether tokens count as source tokens for filtering."},{"text":"Style Dictionary can’t read two files in source.","why":"The source array accepts many files and globs."}],"answer":0},{"q":"

A product engineer edits dist/css/theme-dark.css directly to fix a contrast bug, and the fix vanishes after the next release. What should the process have been?

","options":[{"text":"Commit the generated CSS so the edit is kept.","why":"Committing it doesn’t stop the next build from overwriting it; the source is still wrong."},{"text":"Fix the token in the source JSON, let CI rebuild, and mark generated files with a “do not edit” header.","why":"Correct. The JSON is the source of truth; generated files should say so at the top."},{"text":"Add the fix to the product’s own stylesheet instead.","why":"That hides the bug for one product and leaves every other consumer of the system with it."},{"text":"Turn off the build step for CSS.","why":"Then CSS and the other platforms drift apart, which is what the pipeline exists to prevent."}],"answer":1}],"exercise":{"kind":"fill","language":"js","template":"export default {\n include: ['tokens/primitives.tokens.json'],\n source: ['tokens/semantic-dark.tokens.json'],\n platforms: {\n css: {\n transformGroup: 'css',\n prefix: '{{0}}',\n buildPath: 'dist/css/',\n files: [{\n destination: 'theme-dark.css',\n format: '{{1}}',\n filter: (token) => token.{{2}},\n options: {\n selector: '{{3}}',\n outputReferences: {{4}},\n },\n }],\n },\n },\n};","blanks":[{"answers":["nw"]},{"answers":["css/variables"]},{"answers":["isSource"]},{"answers":["[data-theme=\"dark\"]","[data-theme=dark]"]},{"answers":["true"]}],"title":"Complete the dark theme build","prompt":"

Fill in the Style Dictionary config that generates Northwind’s dark theme. The output must:

\n\n","hints":["The format name is the same one used in the lesson’s build script.","Tokens loaded through source are marked differently from tokens loaded through include. Which property tells them apart?","The selector is the one from the themes lesson: an attribute selector on its own, without html."],"explanation":"

prefix: 'nw' adds the namespace to every name. css/variables writes custom properties inside the given selector. Filtering on token.isSource keeps the dark semantic tokens and drops the primitives, which were only included so references could resolve. [data-theme="dark"] lets any element start a dark subtree, and outputReferences: true keeps lines like --nw-color-action-bg: var(--nw-color-blue-400); so the tier structure survives into the browser.

\n","checkLabels":{}},"words":696,"readMinutes":3}