OpenMetadata UI 颜色设计令牌体系--om-color-*双层 Token 架构、暗色模式与 token-audit 强校验实战指南【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadataOpenMetadata 前端在向 UntitledUI Tailwind 迁移的同时仍需长期维护一套基于 Ant Design Less 的旧有样式栈为此构建了双层颜色令牌体系组件只引用语义化的--om-color-*项目别名底层映射到openmetadata/ui-core-components提供的--color-*原始令牌并通过yarn token-audit把裸 hex/rgb/rgba 硬编码当作 CI 错误直接拦截。本文以 specs/foundations/color.md 为核心结合 globals.css、tokens.css 与 specs/README.md 的源码证据系统讲解令牌分层、语义令牌选型表、29 个 12 阶色板、暗色模式自动翻转机制与审计工具链读完即可在 OpenMetadata UI 中正确、合规地使用颜色令牌。一、为什么需要双层颜色令牌OpenMetadata UI 的样式系统按 specs/README.md 划分为两条栈栈样式方式令牌来源审计命令Go-forward推荐UntitledUI Tailwindtw:工具类globals.cssthemeyarn tw-auditLegacy已废弃迁移中Ant Design Less.lessvar(--om-*)yarn token-audit颜色令牌被划分为两层组件只允许触碰第二层Layer 2 语义令牌--om-color-*组件样式中唯一允许的颜色来源。原始 hex/rgb/rgba 一律禁止出现在组件样式里一旦出现会被yarn token-audit标记为**错误error**并导致退出码非零。Layer 1 上游令牌--color-*由openmetadata/ui-core-components提供的语义令牌与完整色板定义在 globals.css是全系统颜色的唯一事实来源source of truth。这套双层设计的直接收益是组件与具体色值解耦暗色模式、品牌改色、无障碍对比度调整都只需在 Layer 1 或 Layer 2 一处改动全站自动生效。二、什么时候用哪个令牌选用令牌遵循最语义化优先的优先级语义令牌 色板令牌 遗留令牌。优先选择能表达意图的语义令牌如这是正文文字这是卡片表面只有当没有任何语义令牌能表达意图时才退而使用色板令牌palette token遗留令牌--om-legacy-color-*永远不要主动选用——它们只用于暂存迁移过程中一次性出现的旧值等待被重新表达成语义令牌后淘汰。以下是官方推荐的语义令牌选型表覆盖了文本、背景、边框、交互、状态等全部常用场景需求使用正文 / 标题文本--om-color-text-primary次要 / 辅助说明文本--om-color-text-secondary、--om-color-text-tertiary弱化 / 禁用 / 占位文本--om-color-text-quaternary、--om-color-text-disabled、--om-color-text-placeholder深色 / 品牌填充上的文本--om-color-text-inverse状态文本--om-color-text-error/-warning/-success页面背景--om-color-bg-page主工作区--om-color-bg-canvas卡片 / 面板 / 侧边栏--om-color-bg-surface下拉 / 菜单 / 弹层--om-color-bg-raised模态框 / 抽屉内容--om-color-bg-overlay-surface状态表面--om-color-bg-error/-warning/-success品牌表面 / 品牌实色--om-color-bg-brand、--om-color-bg-brand-solid模态框 / 抽屉遮罩--om-color-bg-overlay交互控件边框--om-color-border-primary、--om-color-border-hover卡片 / 面板 / 分隔线边框--om-color-border-subtle错误 / 品牌边框--om-color-border-error、--om-color-border-brand链接--om-color-link、--om-color-link-hover悬停 / 激活 / 选中行--om-color-interactive-hover/-active/-selected焦点环--om-color-focus-ring特定的 brand / gray / red 等色板色块--om-color-{scale}-{25…950}色板令牌从源码可以看到这些令牌的映射方式。tokens.css 中典型的语义别名写法是引用 Layer 1 令牌 原始兜底值--om-color-text-primary: var(--color-text-primary, #181d27); --om-color-bg-page: var(--color-bg-page, #ffffff);即运行时优先取上游--color-*的值暗色模式下会随.dark-mode自动翻转若上游未定义则回退到括号内的原始色值保证令牌在隔离/测试环境下依然可用。三、双层令牌的落地形态完整的调用链是三层结构与 specs/README.md 中Layer 1 → Layer 2 → Components的说明一致Layer 1 globals.css 上游语义令牌--color-text-primary、--color-bg-primary … 与完整色板--color-{scale}-{step}来自 openmetadata/ui-core-components是唯一事实来源。 Layer 2 --om-color-* tokens.css 中的项目别名引用匹配的 Layer 1 令牌 并携带原始兜底值离刻度值 / 遗留值直接持有原始值。 组件只允许使用这一层。 Components .less/.css color: var(--om-color-text-primary);对应到仓库文件Layer 1globals.css位于openmetadata-ui-core-components模块被 UI 消费Layer 2tokens.css其中的生成块由yarn token-gen根据上游自动重新生成完整令牌清单specs/tokens/token-reference.md该文件由node scripts/design-tokens/gen-token-reference.js从tokens.css生成共登记804 个--om-*项目令牌包括 62 个间距令牌、24 个圆角令牌等颜色令牌同样在其中按类目完整列出。另外还有一处过渡性定义src/styles/variables.less中的 Lessvariable属于遗留桥接层已有用法不算违规但新代码应优先使用var(--om-*)。四、色板刻度Palette scales上游系统为每个色系提供完整的12 阶刻度25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950全部以--om-color-scale-step的形式暴露。可用色系包括brand、error、warning、success、gray、gray-blue、gray-cool、gray-modern、gray-neutral、gray-iron、gray-true、gray-warm、blue、blue-dark、blue-light、indigo、violet、purple、fuchsia、pink、rose、orange、orange-dark、yellow、teal、cyan、green、green-light、moss外加三个通用令牌--om-color-white、--om-color-black、--om-color-transparent。使用建议色板令牌应保留给没有语义含义的纯视觉需求图表配色、数据可视化、临时高亮等。凡是表达这是页面这是卡片这是错误状态的意图都必须回到语义令牌因为色板令牌不携带任何角色语义。五、暗色模式语义令牌的自动翻转暗色模式是颜色令牌体系最有价值的能力。机制如下.dark-modeCSS 类挂在父级元素通常是body或根包裹节点上globals.css 在.dark-mode选择器下重新定义上游--color-*自定义属性——例如--color-text-primary: theme(--color-gray-50)第 1163 行、--color-bg-page: theme(--color-gray-950)第 1261 行--om-color-*因为直接引用--color-*自动继承这份重定义无需任何额外代码亮色模式的原生色值保持不变theme()解析出的中性色刻度只在.dark-mode作用域内生效。这也解释了规范中反复强调必须使用语义令牌的原因--om-color-gray-900这样的色板令牌无法向调用者表达这里需要的是页面、画布还是表面角色因此不会随暗色模式正确翻转。深色表面层级Dark surface hierarchy暗色模式下表面层级通过灰阶阶梯拉开官方规定的映射如下角色暗色值--om-color-bg-pageGray 950 —#141414--om-color-bg-canvasGray 900 —#191919--om-color-bg-surfaceGray 800 —#222222--om-color-bg-raisedGray 700 —#2e2e2e--om-color-bg-overlay-surfaceGray 800 —#222222这些取值与 docs/colors.md 中的 Tailwind 对照表完全一致tw:bg-page暗色#141414、tw:bg-canvas暗色#191919等可在两套栈之间互相印证。边框与状态表面的暗色配方同样是共享的而非各组件自造卡片与分隔线使用8% alpha的--om-color-border-subtle交互控件使用--om-color-border-primary与--om-color-border-hover状态表面error / warning / success统一使用共享的16% 填充与35% 弱边框配方禁止为 banner、chip 单独发明颜色。六、Do / Dont硬编码就是错误以下是规范给出的正反对照示例其中Dont部分的每一行都会被token-audit标记为错误/* DO */ color: var(--om-color-text-primary); background: var(--om-color-bg-surface); border: 1px solid var(--om-color-border-subtle); /* DONT — flagged as errors by token-audit */ color: #292a2e; background: rgba(0, 0, 0, 0.03); border: 1px solid #eaecf5;合规要点总结组件样式中永远不出现裸 hex / rgb / rgba优先语义令牌其次色板令牌绝不主动使用--om-legacy-color-*新代码遵循 specs/README.md 的贡献规则提交前必须运行yarn token-audit零错误是硬性要求如果确无现成令牌应向tokens.css增加--om-*别名引用上游令牌无上游等价物时才持有原始值而不是把值写进组件。七、配套审计与迁移工具链颜色令牌的强制性由一整套 yarn 脚本保证详见 specs/README.md命令作用yarn token-audit对 CSS/LESS 做硬编码值扫描任何错误都令退出码为 1可直接接入 CIyarn token-audit:report输出全量分组清单每个值对应的建议令牌yarn token-migrateCodemod 把原始值自动改写为var(--om-*)安全且幂等yarn token-gen重新生成tokens.css的生成块与 token-reference 文档yarn token-test扫描器 / codemod 引擎的单元测试在 CI 中属于**硬失败error的是硬编码颜色、硬编码间距属于警告warning**的是非常规值如偏离网格的小数尺寸、特殊时长。这意味着不光是颜色间距等基础设计维度同样被同一套令牌纪律约束。对于存量代码可以先跑yarn token-audit:report拿到清单再用yarn token-migrate做安全批量迁移最后以yarn token-audit清零收尾。八、与其他规范及文档的交叉引用specs/foundations/elevation.mdElevation 规范——阴影内部使用 rgba 令牌与颜色令牌体系同源specs/tokens/token-reference.md全部--om-*令牌及其取值的完整索引804 项由脚本自动生成、勿手改docs/colors.md面向开发者与 AI Agent 的颜色使用手册覆盖 Tailwindtw:颜色用法与暗色模式的完整指南含各类背景、文本、边框、交互状态在亮/暗两态下的取值对照表以及数据绑定 UI 用 utility 色、SVG 图标用前景令牌tw:text-fg-*等进阶规则。九、总结OpenMetadata UI 用Layer 1 上游原始令牌 → Layer 2--om-color-*项目别名 → 组件消费的三层结构把颜色从组件中彻底剥离语义令牌编码意图并随.dark-mode自动翻转色板令牌只在无语义可表达时兜底遗留令牌仅作迁移暂存裸色值则由token-audit在 CI 中强制清零。理解这套分层与选型纪律是在 OpenMetadata 前端做任何颜色相关改动无论是继续维护 Less 旧栈还是迁移到 Tailwind 新栈的前提。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考