Carbon Design System 主题预览Themes preview本地运行指南基于 carbon/themes 的 Token 可视化工具【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本指南围绕 IBM Carbon Design System 仓库中 packages/themes/examples/preview/README.md 展开介绍如何在本地构建并运行「主题预览」示例应用——一个基于 Next.js 的 Token 可视化工具它把carbon/themes提供的 white、g10、g90、g100 四套主题的全部颜色 Token 以表格形式呈现在浏览器中。读完本文你将掌握该预览应用的完整启动流程、底层数据组织方式Token 分组 / Token 集合 / Token 命名格式以及如何把它当作调试和验证主题 Token 的日常工具。一、预览应用是什么从 README 到源码关联文档是一份简短的 Getting Started 说明核心只有两件事先在仓库根目录构建再进入packages/themes/examples/preview目录安装依赖并启动开发服务器。整个流程如下# 1. 在 carbon 仓库根目录执行 yarn install yarn build # 2. 进入 preview 示例目录 cd packages/themes/examples/preview # 3. 安装该示例的依赖二选一 yarn install # 或 npm install # 4. 启动开发服务器二选一 yarn develop # 或 npm run develop启动成功后用浏览器打开 http://localhost:3000 即可看到结果。从源码结构看这个 preview 不是一个普通的前端演示而是一个「主题 Token 数据透视表」package.json 声明了三个关键依赖carbon/themes以link:../../指向本仓库源码、carbon/colorslink:../../../colors以及next、react、sassdevelop脚本就是nextbuild脚本是next buildnext.config.js 在生产构建阶段设置basePath: /themes/examples/preview、output: export即支持导出为纯静态站点部署同时通过turbopack.root把模块解析根指向仓库根目录这正是它能直接引用仓库内carbon/themes源码而非 npm 上的发布版本的原因src/pages/_app.js 是 Next.js 应用外壳唯一职责是引入 src/scss/styles.scss后者提供了预览表格、吸顶表头、色块预览等全部样式。二、页面核心逻辑Token 表格是如何渲染出来的预览页面的主体实现在 src/pages/index.js它 import 了三个来自../../../../src即 packages/themes/src的模块import { themes } from ../../../../src; import { TokenFormat, group, set as tokenSet } from ../../../../src/tokens;随后在模块加载阶段一次性构建三份元数据const tokens group.getTokens(); // 全部 Token 列表 const groups group.getTokenGroups(); // Token 分组Background、Layer、Text、Link 等 const properties group.getTokenProperties(); // Token 属性background、border、text 等 const tokenSets tokenSet.getTokenSets(); // Token 集合按层级/场景划分的集合页面的表格表头固定为五列Token、White、g10、g90、g100与Properties。每一行对应一个 Token四个主题列各渲染一个色块color-preview 颜色名 HEX 值色块通过行内样式注入style{{ --color-preview-color: themes.white[exportName] }}配合 styles.scss 中.color-preview { background: var(--color-preview-color); }实现颜色名由colorsByValue反向映射得到——页面启动时遍历carbon/colors的全部色阶swatch grade与 hover 色用TokenFormat.convert({ name, format: TokenFormat.formats.scss })将gray-10这类名字转成gray-10形态的 SCSS 变量名后登记到值-名字的映射中每个 Token 名渲染为页内锚点a href{#${token.name}}配合 styles.scss 中[id] { scroll-margin-top: ... }的样式点击表内链接可直接定位。页面还提供了三个联动筛选器Token group / Token set / Properties和一个 Reset 按钮全部在前端通过React.useState完成过滤无需请求后端。三、可交互的筛选与过滤逻辑在 src/pages/index.js 的IndexPage组件中三个状态分别对应三个下拉框const [activeGroup, setActiveGroup] React.useState(All); const [activeProperty, setActiveProperty] React.useState(All); const [activeSet, setActiveSet] React.useState(All);渲染 Token 行时按以下规则过滤Token group若activeGroup ! All则要求token.groups包含当前分组Properties若activeProperty ! All则要求token.properties包含当前属性Token set若activeSet ! All则调用tokenSet.getTokenSet(activeSet)并检查set.hasToken(token.name)。只要任一过滤条件不满足就跳过该行。三个条件同时为默认值All时表格展示全部 Token——这也是页面顶部Tokens ({tokens.length})计数的含义。四、底层支撑carbon/themes 的 Token 数据模型预览应用的价值在于它直接消费carbon/themes的源码结构因此理解它就能顺带理解主题包的数据模型。相关实现集中在 packages/themes/src/tokensTokenGroup分组v11TokenGroup.ts 定义了 Background、Layer、Text、Link 等分组每个分组声明自己的properties如 background、border、text和一组 Token 名部分 Token 还附带stateactive、hover、selected 等例如background-active、layer-hover-01。TokenSet集合TokenSet.ts 的注释点明了它的设计意图“A token set is a collection of tokens which should be used along with each other.”一组应当配套使用的 Token例如对应 UI 某一层级layer level的 Token 会聚成一个集合TokenSet通过[Symbol.iterator]支持嵌套展开getTokenSets()递归返回自身及所有子集合getTokenSet(name)按名字查找hasToken(name)判断集合是否包含某 Token。TokenFormat命名转换TokenFormat.ts 负责在 JavaScript 与 SCSS 命名之间互转转 JS 时把 kebab-case 转 camelCaseinteractive-01-interactive01ui-background中的ui会按保留关键字处理为大写UI转 SCSS 时则在遇到数字scale step时截断并补-并把连续大写字母如UI处理成连写小写。而 packages/themes/src/index.ts 汇总导出四套主题white、g10、g90、g100来自构建产物js/generated/themes/由yarn build中的build:js-tokens任务生成并将group、set、TokenFormat等一并对外暴露——预览页正是通过这条链路拿到全部 Token 元数据的。页面底部还会通过getStaticProps输出lastBuiltOn构建时间戳方便确认当前展示的是哪一次构建的 Token。五、常见问题与排查建议必须先构建根仓库index.ts的注释明确指出其 import 指向js/generated/构建产物需要先执行根目录的yarn build或至少运行yarn build:js-tokens对应的任务生成后再启动 preview否则页面可能因找不到生成文件而报错。这也是 README 第一步要求yarn install yarn build的原因。依赖采用 link 指向源码carbon/themes与carbon/colors在 package.json 中分别以link:../../、link:../../../colors关联到本仓库包因此示例永远预览「当前仓库源码」的主题 Token而非 npm 上已发布版本——修改仓库内主题 Token 后重新构建preview 即可看到最新值。端口占用Next.js 默认监听 3000若被占用可自行调整端口后重试。生产构建如需导出静态站点可在 preview 目录运行yarn build即next build产物输出到build/目录并带有/themes/examples/preview的 basePath。六、小结packages/themes/examples/preview是理解 Carbon Design System 主题体系的最直观入口一条yarn install yarn build加yarn develop的命令链就能把carbon/themes的四套主题与全部 Token 元数据变成一张可筛选、可定位、可对照的在线表格。配合 packages/themes/src/tokens 下的 TokenGroup、TokenSet、TokenFormat 实现你既能快速核对某个 Token 在 white / g10 / g90 / g100 中的取值差异也能把group、set等 API 复用到自己的主题调试工具中。更多主题包用法Sass 与 JavaScript 两种消费方式可参考 packages/themes/README.md 及其 Sass 文档。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考