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 终端。

bash
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 路径的引用。本例让按钮背景复用品牌蓝,让按钮文字复用白色。

json
{
  "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 平台,避免混入尚未需要的原生端转换规则。

json
{
  "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 可避免生成文件头部包含构建时间。

DTCG 源文件通过 Style Dictionary 配置转换为 CSS 自定义属性的数据流

执行构建并核对生成内容

保持终端当前目录为包含 config.json 的项目根目录,运行:

bash
npx style-dictionary build --config config.json

预期结果:命令执行成功后生成 build/css/variables.css,其中的主要内容如下。变量声明的排列顺序可以不同,检查名称和值即可。

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 数据。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置 Style Dictionary 源文件

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

登录哪都通