Carbon 设计系统 DTCG 设计令牌（Design Tokens）格式全解析：目录结构、Token 规范与 Style Dictionary 构建验证-创锋一号

Carbon 设计系统 DTCG 设计令牌（Design Tokens）格式全解析：目录结构、Token 规范与 Style Dictionary 构建验证

【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon

本篇技术指南聚焦 IBM Carbon Design System 仓库中@carbon/themes包的设计令牌（Design Tokens）体系：它如何以 W3C Design Tokens Community Group（DTCG）制定的行业标准 JSON 格式承载四大主题令牌与五个组件令牌，并经由 Style Dictionary 流水线编译为 SCSS 与 JS 产物。读完本文，你将能够定位并阅读 DTCG 令牌文件、理解$schema/$type/$value/$description/$extensions的完整语法、跑通从yarn build到scss/generated/的生成链路，并学会如何校验与新增一个组件令牌文件。

DTCG 格式与 Carbon 的迁移背景

DTCG（Design Tokens Community Group）是 W3C 社区组发布的开放规范，它定义了用 JSON 表达设计令牌的标准化格式，使颜色、尺寸、字体族等设计决策可以在设计工具与代码之间无损流转。Carbon 设计系统已将全部主题令牌与组件令牌迁移到这一行业标准格式，存放于 packages/themes/src/dtcg 目录——也就是说，该目录就是@carbon/themes的“单一事实来源”，所有 SCSS / JS 产物都由它编译而来，而非手工维护。

从 packages/themes/package.json 可以看到，构建依赖中引入了style-dictionary（v5）与ajv、ajv-formats，这正是 DTCG 数据被解析、转换和校验的底层工具链。

目录结构：主题文件与组件文件的分层

packages/themes/src/dtcg/下按“主题层”与“组件层”分为两层：

dtcg/ ├── white.json # White 主题（浅色、高对比） ├── g10.json # Gray 10 主题（浅色） ├── g90.json # Gray 90 主题（深色） ├── g100.json # Gray 100 主题（深色、高对比） └── components/ ├── button.json # Button 组件令牌 ├── tag.json # Tag 组件令牌 ├── notification.json # Notification 组件令牌 ├── status.json # 状态指示器令牌 └── content-switcher.json # Content switcher 令牌

这一分层与 style-dictionary/sd.config.js 中的两组常量一一对应：THEME_NAMES = ['white', 'g10', 'g90', 'g100']、COMPONENT_NAMES = ['button', 'tag', 'notification', 'status', 'content-switcher']。新增组件时只需同时扩展这两个层面。

Token 格式规范：DTCG 键的完整语义

所有令牌文件都遵循 DTCG 规范的结构化格式。以 white.json 和 components/button.json 的实际内容为证，逐键说明如下。

必需键

$schema：声明所遵循的 DTCG 规范版本，位于文件根级，固定为"https://tr.designtokens.org/format/"。四个主题文件与五个组件文件均以此开头。
$type：令牌类型，例如"color"、"dimension"、"fontFamily"等。它让工具链可以针对性地做类型校验与渲染。主题与组件文件中的令牌几乎全部是"color"。
$value：令牌的实际值，可以是字面量，也可以是引用其他令牌的引用串：
- 引用语法使用花括号："{blue.60}"、"{gray.80}"、"{white.default}"；
- 引用在构建阶段被解析（resolve），最终产物中呈现为已解析的颜色值。
$description：人类可读的用途说明。Carbon 要求每个令牌都必须有清晰、可执行的描述，供设计师与开发者理解“何时使用”。例如 white.json 中background的描述是 “Default page background color. Use as the base surface for the entire application or page.”

可选键：`$extensions`

$extensions用于承载自定义元数据与厂商专有信息，Carbon 主要使用两个命名空间：

carbon.themes—— 组件令牌的主题差异值。组件令牌通常不写死$value，而是为每个主题分别给出取值：

"$extensions": { "carbon.themes": { "white": "{blue.60}", "g10": "{blue.60}", "g90": "{blue.60}", "g100": "{blue.60}" } }

在真实文件中，carbon.themes还会出现fallback键作为默认值。例如 button.json 的separator令牌写为：

"$extensions": { "carbon.themes": { "fallback": "{gray.20}", "white": "{gray.20}", "g10": "{gray.20}", "g90": "{gray.100}", "g100": "{gray.100}" } }

org.carbon—— Carbon 专属元数据，典型用例是透明度修饰符与配色模式：

"$extensions": { "org.carbon": { "alphaModifier": 0.5, "color-scheme": "light" } }

alphaModifier表示在基础色之上叠加的透明度，例如background-hover取{gray.50}并附加alphaModifier: 0.12。除了单数键alphaModifier，组件文件中还会使用复数形式alphaModifiers按主题细分：button.json 的disabled令牌即为g90/g100分别配置0.3的透明度。主题级文件还会在根级$extensions.org.carbon中声明"color-scheme": "light"（white / g10）或深色对应值，为浏览器原生控件配色提供依据。

主题令牌实例

以下节选自 white.json 的真实结构：

{ "$schema": "https://tr.designtokens.org/format/", "$description": "White theme - Light theme with high contrast for optimal readability", "background": { "$type": "color", "$value": "{white.default}", "$description": "Default page background color. Use as the base surface for the entire application or page." }, "background-hover": { "$type": "color", "$value": "{gray.50}", "$description": "Background color for hover state. Use when user hovers over interactive elements to provide visual feedback.", "$extensions": { "org.carbon": { "alphaModifier": 0.12 } } } }

注意$schema与$description位于文件根级（后者描述了整个主题），令牌则以扁平键名平铺；嵌套仅发生在语义分组上（如layer.01、layer.hover-01这类 “01 / 02 层级” 令牌）。

组件令牌实例

组件令牌以组件名作为顶层命名空间，components/button.json 覆盖了按钮的全部变体与状态：primary/primary-hover/primary-active、secondary系列、tertiary系列、danger-primary/danger-hover/danger-active/danger-secondary、disabled与separator。每个令牌都通过carbon.themes给出四个主题的取值：

{ "button": { "primary": { "$type": "color", "$description": "Background color for primary buttons in default state. Use for the main call-to-action on a page or in a workflow step.", "$extensions": { "carbon.themes": { "white": "{blue.60}", "g10": "{blue.60}", "g90": "{blue.60}", "g100": "{blue.60}" } } } } }

组件令牌展示了引用系统的精妙之处：primary-hover在四个主题中都引用{blue.60Hover}、secondary在浅色主题引用{gray.80}而深色主题引用{gray.60}、danger-secondary甚至为g90/g100分别选用了{red.40}/{red.50}以保证深色背景下的可读性——主题适配的粒度细化到了令牌级。

主题令牌分类：四个主题、250+ 令牌

四个主题文件对应 Carbon 的四大主题：

white.json— White 主题（浅色、高对比）；
g10.json— Gray 10 主题（浅色，企业默认）；
g90.json— Gray 90 主题（深色）；
g100.json— Gray 100 主题（深色、高对比）。

每个主题文件包含 250+ 个令牌，按语义分为三大类：

颜色令牌（Color tokens）：背景（background）、层级（layer）、字段、边框、文本、链接、图标、支持色（support）等；
语义令牌（Semantic tokens）：焦点（focus）、交互态（interactive）、高亮（highlight）、遮罩（overlay）、骨架屏（skeleton）等；
AI 令牌（AI tokens）：面向 AI 场景的专用颜色，覆盖 popover、chat 与骨架屏状态。

从源码结构看，AI 令牌与语义令牌在 white.json 中同样以扁平键名出现（如ai-popover-background一类命名），共享同一套 DTCG 语法，因此工具链无需特殊分支即可处理它们。

构建流程：从 DTCG JSON 到 SCSS / JS 产物

触发构建

进入主题包目录执行：

cd packages/themes yarn build

yarn build实际是一串复合命令（见 package.json）：先clean清理产物，再生成 JS 令牌、打包 TS 入口、执行 tasks/build.js、最后生成类型声明并做 SCSS 检查。

Style Dictionary 流水线

tasks/build.js 将 DTCG 的编译委托给 style-dictionary/sd.config.js。构建分为两个阶段：

生成调色板：generateDTCGColorAliases()从@carbon/colors生成color-palette.json（未提交、构建期产生），为{blue.60}这类引用提供解析目标；
运行 Style Dictionary：runScss()与runJs()按themeConfig(themeName)/componentConfig(componentName)分别产出 SCSS 与 JS 产物。

配置中的关键自定义插件：

transforms（值转换）：
- carbon/name-kebab：把令牌路径（token path）拼成 kebab-case 名称，并剥离_self段（双角色父节点专用）；
- carbon/alpha-modifier：把$extensions.org.carbon中的alphaModifier/alphaModifiers应用到颜色值；
- carbon/color-flatten：将引用解析为最终色值。两个转换均标记为transitive: true，Style Dictionary 会反复应用直至数值稳定，且顺序有讲究：alpha 修饰必须先于颜色展平执行。
preprocessors（预处理）：component-tokens（把carbon.themes的主题差异值展开为-by-theme-后缀的独立令牌）、theme-metadata（注入主题元数据）、dual-role（处理“既有$value又有子节点”的双角色令牌，避免 Style Dictionary v5 将父节点当叶子而丢弃子令牌）。
formats（输出格式）：carbon/scss-themes、carbon/scss-tokens、carbon/scss-component-tokens、carbon/js-themes、carbon/js-component-tokens，分别渲染 SCSS 主题表、SCSS 令牌表、SCSS 组件令牌表以及对应 JS 模块与.d.ts声明。

生成产物

构建会在scss/generated/下生成：

_themes.scss— 全部四个主题的令牌映射表（四个主题先各自写入临时文件，再由runScss拼接去重为一个文件）；
_tokens.scss— 令牌表；
_button-tokens.scss、_tag-tokens.scss、_notification-tokens.scss、_status-tokens.scss、_content-switcher-tokens.scss— 五个组件的令牌表。

JS 侧则生成js/generated/themes/{white,g10,g90,g100}.{js,d.ts}与js/generated/component-tokens/{button,tag,…}.{js,d.ts}。

这些生成文件由两个转发入口对外暴露：

scss/_themes.scss — 转发主题令牌；
scss/_component-tokens.scss — 转发组件令牌。

同时，tasks/build.js还通过builders/compat中的手工 builder 生成scss/compat/generated/下的兼容层，保证旧版 v10/v11 用法（如$carbon--theme--white）在迁移期间仍可用。

验证：DTCG JSON Schema 校验

构建过程会对所有 DTCG 令牌文件依据官方 DTCG JSON Schema 做自动校验，确保：

$schema引用正确；
$type取值合法（color、dimension 等）；
令牌结构规范；
必填字段齐全。

除构建期自动校验外，也可用任意 JSON Schema 校验器手动校验，例如使用ajv-cli：

ajv validate -s https://tr.designtokens.org/format/schema.json -d white.json

@carbon/themes的 devDependencies 中确实包含ajv与ajv-formats，说明校验链路贯穿于开发与 CI 流程。

贡献指南：如何安全地增改令牌

在添加或修改令牌时，README 与源码共同确认了以下规范：

遵循 DTCG 规范— 所有令牌必须符合官方规范的结构；
包含有意义的描述— 每个令牌都要有清晰的$description；
使用正确的类型— 设置恰当的$type（color、dimension 等）；
提供主题差异值— 组件令牌使用$extensions.carbon.themes覆盖四个主题；
校验改动— 运行yarn build触发 DTCG Schema 校验；
验证生成产物— 确认 SCSS / JS 生成正确（可检查scss/generated/与js/generated/）；
同步文档— 若新增令牌类别或组件，同步更新本文档。

新增一个组件令牌文件的完整步骤

创建src/dtcg/components/your-component.json；
参考现有组件令牌文件的结构（如 button.json）；
用$extensions.carbon.themes提供各主题取值，必要时配合fallback键与org.carbon.alphaModifiers；
把组件名加入 style-dictionary/sd.config.js 的COMPONENT_NAMES数组，使其进入构建流程；
更新 README，补充新组件令牌的说明。

结语

Carbon 将主题与组件令牌整体迁移到 DTCG 标准格式，意味着设计数据可以在 Figma、Style Dictionary 与 Carbon 组件库之间用同一种语言表达：white.json/g10.json/g90.json/g100.json提供主题级基础令牌，components/下的五个文件用carbon.themes扩展承载跨主题差异，再经 Style Dictionary 的自定义 transform 与 preprocessor 编译成 SCSS 表与 JS 模块。对使用者而言，这套体系带来的直接收益是：令牌的来源单一、格式可被通用工具校验、主题适配下沉到每个令牌级——无论是排查一个颜色的取值，还是新增一种组件的主题变量，都能在src/dtcg下找到答案，并通过一次yarn build验证全部改动。

【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析