UI 视觉设计 / 系统课时
编写命名和单位转换规则
编写命名和单位转换规则
要把同一组 Design Token 稳定编译为 CSS,必须让变量名、单位和元数据各按明确规则转换。本课使用 Style Dictionary 5.x 配置内置 Transform,并实现带 ui- 前缀的命名规则与 px 到 rem 的单位转换,最终验证生成的 CSS 变量。
学习目标
- 区分
attribute、name、value三类 Transform 的职责。 - 配置内置规则并编写按 Token 类型过滤的自定义转换。
- 检查命名、零值、换算基准和构建结果是否符合约定。
Transform 改变哪些内容
Style Dictionary 为每个输出平台依次执行所配置的转换;原始 Token 数据不应被当作已转换的 CSS。三类 Transform 分别处理不同的信息:
| 类型 | 常见内置规则 | 可核查的效果 |
|---|---|---|
attribute |
attribute/cti |
从路径补出 category、type 等元数据,不直接改 CSS 值 |
name |
name/kebab |
space.controlGap 命名为 space-control-gap |
value |
size/pxToRem、color/css |
把尺寸换算为 rem,或把颜色转换为 CSS 可用表示 |
内置规则的名称和匹配类型可查阅 Style Dictionary Transform 文档。特别注意:size/rem 只附加单位,不等于 size/pxToRem 的按基准换算。一个平台通常只配置一种名称转换;叠加两个 name Transform,后者可能覆盖前者的命名结果。

准备 DTCG 源数据
示例适用于 Style Dictionary 5.x 和 Node.js 22 及以上版本。在项目根目录创建 tokens.json,使用 DTCG 的 $type 和 $value:尺寸值是包含 value 与 unit 的对象,不是把 px 拼进字符串。
{
"space": {
"controlGap": {
"$type": "dimension",
"$value": { "value": 8, "unit": "px" }
},
"panelPadding": {
"$type": "dimension",
"$value": { "value": 24, "unit": "px" }
}
},
"radius": {
"card": {
"$type": "dimension",
"$value": { "value": 12, "unit": "px" }
}
},
"border": {
"none": {
"$type": "dimension",
"$value": { "value": 0, "unit": "px" }
}
}
}这里有三个非零尺寸和一个零值。预期换算依次是 0.5rem、1.5rem、0.75rem、0。保留零值样本,可检查是否符合本例规定的无单位零值 0;0rem 虽合法,却不符合这里的输出约定。
编写两条自定义规则
在项目根目录创建 build.mjs。自定义 name/ui-kebab 按路径生成带前缀的名称;size/px-to-rem 只作用于 $type 为 dimension 的 Token,同时允许原本就是 rem 的值通过,拒绝未知单位。
import StyleDictionary from 'style-dictionary';
StyleDictionary.registerTransform({
name: 'name/ui-kebab',
type: 'name',
transform: (token) => {
// 统一 camelCase、下划线和多级路径,避免不同组件采用不同拼写
const parts = token.path.map((part) =>
String(part)
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
.replace(/[\s_]+/g, '-')
.toLowerCase()
);
return `ui-${parts.join('-')}`;
},
});
const BASE_PX = 16;
StyleDictionary.registerTransform({
name: 'size/px-to-rem',
type: 'value',
filter: (token) => token.$type === 'dimension',
transform: (token) => {
const { value, unit } = token.$value ?? {};
// 不把未知单位悄悄写进 CSS;16 是本项目约定的设计换算基准
if (!Number.isFinite(value) || !['px', 'rem'].includes(unit)) {
throw new Error(`无效尺寸:${token.path.join('.')}`);
}
const rem = unit === 'px' ? value / BASE_PX : value;
return rem === 0 ? '0' : `${Number(rem.toFixed(4))}rem`;
},
});
const sd = new StyleDictionary({
source: ['tokens.json'],
platforms: {
css: {
transforms: [
'attribute/cti',
'name/ui-kebab',
'color/css',
'size/px-to-rem'
],
buildPath: 'build/',
files: [{
destination: 'tokens.css',
format: 'css/variables',
options: { showFileHeader: false }
}]
}
}
});
await sd.buildAllPlatforms();预期结果:执行此脚本后会写出 build/tokens.css,文件包含四个带 ui- 前缀的 CSS 自定义属性,具体值在下一节逐项核对。
attribute/cti 可用于后续分类或过滤,但不会替换 DTCG 的 $type;color/css 只会命中颜色类型,本例的四个尺寸均交给自定义值转换。没有使用 transformGroup: 'css',是为了避免其内置尺寸规则与自定义规则重复执行。
运行构建并检查结果
在保存好两个文件后,从项目根目录执行以下命令;安装 Style Dictionary 为开发依赖即可,运行时页面并不需要加载它。
npm init -y
npm install --save-dev 'style-dictionary@^5'
node build.mjs预期结果:生成 build/tokens.css。其中应包含下列 CSS 声明(具体排列顺序可能不同):
:root {
--ui-space-control-gap: 0.5rem;
--ui-space-panel-padding: 1.5rem;
--ui-radius-card: 0.75rem;
--ui-border-none: 0;
}用 8 ÷ 16 = 0.5、24 ÷ 16 = 1.5、12 ÷ 16 = 0.75 逐项核算。再把 panelPadding 的源值改为 32px 所对应的对象数值 32,重新运行 node build.mjs;预期 --ui-space-panel-padding 更新为 2rem,而 CSS 变量名不变。
修正易出错的边界
- 同名冲突:
controlGap与control-gap都会归一化成control-gap。合入前检查生成文件中的变量是否唯一,必要时调整源 Token 路径。 - 基准误用:这里固定按设计基准
16px = 1rem换算;它不会强制用户浏览器的根字号为16px。页面修改根字号后,渲染尺寸会随rem变化。 - 类型误配:若把颜色或时间也交给尺寸转换,会出现无效输出;用
filter限定$type,对不支持的尺寸单位主动报错。 - 重复转换:不要在
transformGroup: 'css'后再无条件追加另一条尺寸转换;应明确列出需要的 Transform,并检查它们的执行顺序。
实际项目应把命名规则、基准字号和允许的单位写进构建约定,并把生成 CSS 的差异检查放进代码评审;这样新增 Token 时就能识别意外改名或数值漂移。