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 GroupDTCG制定的行业标准 JSON 格式承载四大主题令牌与五个组件令牌并经由 Style Dictionary 流水线编译为 SCSS 与 JS 产物。读完本文你将能够定位并阅读 DTCG 令牌文件、理解$schema/$type/$value/$description/$extensions的完整语法、跑通从yarn build到scss/generated/的生成链路并学会如何校验与新增一个组件令牌文件。DTCG 格式与 Carbon 的迁移背景DTCGDesign Tokens Community Group是 W3C 社区组发布的开放规范它定义了用 JSON 表达设计令牌的标准化格式使颜色、尺寸、字体族等设计决策可以在设计工具与代码之间无损流转。Carbon 设计系统已将全部主题令牌与组件令牌迁移到这一行业标准格式存放于 packages/themes/src/dtcg 目录——也就是说该目录就是carbon/themes的“单一事实来源”所有 SCSS / JS 产物都由它编译而来而非手工维护。从 packages/themes/package.json 可以看到构建依赖中引入了style-dictionaryv5与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: lightwhite / 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 buildyarn 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 DictionaryrunScss()与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: trueStyle 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-cliajv validate -s https://tr.designtokens.org/format/schema.json -d white.jsoncarbon/themes的 devDependencies 中确实包含ajv与ajv-formats说明校验链路贯穿于开发与 CI 流程。贡献指南如何安全地增改令牌在添加或修改令牌时README 与源码共同确认了以下规范遵循 DTCG 规范— 所有令牌必须符合官方规范的结构包含有意义的描述— 每个令牌都要有清晰的$description使用正确的类型— 设置恰当的$typecolor、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），仅供参考