Build design tokens JSON into CSS variables

Some token references (1) could not be found. — that is what Style Dictionary prints when it stops on a broken token file. This guide turns a few token files into :root { --color-… } and uses that error as a check. The example JSON is hand-written.

[1] Install it in the project folder. Node.js is required; this guide ran on 24.

$ npm install style-dictionary$ npx style-dictionary --version

[2] Write the token files. Colors go in tokens/color.json. A $type on the group is inherited by the tokens below it, and brand.primary points at another token with {color.base.blue}.

{  "color": {    "$type": "color",    "base": {      "blue": { "$value": "#0b5fff" },      "gray": { "$value": "#f4f5f7" }    },    "brand": {      "primary": { "$value": "{color.base.blue}" }    }  }}

Spacing and fonts go in tokens/size.json. A font stack is an array.

{  "space": {    "$type": "dimension",    "sm": { "$value": "8px" },    "md": { "$value": "16px" }  },  "font": {    "family": {      "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }    },    "size": {      "base": { "$type": "dimension", "$value": "16px" }    }  }}

[3] Create config.json. source lists the tokens to read, transformGroup: "css" applies the CSS name and value transforms, and css/variables is the format that writes a :root block.

{  "source": ["tokens/**/*.json"],  "platforms": {    "css": {      "transformGroup": "css",      "buildPath": "build/css/",      "files": [{ "destination": "variables.css", "format": "css/variables" }]    }  }}

[4] Build.

$ npx style-dictionary build --config config.jsoncss✔︎ build/css/variables.css$ cat build/css/variables.css/** * Do not edit directly, this file was auto-generated. */ :root {  --color-base-blue: #0b5fff;  --color-base-gray: #f4f5f7;  --color-brand-primary: #0b5fff;  --space-sm: 8px;  --space-md: 16px;  --font-family-body: Inter, system-ui, sans-serif;  --font-size-base: 16px;}

Variable names are the JSON path joined with hyphens (color.base.blue → --color-base-blue). The reference in --color-brand-primary is resolved to #0b5fff.

[5] Add a reference that does not exist. In color.json, change {color.base.blue} to {color.base.bleu}.

$ npx style-dictionary build --config config.jsonfile:///…/node_modules/style-dictionary/lib/StyleDictionary.js:551        throw new Error(err);              ^ Error: Reference Errors:Some token references (1) could not be found.Use log.verbosity "verbose" or use CLI option --verbose for more details.Refer to: https://styledictionary.com/reference/logging/$ echo $?1

Add --verbose to see which token.

$ npx style-dictionary build --config config.json --verboseError: Reference Errors:Some token references (1) could not be found. {color.brand.primary} tries to reference {color.base.bleu}, which is not defined.

The exit code is 1, so CI and scripts fail on it as is. Two tokens referencing each other (c1 ↔ c2) stopped with the same Some token references (1) could not be found.

[6] A JSON syntax error gives a different message. A file with a missing closing brace stops while the file is being read.

Error: Failed to load or parse JSON or JS Object: JSON5: invalid end of input at 2:1

[7] Run token JSON from an AI through this build before using it. Put the file in tokens/, run the command from step 4, and check for exit code 0 and a variables.css. Invented reference names, typos and broken syntax get caught here.

A passing build does not prove the values are right. A token with "$type": "color" and "$value": "notacolor" built without an error in this setup and produced --color-bad: notacolor;. Add one more filter for the color variables.

$ grep -E '^\s+--color-' build/css/variables.css | grep -vE ': #[0-9a-fA-F]{3,8};$'  --color-bad: notacolor;

Any output line is a bad value. On a good file there is no output and grep exits 1. The pattern assumes hex colors only; change it if you use rgb() or hsl().

For the Figma side, see Convert Figma designs to code with Claude Code.