Metabase 嵌入 SDK 主题颜色键MetabaseColorKey完全指南全部 Token 清单与命名规范【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabaseMetabase 嵌入 SDK 允许你通过MetabaseTheme自定义嵌入应用的整体外观而MetabaseColorKey正是这一主题系统的基石——它枚举了主题中可以覆盖的全部颜色键Color Token。本文以 MetabaseColorKey.md 文档为主体结合仓库源码深入讲解每一个颜色键的分类、命名规范、明暗双主题要求以及如何在实际的嵌入主题配置中正确使用这些 Token。MetabaseColorKey 是什么MetabaseColorKey是一个 TypeScript 字符串字面量联合类型string literal union type它列出了 Metabase 主题中所有可用的颜色键。在嵌入 SDK 中它用于约束主题对象MetabaseTheme/MetabaseEmbeddingTheme中colors字段的键名确保你只能使用受支持的、语义明确的颜色 Token而不是任意字符串。从源码结构看该类型由三部分构成见 color-keys.tsMetabaseAccentColorKey图表与可视化使用的强调色accent系列ProtectedColorKey受保护的、不允许被主题覆盖的颜色键如纯白、纯黑等常量色其余为按语义分类的颜色键背景background、边框border、图标icon、文本text、按钮button、开关switch、反馈feedback、语法高亮syntax等。对外导出时嵌入 SDK 包通过 frontend/src/embedding-sdk-bundle/types/theme.ts 将MetabaseColorKey与ProtectedColorKey、ChartColorV2一并公开供宿主应用在配置主题时获得完整的类型提示与编译期校验。颜色键完整清单图表强调色Accent Colorsaccent0至accent7是图表系列的主强调色每个色号都配套-light与-dark两个变体用于表达同一色系的不同深浅层次accent-gray同样提供accent-gray、accent-gray-light、accent-gray-dark三个梯度。完整键名如下accent0 / accent0-light / accent0-dark accent1 / accent1-light / accent1-dark accent2 / accent2-light / accent2-dark accent3 / accent3-light / accent3-dark accent4 / accent4-light / accent4-dark accent5 / accent5-light / accent5-dark accent6 / accent6-light / accent6-dark accent7 / accent7-light / accent7-dark accent-gray / accent-gray-light / accent-gray-dark强调色在源码中由ALL_ACCENT_COLOR_NAMES常量生成见 color-keys.ts 对../constants/accents的引用并通过MetabaseAccentColorKey并入MetabaseColorKey。当嵌入多个图表或看板时系列颜色会按accent0 → accent7的顺序循环分配。背景色Background背景色覆盖了页面page、表面surface、选中态、悬停态、禁用态以及各类语义状态成功、警告、错误、信息的底色background-brand / background-filter background-disabled / background-disabled-inverse background-error / background-error-secondary background-highlight / background-hover background-info / background-primary / background-primary-inverse background-secondary / background-secondary-inverse background-selected / background-success / background-success-secondary background-tertiary / background-tertiary-inverse background-warning / background-warning-secondary background_page-filter / background_page-highlighted background_page-primary / background_page-primary-inverse background_page-secondary / background_page-secondary-inverse background_page-tertiary / background_page-tertiary-inverse background_surface-brand-strong / -hover / -pressed background_surface-brand-subtle / -hover / -pressed background_surface-disabled / background_surface-disabled-inverse background_surface-error / background_surface-error-subtle background_surface-hover background_surface-primary / -hover / -pressed / background_surface-primary-inverse / -hover / -pressed background_surface-secondary / -hover / -pressed / background_surface-secondary-inverse / -hover / -pressed background_surface-selected / background_surface-success / background_surface-warning / background_surface-warning-strong其中以_page、_surface为分类前缀的属于命名规范升级后的新 Token源码中标注为 New namesbackground_surface-*系列通常还带-hover、-pressed状态后缀用于按钮、卡片等可交互表面的按下与悬停反馈。边框色Borderborder / border-strong / border-stronger / border-subtle border-brand / border-filter / border-highlight border-neutral / border-neutral-strong / border-neutral-strongest / border-neutral-subtle border-on_darkborder-neutral-*提供由弱到强的中性边框梯度border-brand用于品牌色边框如选中输入框border-on_dark用于深色背景上的边框。品牌与图标Brand Iconbrand / brand-hover / icon-brand / icon-brand-inverse icon-disabled / icon-disabled-inverse icon-primary / icon-primary-inverse icon-secondary / icon-secondary-inversebrand是 Metabase 主题的主品牌色通常与前端主题的metabaseTheme.colors.brand对应决定按钮、链接、选中态等高优先级元素的颜色icon-*系列则约束各类图标的颜色层级。文本色Texttext-hover / text-secondary-opaque / text-tertiary / text-tertiary-inverse text-brand / text-brand-hover / text-brand-strong / text-brand-strong-hover text-disabled / text-disabled-inverse text-filter / text-primary / text-primary-inverse text-secondary / text-secondary-inverse / text-selected text-syntax-parameter / text-syntax-parameter-activetext-primary、text-secondary、text-tertiary构成文本的三级层级text-syntax-parameter系列服务于原生查询编辑器中的 SQL 参数高亮。语义反馈色Feedback Statusdanger / error / info / success / success-secondary / warning feedback-negative / feedback-negative-strong feedback-neutral-strong feedback-positive / feedback-positive-selected / feedback-positive-strong feedback-warning / feedback-warning-strongfeedback-*是较新的语义 Token 命名positive / negative / warning / neutral与早期的success、danger、error、warning并存后者的值会被映射到前者的语义槽位中。其他 UI Token其余颜色键覆盖界面细节包括focus / filter / summarize / gold / overlay / shadow / white core-blue-saturated / core-brand / core-brand-hover / core-filter core-gold / core-green-saturated / core-info core-purple-saturated / core-red-saturated / core-summarize core-white / core-white_constant / core-yellow-saturated saturated-blue / saturated-green / saturated-purple / saturated-red / saturated-yellow illustration-brand-secondary / illustration-brand-tertiary illustration-secondary-brand / illustration-tertiary-brand input-background / input-focus / modal-overlay / shadow-default switch-checked / switch-disabled / switch-unchecked / switch_thumb-disabled tooltip-background / tooltip-background-focused / tooltip-text / tooltip-text-secondary button-label-on_dark-disabled / button-label-on_dark-primary / button-label-on_dark-secondary button-on_dark-primary-default / -hover / -pressed button-on_dark-secondary-default / -hover / -pressed syntax-parameters / syntax-parameters-activecore-*系列代表主题最底层的核心常量色saturated-*与core-*-saturated提供高饱和度的基准色button-on_dark-*用于深色背景上的按钮状态switch*与tooltip-*分别控制开关控件和提示气泡的颜色shadow-default控制阴影modal-overlay控制弹层遮罩。命名规范读懂任意 Token 的结构原文档明确了颜色键的命名范式这是理解全部 200 个 Token 的关键Token 名称遵循[category]-[property]-[variant?]-[state?]结构各部分用-连接当某个部分由两个单词组成时用_连接成一个整体使其读起来像一个单元。对照示例解析background_surface-brand-strongcategory 是background_surface注意双词部分用下划线property 是brandvariant 是strongbutton-on_dark-primary-hovercategory 是buttonproperty 是on_darkvariant 是primarystate 是hovertext-syntax-parameter-activecategory 是textproperty 是syntax-parameterstate 是active。利用这个规则你不需要死记硬背看到background_surface-*-hover就知道是表面悬停底色看到*-inverse就知道是反色用于深色背景上的浅色元素看到-pressed就知道是按下状态。源码 color-keys.ts 顶部注释与该规范完全一致可作为权威参考。明暗双主题必须覆盖全部颜色键原文档特别强调浅色主题与深色主题都必须定义所有这些颜色Both the light and dark theme must define all of these colors.。这意味着在嵌入 SDK 中配置主题时不能只提供brand、accent等少数键——主题系统会基于完整的MetabaseColorKey集合生成 CSS 变量任何缺失的键都可能导致界面某处出现不协调的默认色。在实际使用中MetabaseColorKey通常以键值对形式出现在主题配置中import type { MetabaseTheme } from metabase/embedding-sdk; const theme: MetabaseTheme { colors: { brand: #4C6FFF, accent0: #4C6FFF, accent1: #88BF4D, text-primary: #172A3A, text-secondary: #6A7C8F, background-primary: #F4F6F8, background-secondary: #FFFFFF, // 深色主题场景下还需为对应的 *-inverse / on_dark Token 提供取值 }, // ... };主题对象的类型定义来源于 frontend/src/metabase/embedding-sdk/theme 与 frontend/src/metabase/ui/colors/types并通过 types/theme.ts 重新导出。借助MetabaseColorKey联合类型编辑器会为colors对象提供完整的键名自动补全并在键名拼写错误时给出编译错误。从源码确认类型定义的双重来源MetabaseColorKey在仓库中有两处同源定义文档快照docs/embedding/sdk/api/snippets/MetabaseColorKey.md —— SDK API 文档中展示的类型清单供阅读与检索源码真身frontend/src/metabase/ui/colors/types/color-keys.ts —— 实际生效的 TypeScript 类型其中部分历史遗留颜色legacy colors在源码注释中被标注为 Prefer using new ones推荐优先使用新命名。同时该文件被CssVarsDeclarationPlugin引用见文件头部警告注释主题系统会依据MetabaseColorKey声明对应的 CSS 变量这意味着每一个颜色键最终都会映射为一个 CSS 自定义属性供嵌入 SDK 渲染的组件树使用。这也是为什么列表中的键名如background-primary与 CSS 变量名保持严格一致。使用建议与最佳实践以新命名优先配置新主题时优先使用background_page-*、background_surface-*、feedback-*、button-*、text-*等新 Tokenbackground-*、brand、error、success等旧键仍可用但属于历史遗留。成对配置明暗主题如果宿主应用同时支持明暗模式请为两套主题分别提供完整的颜色键尤其是*-inverse与-on_dark系列它们正是为深色场景设计的。利用类型自动补全在 TypeScript 中导入MetabaseTheme后直接书写colors对象即可获得基于MetabaseColorKey的键名提示避免手写错误。语义化引用不要直接使用saturated-*或core-*-saturated高饱和色作为大面积底色它们更适合图表、徽标等强调场景界面底色请使用background_page-*/background_surface-*语义 Token。通过本文的 Token 清单与命名规则你可以精确控制嵌入应用的每一个视觉细节——从图表配色到按钮悬停态从输入框焦点到深色模式下的文字层级从而让 Metabase 嵌入内容与宿主产品视觉完全统一。【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考