Skip to main content

Frontend development · Intermediate · 16 min

Generate CSS from a token file with Style Dictionary

By Padding · Updated 18 Nov 2026
Node.js 26 · Style Dictionary 5.8.0 · Design Tokens Format Module 2025.10 · checked in Chromium 159

You will have the Larkfield Clinic design tokens in JSON files, a Style Dictionary build that turns them into CSS custom properties and a JavaScript module with one npm script, and a build that fails loudly when a token reference is broken, so it can run in CI.

On this page

A design token file is only useful if the code reads from it. Copy its values into a stylesheet by hand and you have two sources of truth again, and they start to disagree the first time someone is in a hurry. The fix is a build step: the JSON file is the only place a value is written, and a tool generates the CSS, and anything else the app needs, from it.

Style Dictionary is an open-source build tool for exactly this. It reads token files, resolves references between tokens, runs each token through transforms for a target platform (CSS names in kebab case, JavaScript names in Pascal case, colours as hex) and writes one or more output files per platform. Version 5 reads the Design Tokens Community Group format, where every token is an object with a $value and a $type. That format's 2025.10 version is a stable Community Group report, not a W3C Standard, Figma's variable import and export follow it, and Style Dictionary and Tokens Studio, among others, can read it.

You will build the token pipeline for Larkfield Clinic, the fictional community clinic whose appointment booking app runs through the design tutorials. Its designers keep the tokens as Figma variables in two collections, Larkfield primitives and Larkfield, and export them to JSON. Here you take those two files, generate tokens.css and tokens.js from them, point a small demo page at the CSS, and push one real change through: the new colour/notice-border token from Keep a design system in sync with code.

Step 1 · Create the project and install Style Dictionary

Make a folder for the token build and install Style Dictionary as a development dependency. --save-exact writes 5.8.0 into package.json rather than a range, so every machine and every CI run builds with the same version until you choose to upgrade:

Bash
mkdir -p ~/larkfield-tokens-demo
cd ~/larkfield-tokens-demo
npm init -y > /dev/null
npm pkg set type=module
npm install --save-dev --save-exact style-dictionary@5.8.0
npx style-dictionary --version

npm pkg set type=module tells Node.js to treat .js files in this folder as ES modules. You need that later, when you import the generated JavaScript file.

Style Dictionary is a build tool, so it belongs in devDependencies. The app ships the files it generates, not Style Dictionary itself.

Check it worked

The last command prints 5.8.0. package.json has "style-dictionary": "5.8.0" under devDependencies, with no ^ in front of the number, and "type": "module" near the top. A package-lock.json file sits next to it.

Step 2 · Write the primitive tokens

Primitives are the raw values: every colour step and size the system allows, named by what they are rather than what they are for. In Larkfield's naming rule a primitive is family/step, which becomes nested groups in JSON: teal/700 is the token 700 inside the group teal.

Create tokens/primitives.tokens.json. This file holds the steps the semantic tokens need, plus amber.500, which you use later. A file exported from the full Larkfield palette would hold all forty colour steps; the build treats it the same way.

Bash
mkdir -p tokens
cat > tokens/primitives.tokens.json <<'JSON'
{
  "grey": {
    "$type": "color",
    "0": { "$value": "#ffffff" },
    "50": { "$value": "#f3f5f8" },
    "200": { "$value": "#cfd5dc" },
    "500": { "$value": "#7f848b" },
    "600": { "$value": "#656970" },
    "900": { "$value": "#20242a" }
  },
  "teal": {
    "$type": "color",
    "50": { "$value": "#ebf8f7" },
    "700": { "$value": "#0f5e5a" }
  },
  "red": {
    "$type": "color",
    "50": { "$value": "#fef2f0" },
    "600": { "$value": "#b42318" }
  },
  "amber": {
    "$type": "color",
    "50": { "$value": "#fff3e5" },
    "500": { "$value": "#aa782f" },
    "600": { "$value": "#8a5a00" }
  },
  "space": {
    "$type": "dimension",
    "4": { "$value": { "value": 4, "unit": "px" } },
    "8": { "$value": { "value": 8, "unit": "px" } },
    "12": { "$value": { "value": 12, "unit": "px" } },
    "16": { "$value": { "value": 16, "unit": "px" } },
    "24": { "$value": { "value": 24, "unit": "px" } },
    "32": { "$value": { "value": 32, "unit": "px" } },
    "48": { "$value": { "value": 48, "unit": "px" } }
  },
  "radius": {
    "$type": "dimension",
    "4": { "$value": { "value": 4, "unit": "px" } },
    "8": { "$value": { "value": 8, "unit": "px" } },
    "999": { "$value": { "value": 999, "unit": "px" } }
  },
  "border": {
    "$type": "dimension",
    "1": { "$value": { "value": 1, "unit": "px" } },
    "2": { "$value": { "value": 2, "unit": "px" } }
  }
}
JSON

Three details of the format matter here:

  • $type on a group applies to every token in it. Writing "$type": "color" once on grey saves repeating it six times.
  • Dimensions are objects. The 2025.10 format writes a size as a number and a unit, { "value": 16, "unit": "px" }, not as the string "16px". Style Dictionary turns the object into 16px in the CSS.
  • Colours here are hex strings. The 2025.10 format itself writes a colour as an object with a colour space and components, and it may also carry a hex field. Style Dictionary 5 reads both forms: since version 5.3 its colour transforms accept the object form, and use its hex field as a fallback when a colour falls outside the sRGB range. Hex strings keep this file short. If your exporter writes objects, leave them as they are.

Check it worked

Check that the file is valid JSON and list its top-level groups:

Bash
node -e "const t = JSON.parse(require('fs').readFileSync('tokens/primitives.tokens.json', 'utf8')); console.log(Object.keys(t).join(' '))"

It prints grey teal red amber space radius border. If you see SyntaxError instead, look for a missing comma or a comma after the last item in a group, which JSON does not allow.

Step 3 · Write the semantic tokens as references

Semantic tokens are named for a job (colour/accent, space/m) and hold no values of their own. Each one points at a primitive with a reference: the primitive's path in curly braces, with dots between the groups, such as {teal.700}. This is why token names must never contain a dot.

Create tokens/larkfield.tokens.json:

Bash
cat > tokens/larkfield.tokens.json <<'JSON'
{
  "colour": {
    "$type": "color",
    "text": { "$value": "{grey.900}" },
    "text-muted": { "$value": "{grey.600}" },
    "surface": { "$value": "{grey.0}" },
    "canvas": { "$value": "{grey.50}" },
    "line": { "$value": "{grey.200}" },
    "border": { "$value": "{grey.500}" },
    "accent": { "$value": "{teal.700}" },
    "accent-tint": { "$value": "{teal.50}" },
    "on-accent": { "$value": "{grey.0}" },
    "danger": { "$value": "{red.600}" },
    "danger-tint": { "$value": "{red.50}" },
    "notice": { "$value": "{amber.600}" },
    "notice-tint": { "$value": "{amber.50}" }
  },
  "space": {
    "$type": "dimension",
    "2xs": { "$value": "{space.4}" },
    "xs": { "$value": "{space.8}" },
    "s": { "$value": "{space.12}" },
    "m": { "$value": "{space.16}" },
    "l": { "$value": "{space.24}" },
    "xl": { "$value": "{space.32}" },
    "2xl": { "$value": "{space.48}" }
  },
  "radius": {
    "$type": "dimension",
    "s": { "$value": "{radius.4}" },
    "m": { "$value": "{radius.8}" },
    "full": { "$value": "{radius.999}" }
  },
  "border": {
    "$type": "dimension",
    "thin": { "$value": "{border.1}" },
    "thick": { "$value": "{border.2}" }
  }
}
JSON

Notice that space appears in both files. Style Dictionary merges every source file into one tree before it resolves anything, so space.m and space.16 end up as siblings in the same group, and {space.16} finds its target even though it lives in the other file. The flip side is that two files must never define the same token path. If they do, the file read last wins, and the build prints Token collisions detected as a warning while still succeeding, so read the build output rather than trusting the tick alone.

Check it worked

You have two files in tokens/. Every $value in larkfield.tokens.json is a reference in curly braces, and none is a hex code or a number. Every reference names a primitive that exists in primitives.tokens.json: {red.600} yes, {red.700} no, because Larkfield's danger red sits at step 600 on its ramp.

Step 4 · Configure the CSS and JavaScript outputs

The configuration tells Style Dictionary where the tokens are and what to build from them. Each entry under platforms is one target with its own transforms and its own output files. Create config.json, the file name the command looks for by default:

Bash
cat > config.json <<'JSON'
{
  "source": ["tokens/**/*.tokens.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "build/css/",
      "files": [
        {
          "destination": "tokens.css",
          "format": "css/variables",
          "options": { "outputReferences": true }
        }
      ]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "build/js/",
      "files": [
        {
          "destination": "tokens.js",
          "format": "javascript/es6"
        }
      ]
    }
  }
}
JSON

What each part does:

  • source is a list of glob patterns. Every matching file is read and merged. New token files in tokens/ are picked up without touching the config.
  • transformGroup is a named set of transforms. The built-in css group joins the token path with hyphens for the name (colour.accent-tint becomes colour-accent-tint) and writes colours as hex. The js group uses Pascal case names instead (ColourAccentTint).
  • format decides the shape of the file. css/variables writes custom properties inside :root. javascript/es6 writes one export const per token.
  • outputReferences: true keeps the link between layers in the CSS. Without it, --colour-accent would hold #0f5e5a. With it, it holds var(--teal-700), so changing a primitive in the browser's developer tools updates every semantic token that points at it, the same behaviour you get in Figma.

The JavaScript output always holds resolved values. A chart library or a canvas drawing needs a real colour string, not var(...).

Check it worked

config.json has two platforms, css and js, each with its own buildPath and one file under files. You prove it in the next step: when you run npm run tokens:build, the output lists build/css/tokens.css and build/js/tokens.js, each with a tick.

Step 5 · Add an npm script and run the build

Give the build a name in package.json, so you, your teammates and CI run it the same way and nobody needs to remember the command:

Bash
npm pkg set scripts.tokens:build="style-dictionary build"
npm run tokens:build

Style Dictionary prints each platform and each file it wrote, with a tick. Look at the CSS:

Bash
cat build/css/tokens.css

It starts with a comment saying the file is generated and must not be edited, followed by one :root block. The primitives come first with real values, then the semantic tokens as references to them. Part of it:

CSS
:root {
  --teal-700: #0f5e5a;
  --space-16: 16px;
  --colour-accent: var(--teal-700);
  --colour-accent-tint: var(--teal-50);
  --space-m: var(--space-16);
  --radius-m: var(--radius-8);
}

Then the JavaScript module. Import one value from it with Node.js:

Bash
node --input-type=module -e "import { ColourAccent, SpaceM } from './build/js/tokens.js'; console.log(ColourAccent, SpaceM)"

Check it worked

The import prints #0f5e5a 16px. build/css/tokens.css holds thirteen --colour- custom properties, each set to a var(--...) of a primitive, and --teal-700: #0f5e5a. If a semantic token shows a hex code instead of var(...), outputReferences is missing from the CSS file's options.

Step 6 · Use the generated CSS in a page

Components should use only the semantic custom properties. Build a small demo page: the Continue button from the Pick a time screen, and the notice the screen shows when the time a patient picked has just been taken.

Bash
cat > index.html <<'HTML'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Larkfield tokens demo</title>
  <link rel="stylesheet" href="build/css/tokens.css">
  <link rel="stylesheet" href="demo.css">
</head>
<body>
  <main class="screen">
    <h1>Pick a time</h1>
    <p class="muted">Nurse appointment, 15 min · Tue 9 Dec</p>
    <p class="notice" role="status">10:30 was just taken. Choose another time.</p>
    <button class="button-primary" type="button">Continue</button>
  </main>
</body>
</html>
HTML
cat > demo.css <<'CSS'
body {
  margin: 0;
  font-family: system-ui, sans-serif;
  background: var(--colour-canvas);
  color: var(--colour-text);
}
.screen { padding: var(--space-m); max-width: 30rem; }
.muted { color: var(--colour-text-muted); }
.notice {
  padding: var(--space-s) var(--space-m);
  border-radius: var(--radius-m);
  background: var(--colour-notice-tint);
  color: var(--colour-notice);
}
.button-primary {
  margin-top: var(--space-xl);
  padding: var(--space-s) var(--space-l);
  border: 0;
  border-radius: var(--radius-m);
  background: var(--colour-accent);
  color: var(--colour-on-accent);
  font: inherit;
  font-weight: 600;
}
CSS

tokens.css loads first, because demo.css reads the custom properties it defines. Custom properties are resolved when the browser computes styles, so the order of the two <link> tags does not strictly matter; loading the tokens first makes the dependency obvious to the next person.

tokens.css is about 1.5 KB, and browsers cache it like any other stylesheet. On a patient's low-cost Android phone with prepaid data, that is a smaller cost than one icon. Serve it with your other CSS rather than inlining a copy in every page, so the cache does its job.

Check it worked

Open index.html in a browser (open index.html on macOS, xdg-open index.html on Linux, or drag the file into a browser window). The page has a pale grey background, a pale amber notice with dark amber text, and a dark teal Continue button with white text and rounded corners. Right-click the button, choose Inspect, and look at the Styles panel: background shows var(--colour-accent), and the computed value is rgb(15, 94, 90), which is #0F5E5A. The notice has no border yet.

Step 7 · Change a token and rebuild

The Larkfield team tested Pick a time on a cheap Android phone outdoors and found that the notice barely stands out: its pale amber fill is close to the pale grey screen behind it, so it reads as ordinary text. The fix agreed in the design system is a new semantic token, colour/notice-border, pointing at the existing primitive amber/500 (#AA782F), drawn as a thin border on the notice.

In a real project this change arrives as a fresh export from Figma. Here, add the token to tokens/larkfield.tokens.json yourself. The file below is the same as before with one new line, notice-border, at the end of the colour group:

Bash
cat > tokens/larkfield.tokens.json <<'JSON'
{
  "colour": {
    "$type": "color",
    "text": { "$value": "{grey.900}" },
    "text-muted": { "$value": "{grey.600}" },
    "surface": { "$value": "{grey.0}" },
    "canvas": { "$value": "{grey.50}" },
    "line": { "$value": "{grey.200}" },
    "border": { "$value": "{grey.500}" },
    "accent": { "$value": "{teal.700}" },
    "accent-tint": { "$value": "{teal.50}" },
    "on-accent": { "$value": "{grey.0}" },
    "danger": { "$value": "{red.600}" },
    "danger-tint": { "$value": "{red.50}" },
    "notice": { "$value": "{amber.600}" },
    "notice-tint": { "$value": "{amber.50}" },
    "notice-border": { "$value": "{amber.500}" }
  },
  "space": {
    "$type": "dimension",
    "2xs": { "$value": "{space.4}" },
    "xs": { "$value": "{space.8}" },
    "s": { "$value": "{space.12}" },
    "m": { "$value": "{space.16}" },
    "l": { "$value": "{space.24}" },
    "xl": { "$value": "{space.32}" },
    "2xl": { "$value": "{space.48}" }
  },
  "radius": {
    "$type": "dimension",
    "s": { "$value": "{radius.4}" },
    "m": { "$value": "{radius.8}" },
    "full": { "$value": "{radius.999}" }
  },
  "border": {
    "$type": "dimension",
    "thin": { "$value": "{border.1}" },
    "thick": { "$value": "{border.2}" }
  }
}
JSON
npm run tokens:build

Now use the token in the component. Add a rule at the end of demo.css, after the existing .notice rule, so it adds the border without repeating the other properties:

Bash
cat >> demo.css <<'CSS'

.notice {
  border: var(--border-thin) solid var(--colour-notice-border);
}
CSS

Then check that both outputs picked up the change:

Bash
grep -- '--colour-notice-border' build/css/tokens.css
node --input-type=module -e "import { ColourNoticeBorder } from './build/js/tokens.js'; console.log(ColourNoticeBorder)"

Check it worked

The grep prints --colour-notice-border: var(--amber-500); and the import prints #aa782f. You changed one JSON file and both outputs moved. Reload the page in the browser: the notice now has a thin amber edge, and Inspect shows its border colour coming from var(--colour-notice-border), not a typed hex code.

Step 8 · Make the build safe to run in CI

A build that runs in CI has to do two things: produce the same output on every machine, and stop the pipeline when the tokens are wrong.

The first is already in place. The exact version in package.json and the lockfile mean npm ci installs the same Style Dictionary everywhere. Prove it by deleting everything generated or installed, and building from the committed files alone, the way a CI job starts:

Bash
rm -rf node_modules build
npm ci
npm run tokens:build
ls build/css build/js

For the second, see what a broken reference does. A typo in a reference is the most common token mistake: someone types {amber.550} for a step that does not exist. Add a file with exactly that mistake:

Bash
cat > tokens/typo.tokens.json <<'JSON'
{
  "colour": {
    "$type": "color",
    "warning": { "$value": "{amber.550}" }
  }
}
JSON

Run the build again:

Bash
npm run tokens:build

Style Dictionary stops with something like this, spread over several lines:

Text
Error:
Reference Errors:
Some token references (1) could not be found.

followed by a hint about --verbose and a Node.js stack trace. The stack trace is normal for this error; the tool has not crashed, it is reporting the broken reference. The command exits with a non-zero code, which is what fails a CI job. Add --verbose to see which token and which reference: npx style-dictionary build --verbose. Delete the file with the mistake and build again to get back to a clean state:

Bash
rm tokens/typo.tokens.json
npm run tokens:build

In your CI system, the token job is the two commands you just ran: npm ci, then npm run tokens:build. Put it before the app's own build, so a broken token stops the pipeline before anything ships. Whether you commit the build/ folder or generate it in CI is a team choice. Generating it keeps reviews short, because only the JSON changes in a pull request; committing it lets people without Node.js read the output. Pick one and write it in the README next to the tokens.

Check it worked

After npm ci, the build recreated build/css/tokens.css and build/js/tokens.js from nothing. With the typo file present, the build stopped with a reference error; without it, the build succeeds and prints a tick for each file.

Step 9 · Clean up

Remove the demo folder:

Bash
cd ~
rm -rf ~/larkfield-tokens-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Digital Transformation

Get new tutorials

New tutorials, about twice a month.