Carbon v10 主题系统迁移指南从 carbon-themes 升级到 carbon/themes【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本篇技术指南以 docs/migration/10.x-themes.md 为核心脉络系统讲解 Carbon Design System 在 v9 到 v10 版本间主题Themes系统的迁移路径carbon-themes已被弃用取而代之的是基于新版 IBM Design Language 的carbon/themes包。读者将掌握四种内置色彩组white、g10、g90、g100的 Sass / JavaScript 使用方式理解 v9 旧主题文件与 v10 色彩组的一一对应关系并能够从源码层面理解主题 token 的生成与落地机制从而在项目中安全、平滑地完成主题升级。一、为什么需要迁移v9 主题包的终结在 Carbon v10 之前主题能力由独立的carbon-themes包提供其中散落着carbon.scss、dark-ui.scss、experimental--light.scss、genesis.scss、watson.scss等多个主题文件。随着 v10 全面切换到新版 IBM Design Language 的色板体系这套旧文件结构被整体重构carbon-themes包已被正式弃用deprecated替代品为carbon/themes它为 Carbon v10 提供全部主题themes与色彩组color groups定义主题能力由分散的「主题文件」收敛为「四个标准色彩组」white、g10、g90、g100。这一收敛带来的直接好处是迁移不再需要逐个排查主题文件只需明确「我的界面属于哪个色彩组」然后在carbon/themes中按相同语义引入即可。二、安装 carbon/themes在迁移前先从包注册表中安装新包。根据 packages/themes/package.json该包名为carbon/themes当前仓库内版本为11.81.0其 Sass 入口指向index.scss。使用 npmnpm install -S carbon/themes或使用 Yarnyarn add carbon/themes该包依赖carbon/colors、carbon/layout、carbon/type等基础包安装时会一并解析。安装后可通过 Sass 或 JavaScript 两种方式引入详见 packages/themes/README.md。三、在 Sass 中使用新主题系统3.1 默认引入加载 white 色彩组最基础的用法是在 Sass 文件中引入主题模块。根据迁移文档直接引入后默认加载white色彩组import carbon/themes/scss/themes;也就是说仅这一行代码你的编译产物就会带上默认的浅色white主题 token。3.2 引入指定色彩组如果你需要某个特定的色彩组color group可以像下面这样直接引入并调用对应的主题 mixinimport carbon/themes/scss/g10; include carbon--theme-g10();white、g10、g90、g100四个色彩组都遵循同样的模式把g10替换为目标色彩组名称即可。例如深色界面使用g90import carbon/themes/scss/g90; include carbon--theme-g90();3.3 现代 Sass Module 语法use仓库当前版本的carbon/themes已全面采用 Sass Modules 语法。在 packages/themes/docs/sass.md 中官方推荐使用use方式引入并说明了各入口文件的用途入口说明use carbon/themes;包主入口重新导出各模块的值use carbon/themes/scss/config;配置项$prefix、$use-fallback-valueuse carbon/themes/scss/themes;四个主题定义white、g10、g90、g100use carbon/themes/scss/theme;设置当前主题、读取 token 值use carbon/themes/scss/tokens;访问主题 tokenuse carbon/themes/scss/compat/themes;v10 兼容版主题定义white/g10/g90/g100use carbon/themes/scss/compat/tokens;v10 兼容版主题 token在组件样式中使用主题 token会自动映射为 CSS 自定义属性Custom Propertiesuse carbon/themes; .my-component { color: themes.$token-01; // 编译后映射为 var(--cds-token-01) } :root { include themes.theme(); // 为当前主题输出 CSS 自定义属性 } // 读取某个 token 的具体值并参与运算 $custom-variable: rgba(themes.get(token-01), 0.25);切换默认主题则通过配置$theme完成use carbon/themes/scss/themes as *; use carbon/themes with ( $theme: $g100 );如果你希望扩展自己的自定义 token可以同时指定$fallback与$themepackages/themes/docs/sass.mduse carbon/themes/scss/themes; use carbon/themes with ( $fallback: themes.$g100, $theme: ( token-01: #000000, ) );3.4 为什么carbon/themes主入口不直接导出四个主题这是一个常见疑问既然scss/themes里定义了$white、$g10、$g90、$g100为什么主入口carbon/themes不重新导出它们答案在于 Sass Module 系统的限制见 packages/themes/docs/sass.md 的 FAQ为了支持use carbon/themes with (...)配置语法carbon/themes主入口不能重新导出themes模块。如果强行 re-export以下写法将导致同一模块被初始化两次而编译失败use carbon/themes/scss/modules/themes; use carbon/themes with ( $theme: themes.$g100 );因此官方约定四个主题只在scss/themes文件中可用需要切换主题时先use carbon/themes/scss/themes as *;拿到$g10、$g90、$g100等变量再将其作为配置传入主入口。四、在 JavaScript 中使用新主题系统除了 Sasscarbon/themes还导出一系列 JavaScript 绑定packages/themes/README.md适合在运行时如主题切换器、动态样式计算中使用import { // 所有主题的对象 themes, // 直接引用的主题值 white, g10, g90, g100, // 特定 token 值 interactive01, interactive02, } from carbon/themes;从源码看这些绑定定义在 packages/themes/src/v10/index.tsthemes对象聚合了white、g10、g90、g100四个模块同时把white模块下的所有 token以及tokens集合一并导出。因此你可以直接使用interactive01这类具体 token 名也可以遍历themes.g90取得整组主题值。五、迁移对照表v9 主题文件 → v10 色彩组迁移文档给出了完整的 v9 → v10 对照关系这是升级时的核心决策依据现完整列出如下v9v10themes/carbon.scssReplaced by thewhitecolor groupthemes/dark-ui.scssReplaced by theg90color groupthemes/experimental--light.scssReplaced by thewhitecolor groupthemes/genesis.scssRemovedthemes/watson.scssRemoved逐条解读themes/carbon.scss默认浅色主题→white色彩组两者语义一致都是标准浅色背景。直接替换引入即可。themes/dark-ui.scss暗色 UI 主题→g90色彩组v9 的暗色 UI 由 v10 的g90gray 90承接。从 packages/themes/src/v10/g90.ts 可以看到g90的uiBackground取值为gray90各层 UI 色为gray80、gray70与旧暗色主题的观感一致。themes/experimental--light.scss实验性浅色主题→white色彩组实验主题已被标准化的white取代。themes/genesis.scss、themes/watson.scss→ 移除这两个非标准主题在 v10 中没有任何对应物迁移时必须删除相关引用改用white、g10、g90、g100之一。注意v9 中并不存在g10的对应文件但 v10 额外提供了g10gray 10浅灰背景色彩组适用于面板/工作台类界面。若旧项目中曾使用自定义的浅灰背景可在迁移时评估是否直接切换到g10。六、源码级解析主题 token 是如何定义与落地的6.1 主题定义的单一数据源v10 的四个主题以 TypeScript 模块的形式定义在 packages/themes/src/v10 目录下white.ts、g10.ts、g90.ts、g100.ts。以 packages/themes/src/v10/white.ts 为例token 并非各自独立的魔法数值而是显式映射自carbon/colors的基础色板并复用adjustLightness、rgba等工具进行派生计算// packages/themes/src/v10/white.ts节选 export const interactive01 blue60; export const interactive02 gray80; export const uiBackground white; export const ui01 gray10; export const ui02 white; export const ui03 gray20; export const text01 gray100; export const text02 gray70; export const overlay01 rgba(gray100, 0.5); export const hoverPrimary #0353e9; export const activeUI gray30; export const skeleton01 #e5e5e5; export const hoverDanger adjustLightness(danger01, -8);这些 TS 模块随后通过 style-dictionary 与代码生成任务packages/themes/style-dictionary/sd.config.js、packages/themes/tasks/generate-js-tokens.js产出 Sass 变量与兼容入口最终由 packages/themes/scss/_themes.scss 通过forward generated/themes;对外提供。6.2 theme mixin从 Sass Map 到 CSS 自定义属性在 packages/themes/scss/_theme.scss 中可以看到主题落地的核心机制。thememixin 遍历当前主题的 Sass Map为每个 token 输出一条 CSS 自定义属性mixin theme($active-theme: $theme, $component-tokens...) { each $token, $value in $active-theme { include -custom-property($token, $value); } // ...组件级 token 处理 }其中-custom-property负责生成形如--cds-token: value的自定义属性cds前缀来自 packages/themes/scss/_config.scss 中的$prefix: cds !default。若 token 值是嵌套 Map如带values/fallback的组件 token还会调用-resolve-token-value按当前主题做多主题解析。同时该文件提供了两个实用 APIget($token)从当前$theme中取值找不到时抛出error Unable to find token...matches($a, $b)判断主题 B 是否为主题 A 的超集用于组件 token 的主题匹配。6.3 组件级 token 与多主题共存thememixin 还支持传入组件 token用于实现「同一组件在不同主题下取不同值」的需求use carbon/themes/scss/themes; use carbon/themes/scss/theme; // 默认使用 white 主题 .my-dark-theme { include theme.theme(themes.$g90); } .my-darker-theme { include theme.theme(themes.$g100); }这是实现暗色模式分区局部换肤的推荐姿势外层包一个选择器内层调用thememixin 注入对应主题的 CSS 自定义属性即可在不改组件代码的前提下完成多主题共存。组件 token 可通过add-component-tokensmixin 注册构建工具链中对应 packages/themes/src/tokens/components.ts 的组件 token 定义以及 packages/themes/scss/_component-tokens.scss 的 Sass 出口。6.4 兼容层v10 主题 token 的旧名兼容迁移过程中不可避免会遇到旧 token 名如ui01、text01。仓库在 packages/themes/scss/compat 下提供了兼容入口compat/themes重新导出 v10 四个主题compat/tokens提供 v10 主题 token旧命名风格。当你的代码还大量引用旧 token 名、无法一次性切换时可以先引入 compat 入口过渡再逐步迁移到新命名体系。七、迁移实操三步完成替换综合以上内容一次完整的 v9 → v10 主题迁移可以归纳为三步移除旧依赖与旧文件引用卸载carbon-themes删除对themes/carbon.scss、themes/dark-ui.scss、themes/experimental--light.scss、themes/genesis.scss、themes/watson.scss的所有import。确定目标色彩组并安装新包npm install -S carbon/themes或yarn add carbon/themes。参照第五节对照表浅色界面 →white浅灰界面 →g10暗色界面 →g90更深的对比暗色 →g100。按新语法引入并验证在全局样式中使用import carbon/themes/scss/themes;默认 white或import carbon/themes/scss/g90; include carbon--theme-g90();指定目标色彩组新版工程建议改用use语法见 3.3 节。最后在浏览器中核对背景、文字、链接、交互态等关键 token 是否符合预期。若工程已使用 CSS 自定义属性消费 token即var(--cds-*)升级后变量名与语义均应保持稳定这得益于thememixin 将 token 值统一落地为前缀化的自定义属性见 6.2 节。八、相关资源迁移文档原文docs/migration/10.x-themes.md包完整使用说明packages/themes/README.mdSass 入口与 API 文档packages/themes/docs/sass.md主题实现源码packages/themes/src/v10/white.ts、packages/themes/src/v10/g90.ts、packages/themes/src/v10/index.ts主题落地机制packages/themes/scss/_theme.scss、packages/themes/scss/_config.scss兼容入口packages/themes/scss/compat包配置与版本信息packages/themes/package.json【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考