디자인 토큰 JSON 을 CSS 변수로 빌드하기

Some token references (1) could not be found. — 토큰 JSON 이 깨졌을 때 Style Dictionary 가 빌드를 멈추며 내는 문구입니다. 이 글은 토큰 파일 몇 개를 :root { --color-… } 로 바꾸고, 그 오류를 검증 수단으로 씁니다. 예시 JSON 은 직접 쓴 것입니다.

[1] 프로젝트 폴더에 설치합니다. Node.js 가 필요하고, 이 글은 24 에서 돌렸습니다.

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

[2] 토큰 파일을 만듭니다. 색은 tokens/color.json 입니다. $type 을 그룹에 한 번 적으면 아래 토큰이 이어받고, brand.primary 는 {color.base.blue} 로 다른 토큰을 가리킵니다.

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

간격과 글꼴은 tokens/size.json 에 둡니다. 글꼴 목록은 배열로 씁니다.

{  "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] 설정 파일 config.json 을 만듭니다. source 는 읽을 토큰, transformGroup: "css" 는 CSS 에 맞는 이름·값 변환 묶음, css/variables 는 :root 블록을 쓰는 출력 형식입니다.

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

[4] 빌드합니다.

$ 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;}

변수 이름은 JSON 경로를 하이픈으로 이은 것입니다(color.base.blue → --color-base-blue). --color-brand-primary 에는 참조가 풀려 #0b5fff 가 들어갔습니다.

[5] 일부러 없는 참조를 넣어 봅니다. color.json 의 {color.base.blue} 를 {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

어느 토큰인지는 --verbose 를 붙이면 나옵니다.

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

종료 코드가 1 이라 CI 나 스크립트에서 그대로 실패로 잡힙니다. 서로를 가리키는 순환 참조(c1 ↔ c2)도 같은 Some token references (1) could not be found. 로 멈췄습니다.

[6] JSON 문법 오류는 다른 문구입니다. 닫는 괄호를 빼먹은 파일을 넣으면 파일을 읽는 단계에서 멈춥니다.

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

[7] AI 가 만든 토큰 JSON 은 이 빌드를 통과시켜 본 뒤에 씁니다. tokens/ 에 파일을 넣고 [4] 의 명령을 돌려, 종료 코드 0 과 variables.css 를 확인합니다. 참조 이름을 지어내거나 오타를 낸 파일, 문법이 깨진 파일은 여기서 걸립니다.

빌드가 통과해도 값이 맞는다는 보장은 없습니다. "$type": "color" 인 토큰에 "$value": "notacolor" 를 넣어도 이 설정에서는 오류 없이 --color-bad: notacolor; 가 나왔습니다. 색 변수만 형식을 한 번 더 거릅니다.

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

출력이 한 줄이라도 있으면 잘못된 값입니다. 정상 파일에서는 출력이 없고 grep 종료 코드가 1 입니다. 16진수 색만 쓰는 토큰을 가정한 검사이므로 rgb() 나 hsl() 을 쓰면 패턴을 고칩니다.

Figma 쪽 작업은 Figma 디자인을 Claude Code 로 코드 변환하기 을 봅니다.