UI 视觉设计 / 系统课时
配置 Style Dictionary 源文件
配置 Style Dictionary 源文件
将一份含有基础色和组件别名的 DTCG JSON 编译为浏览器可用的 CSS 自定义属性。本课使用 Style Dictionary v5,从安装依赖、指定源文件和构建平台,到检查首个生成文件,完成一条可以在项目中复现的构建链。
学习目标
- 在 Node.js 22 及以上环境安装 Style Dictionary v5。
- 用
source、transformGroup、buildPath和files配置 CSS 输出。 - 运行构建命令,核对别名解析结果并定位常见路径错误。
检查环境并安装依赖
在一个空项目目录中打开终端,先用 node --version 确认 Node.js 版本不低于 22.0.0。Style Dictionary v5 要求 Node.js 22 及以上;下方命令使用 npm,适用于 macOS、Linux 和已安装 Node.js 的 Windows 终端。
npm init -y
npm install --save-dev style-dictionary@^5
npx style-dictionary --version预期结果:项目出现 package.json、package-lock.json 和 node_modules;最后一条命令打印 5.x.x,具体次版本和补丁版本由实际安装结果决定。采用本地开发依赖而不是全局安装,可以让团队通过锁文件复现工具版本。
编写最小 DTCG 输入文件
在项目根目录创建 tokens/colors.json。每个叶子 Token 使用 $type 指定数据类型、$value 指定值;花括号表示对另一个 Token 路径的引用。本例让按钮背景复用品牌蓝,让按钮文字复用白色。
{
"color": {
"brand": {
"600": { "$type": "color", "$value": "#2563eb" }
},
"text": {
"onBrand": { "$type": "color", "$value": "#ffffff" }
},
"button": {
"primary": {
"background": {
"$type": "color",
"$value": "{color.brand.600}"
},
"foreground": {
"$type": "color",
"$value": "{color.text.onBrand}"
}
}
}
}
}这里的 color、brand、button 都是分组,只有包含 $value 的对象才是 Token。引用写的是完整的点分隔路径,而不是生成后的 CSS 变量名。保存时保持标准 JSON 格式,不要加入注释或尾随逗号。
连接源文件与 CSS 构建平台
在项目根目录创建 config.json。先只配置一个 css 平台,避免混入尚未需要的原生端转换规则。
{
"source": ["tokens/**/*.json"],
"usesDtcg": true,
"platforms": {
"css": {
"transformGroup": "css",
"buildPath": "build/css/",
"files": [
{
"destination": "variables.css",
"format": "css/variables",
"options": { "showFileHeader": false }
}
]
}
}
}source 匹配 tokens 目录下的 JSON 文件,多份文件会按 Token 路径合并;不要把生成目录也放进这个匹配范围。usesDtcg: true 明确使用带 $ 前缀的 DTCG 属性,虽然 v5 通常也能自动识别。
transformGroup: "css" 应用内置的 CSS 命名与值转换;format: "css/variables" 将结果写成 :root 自定义属性。buildPath 是输出目录,末尾必须保留 /;destination 是该目录内的文件名。关闭 showFileHeader 可避免生成文件头部包含构建时间。

执行构建并核对生成内容
保持终端当前目录为包含 config.json 的项目根目录,运行:
npx style-dictionary build --config config.json预期结果:命令执行成功后生成 build/css/variables.css,其中的主要内容如下。变量声明的排列顺序可以不同,检查名称和值即可。
:root {
--color-brand-600: #2563eb;
--color-text-on-brand: #ffffff;
--color-button-primary-background: #2563eb;
--color-button-primary-foreground: #ffffff;
}本例没有设置 outputReferences: true,所以组件别名在输出中被解析为实际色值,而不是 var(...) 引用。为验证输入确实参与构建,可把源文件中的品牌蓝改为 #1d4ed8,再次执行相同命令;预期 --color-brand-600 和 --color-button-primary-background 同时变为该新值。
处理首次构建的典型问题
- 提示配置文件不存在:检查终端所在目录;使用
--config config.json明确指定文件,或传入实际相对路径。 - 没有生成预期变量:核对
tokens/colors.json是否落在tokens/**/*.json匹配范围内,检查$value拼写和 JSON 语法。 - 提示引用未找到或循环引用:确认
{color.brand.600}与源对象层级逐段一致,引用链不能回到自身;可在构建命令中添加--verbose获取更多诊断信息。 - 文件生成到了别处:检查
buildPath末尾的/以及files[].destination。两者合起来才是输出文件路径。
完成后应同时保存 tokens/colors.json、config.json 和锁文件;build/css/variables.css 是可重新生成的构建产物。之后增加 SCSS 或其他平台时,可以在同一份 source 上继续配置独立平台,而不修改基础 Token 数据。