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,后者可能覆盖前者的命名结果。

同一 Token 经元数据、命名和尺寸转换后输出 CSS 的顺序

准备 DTCG 源数据

示例适用于 Style Dictionary 5.x 和 Node.js 22 及以上版本。在项目根目录创建 tokens.json,使用 DTCG 的 $type 和 $value:尺寸值是包含 value 与 unit 的对象,不是把 px 拼进字符串。

json
{
  "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 的值通过,拒绝未知单位。

js
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 为开发依赖即可,运行时页面并不需要加载它。

bash
npm init -y
npm install --save-dev 'style-dictionary@^5'
node build.mjs

预期结果:生成 build/tokens.css。其中应包含下列 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 时就能识别意外改名或数值漂移。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写命名和单位转换规则

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通