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 项目根目录操作,先确认环境并安装依赖。

bash
# 确认 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。

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 接口,不要求修改整个项目的模块类型。

js
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 输入,但分别执行转换和格式化,不会互相覆盖。

DTCG 令牌分流生成 CSS 与 JavaScript 产物

CSS 的 outputReferences: true 是本例的重要选择。它使语义变量在输出中继续引用基础变量,而不是立即展开成固定色值。JavaScript 输出则采用已经解析的值,方便应用直接导入常量。

运行构建并验证产物

在项目根目录执行:

bash
node build.mjs

预期输出:Style Dictionary 可能先打印各平台的文件生成日志,最后一行应为:

text
Token 构建完成

随后打开 build/css/variables.css,核心内容应为:

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 格式没有启用保留引用的选项,别名会解析为实际颜色值。

运行独立导入验证:

bash
node --input-type=module -e "import { ColorActionPrimary } from './build/js/tokens.mjs'; console.log(ColorActionPrimary)"

预期输出:

text
#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 流程。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置 Style Dictionary

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

登录哪都通