UI 视觉设计 / 系统课时
配置 Style Dictionary
配置 Style Dictionary
把设计变量导出的 DTCG JSON 接入 Style Dictionary 4,分别生成浏览器可用的 CSS 自定义属性和 JavaScript ES 模块。完成依赖安装、双平台配置与别名核验后,同一份令牌就能通过命令重复构建。
学习目标
- 配置 Style Dictionary 4 的 DTCG 输入与异步构建入口。
- 为 CSS 和 JavaScript 分别设置转换组、输出路径和格式。
- 验证语义别名是否按目标平台正确保留或解析。
检查环境并安装依赖
本例适用于 Style Dictionary 4.x,要求 Node.js 18 或更新版本。在一个新的 npm 项目根目录操作,先确认环境并安装依赖。
# 确认 Node.js 版本,并安装 Style Dictionary 4
node --version
npm init -y
npm install --save-dev style-dictionary@4预期结果:node --version 显示 18 或更新的主版本,安装成功后出现 package.json、package-lock.json 和 node_modules/。终端中的版本号、审计提示与耗时因环境而异。提交项目时保留锁文件,让团队及 CI 使用相同的依赖版本。
本例使用以下文件约定:
| 路径 | 职责 |
|---|---|
tokens/base.json |
DTCG 原始令牌 |
build.mjs |
Style Dictionary 构建入口 |
build/css/variables.css |
生成的 CSS 自定义属性 |
build/js/tokens.mjs |
生成的 JavaScript ES 模块 |
build/ 是自动生成目录,不应直接修改其中的值。设计变量发生变化时,应更新 tokens/ 下的源文件并重新构建。
建立 DTCG 输入文件
新建 tokens/base.json。这里同时放入一个基础颜色和一个语义别名,用来验证构建工具确实能处理 DTCG 的 $type、$value 与花括号引用,而不只是复制 JSON。
{
"color": {
"$type": "color",
"base": {
"blue": {
"600": { "$value": "#2563eb" }
}
},
"action": {
"primary": { "$value": "{color.base.blue.600}" }
}
}
}$type 由 color 分组向下继承,两个令牌都属于颜色类型。color.action.primary 通过 {color.base.blue.600} 引用基础颜色,而不是再次填写具体色值。
这样设计有两个可检查的结果:基础颜色为 #2563eb,语义别名解析后的颜色也为 #2563eb。以后修改基础色时,语义颜色可以随引用关系更新。
定义双平台转换和输出
在项目根目录新建 build.mjs。使用 .mjs 扩展名可以直接调用 v4 的 ES Module 接口,不要求修改整个项目的模块类型。
import StyleDictionary from 'style-dictionary';
const dictionary = new StyleDictionary({
usesDtcg: true,
source: ['tokens/**/*.json'],
platforms: {
css: {
transformGroup: 'css',
buildPath: 'build/css/',
files: [{
destination: 'variables.css',
format: 'css/variables',
// 保留 CSS 变量引用,让基础色变化能传递给语义变量。
options: { outputReferences: true, showFileHeader: false }
}]
},
js: {
transformGroup: 'js',
buildPath: 'build/js/',
files: [{
destination: 'tokens.mjs',
format: 'javascript/es6'
}]
}
}
});
// v4 构建是异步操作,必须等待所有平台的文件写入完成。
await dictionary.buildAllPlatforms();
console.log('Token 构建完成');这里有四组需要区分的配置:
| 配置字段 | 本例取值 | 作用 |
|---|---|---|
source |
tokens/**/*.json |
查找并读取令牌源文件 |
transformGroup |
css、js |
应用对应平台的内置转换规则 |
format |
css/variables、javascript/es6 |
指定输出文件的语法格式 |
buildPath + destination |
各平台目录与文件名 | 决定最终生成位置 |
CSS 平台使用内置 css 转换组,将名称转换为短横线风格,并通过 css/variables 输出 :root 中的自定义属性。
JavaScript 平台使用内置 js 转换组,将名称转换为 PascalCase,再通过 javascript/es6 输出具名导出的常量。两条构建链使用同一份 DTCG 输入,但分别执行转换和格式化,不会互相覆盖。

CSS 的 outputReferences: true 是本例的重要选择。它使语义变量在输出中继续引用基础变量,而不是立即展开成固定色值。JavaScript 输出则采用已经解析的值,方便应用直接导入常量。
运行构建并验证产物
在项目根目录执行:
node build.mjs预期输出:Style Dictionary 可能先打印各平台的文件生成日志,最后一行应为:
Token 构建完成随后打开 build/css/variables.css,核心内容应为:
:root {
--color-base-blue-600: #2563eb;
--color-action-primary: var(--color-base-blue-600);
}检查重点是 --color-action-primary 是否引用 --color-base-blue-600,而非仅仅检查两个变量的颜色是否相同。如果基础色发生变化,CSS 语义变量可以通过 var(...) 继续引用更新后的基础值。
JavaScript 产物 build/js/tokens.mjs 应包含 ColorBaseBlue600 和 ColorActionPrimary 等具名导出。因为这里的 JavaScript 格式没有启用保留引用的选项,别名会解析为实际颜色值。
运行独立导入验证:
node --input-type=module -e "import { ColorActionPrimary } from './build/js/tokens.mjs'; console.log(ColorActionPrimary)"预期输出:
#2563eb可以再做一次变更验证:将 tokens/base.json 的基础色从 #2563eb 改为 #1d4ed8,保留语义别名不变,重新执行 node build.mjs。此时 CSS 基础变量应更新为 #1d4ed8,语义变量仍保持 var(--color-base-blue-600);JavaScript 的 ColorActionPrimary 则应解析为 #1d4ed8。
这项验证能够确认两个平台确实消费了相同的令牌源,而不是依赖手工维护的重复值。注意,JavaScript 常量是构建时确定的值,并不会自动跟随浏览器运行时的 CSS 变量变化。
排查构建失败
| 现象 | 优先检查 | 修复方法 |
|---|---|---|
找不到 style-dictionary 包 |
是否在当前项目安装依赖 | 在项目根目录重新执行 npm install;v4 使用 import,不要直接照搬 v3 的 require 初始化方式 |
| 没有生成令牌或产物缺少内容 | source 是否匹配 tokens/base.json |
检查工作目录、文件路径、JSON 语法及 $value 字段 |
| 提示引用无法解析 | {color.base.blue.600} 是否与令牌层级一致 |
修复引用路径、大小写或缺失的基础令牌,再重新构建 |
| CSS 语义变量变为固定色值 | outputReferences 是否被关闭 |
在 CSS 文件配置中设置 options.outputReferences: true |
| JavaScript 导入报模块错误 | 输出文件的模块格式与运行环境 | 保持 javascript/es6 格式与 .mjs 扩展名,并使用 ES Module 导入 |
如果构建能完成却没有预期变量,不要先修改生成文件。应回到 tokens/base.json 和 build.mjs,依次检查源文件匹配、DTCG 字段、引用路径、平台转换组和输出格式。
最终验收应同时满足三个条件:CSS 文件包含两个变量且保留语义引用,JavaScript 模块可以成功导入并返回正确色值,修改基础令牌后重新构建能够同步更新两端产物。满足这些条件后,就可以把构建命令接入项目脚本或 CI 流程。