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:
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 --versionnpm 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.
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" } }
}
}
JSONThree details of the format matter here:
$typeon a group applies to every token in it. Writing"$type": "color"once ongreysaves 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 into16pxin 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
hexfield. Style Dictionary 5 reads both forms: since version 5.3 its colour transforms accept the object form, and use itshexfield 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:
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:
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}" }
}
}
JSONNotice 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:
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"
}
]
}
}
}
JSONWhat each part does:
sourceis a list of glob patterns. Every matching file is read and merged. New token files intokens/are picked up without touching the config.transformGroupis a named set of transforms. The built-incssgroup joins the token path with hyphens for the name (colour.accent-tintbecomescolour-accent-tint) and writes colours as hex. Thejsgroup uses Pascal case names instead (ColourAccentTint).formatdecides the shape of the file.css/variableswrites custom properties inside:root.javascript/es6writes oneexport constper token.outputReferences: truekeeps the link between layers in the CSS. Without it,--colour-accentwould hold#0f5e5a. With it, it holdsvar(--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:
npm pkg set scripts.tokens:build="style-dictionary build"
npm run tokens:buildStyle Dictionary prints each platform and each file it wrote, with a tick. Look at the CSS:
cat build/css/tokens.cssIt 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:
: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:
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.
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;
}
CSStokens.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:
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:buildNow 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:
cat >> demo.css <<'CSS'
.notice {
border: var(--border-thin) solid var(--colour-notice-border);
}
CSSThen check that both outputs picked up the change:
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:
rm -rf node_modules build
npm ci
npm run tokens:build
ls build/css build/jsFor 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:
cat > tokens/typo.tokens.json <<'JSON'
{
"colour": {
"$type": "color",
"warning": { "$value": "{amber.550}" }
}
}
JSONRun the build again:
npm run tokens:buildStyle Dictionary stops with something like this, spread over several lines:
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:
rm tokens/typo.tokens.json
npm run tokens:buildIn 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:
cd ~
rm -rf ~/larkfield-tokens-demoNext steps
- Turn design tokens into CSS custom properties goes deeper into the stylesheet side: two token layers in CSS, and how to check that a component never reaches past the semantic layer.
- Add dark mode with CSS variables shows how a second set of values for the same semantic names gives you a dark theme.
- Keep a design system in sync with code is the designer's half of this pipeline: exporting the token files from Figma, the change log and the monthly drift check.
- Name design tokens from primitives to roles explains the naming rule behind
teal/700andcolour/accent-tint, and why a token name never contains a dot.
Part of these paths
Related tutorials
- Turn design tokens into CSS custom propertiesYou will have a two-layer tokens.css file of primitive and semantic custom properties, component styles that use only the semantic layer, a Node script that enforces that rule, and a demo page that proves one primitive change reaches every component.
- Keep a design system in sync with codeYou will have a versioned Larkfield design system with a change log, its tokens exported from Figma into the code repository, an approval rule for new tokens and components, one real change shipped through all of it, and a monthly drift checklist.
- Name design tokens from primitives to rolesYou will have the Larkfield Clinic values split into a primitives collection and a semantic collection in Figma variables, every semantic token aliasing a primitive, and a one-paragraph naming rule your team can apply to any new token.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials