Style Dictionary：转换与生成令牌

Style Dictionary（由 Amazon 创建）是一种构建工具，可以读取 JSON 格式的设计令牌定义，并将其输出为任意目标格式：CSS 自定义属性、JavaScript ES 模块、Sass 变量、iOS Swift 常量、Android XML 资源，以及您定义的任何自定义格式。一个事实来源，多种输出。

使用 npm install --save-dev style-dictionary 进行安装。使用 npx style-dictionary init 初始化项目结构，该命令会创建 config.json（或 config.js）和一个 tokens/ 目录。配置会告诉 Style Dictionary 从哪里查找令牌文件，以及将输出写入何处。

Style Dictionary 使用嵌套的 JSON 结构，其中叶节点包含 value 属性。例如：{ "color": { "primary": { "500": { "value": "#3b82f6" } } } }。通向该值的路径（颜色、主色、500）会在转换后成为令牌名称，通常格式为 color-primary-500 或 --color-primary-500。

运行 npx style-dictionary build --config config.json（如果已在 package.json 脚本中配置，也可以运行 style-dictionary build）。Style Dictionary 会读取配置源中的所有令牌文件，应用转换，并将输出写入配置的目标位置。令牌格式中的错误会随文件名和路径一起报告。

config.json 定义了多个平台：css（输出包含自定义属性的 CSS 文件）、js（输出 JS 对象）和 scss（输出 Sass 变量）。每个平台都会指定输出目录、文件名、格式（模板）以及要应用的转换（名称和值处理函数）。

Style Dictionary 包含多种内置转换：name/cti/kebab 将嵌套路径转换为 color-primary-500，name/cti/camel 生成 colorPrimary500，size/rem 将像素值转换为 rem，color/hex 将颜色规范化为十六进制格式。转换可以组合，并会按顺序应用。

您可以使用 StyleDictionary.registerTransform() 注册自定义转换。例如，可以将像素值转换为 iOS 点值，或为所有令牌名称添加公司专用前缀。自定义转换让您可以完全控制值在输出前的处理方式。

自定义格式定义输出文件的模板。StyleDictionary.registerFormat() 接收转换后令牌的字典，并返回一个字符串，即文件内容。您可以将令牌输出为 TypeScript 类型、React 主题对象、Tailwind 配置扩展，或技术栈所需的任何其他格式。

构建完成后，在全局样式表中导入 CSS 输出：@import './tokens/tokens.css'。在组件或 Tailwind 配置中导入 JS 输出：import tokens from './tokens/tokens.js'。CSS 会提供用于运行时主题切换的自定义属性；JS 会提供供 Tailwind 和 JavaScript 逻辑使用的类型化常量。

Style Dictionary 支持使用花括号引用令牌：{ "value": "{color.primary.500}" }。这会创建语义令牌别名，即语义令牌引用一个原始令牌。构建时，Style Dictionary 会解析这些引用，并输出最终解析后的值（或者根据格式输出 CSS 变量引用）。

将 Style Dictionary 作为 prebuild npm 脚本运行，以便在应用构建前始终重新生成令牌。将 "prebuild": "style-dictionary build" 添加到 package.json 中。这样可以确保令牌 JSON 文件的任何变更，都会在 React 构建处理这些输出之前反映到 CSS 和 JS 输出中。

Style Dictionary 中的转换有什么作用？

Style Dictionary 可以将令牌 JSON 转换为任意输出格式：CSS 变量、JS 模块、Sass、iOS 和 Android。令牌 JSON 使用包含 value 叶节点的嵌套对象。转换负责处理名称和值（camelCase、像素转 rem）；格式负责定义输出模板。令牌引用（{color.primary.500}）支持语义别名。使用 prebuild 脚本自动化处理，确保在 React 构建前令牌始终是最新的。