多主题与多品牌令牌架构

主题改变的是同一品牌的颜色模式（同一产品的浅色和深色版本）。品牌代表不同的视觉身份——使用不同的颜色、排版和间距来呈现同一设计系统的组件，以服务不同的产品或客户。两者使用相同的令牌架构，但处于不同的抽象层级。

原始令牌是系统可用的全部原始值调色板。其中包括每个颜色级别（从 color-blue-50 到 color-blue-900）、每个间距单位和每个字号。组件不会直接使用原始令牌，它们只由语义令牌引用。调色板只定义一次，并由所有主题和品牌共享。

语义令牌表达使用意图：color-background-page、color-text-primary、color-action-primary。每个语义令牌都会引用适合当前主题的原始令牌值。组件只基于语义令牌构建。这是主题切换发生的层。

在浅色主题中：color-background-page 引用 color-white，color-text-primary 引用 color-gray-900，color-action-primary 引用 color-blue-500。这些映射定义在主题专用的令牌文件中，用于覆盖浅色环境下的语义层。

在深色主题中：color-background-page 引用 color-gray-950，color-text-primary 引用 color-gray-50，color-action-primary 引用 color-blue-400（为了在深色背景上获得足够对比度，该颜色稍亮一些）。只有语义映射会改变，原始调色板和所有组件都保持不变。

品牌 A 使用蓝色作为主色（color-action-primary: {color-blue-500}）。品牌 B 使用绿色（color-action-primary: {color-green-500}）。按钮组件读取 var(--color-action-primary)，完全无需了解当前启用的是哪个品牌。品牌覆盖只改变语义令牌映射，从不修改组件代码。

CSS 自定义属性让运行时主题切换变得非常简单。将当前主题存储在数据属性中：document.documentElement.setAttribute('data-theme', 'dark')。CSS 规则会在 [data-theme="dark"] 选择器下覆盖语义令牌。浏览器会立即将所有 var() 引用解析为新值，无需 JavaScript 重新渲染。

对于以独立部署形式提供的不同品牌，可以使用构建时主题：使用 Style Dictionary 为每个品牌生成单独的 CSS 令牌文件，并在应用启动时加载正确的品牌 CSS。当品牌在部署时确定（例如使用不同的域名、子域名或白标实例），而不是在用户交互时确定时，这种方法非常合适。

多品牌、多主题系统需要一个二维矩阵：品牌 A 浅色、品牌 A 深色、品牌 B 浅色和品牌 B 深色。CSS 自定义属性通过嵌套选择器可以优雅地处理这种情况：[data-brand="a"][data-theme="dark"] 会为特定组合覆盖语义令牌。四种组合只需要四个 CSS 代码块，而不是四套代码库。

随着设计系统不断发展，令牌会被添加、重命名或移除。请将令牌与代码放在同一个仓库中进行版本管理。弃用某个令牌时，请在一个发布周期内保留旧名称，并将其作为指向新名称的别名；添加弃用注释，并更新使用这些令牌的代码。通过结构化的变更日志，在设计与工程团队之间协调令牌变更。

治理规定谁可以添加或修改令牌，以及需要经过怎样的审查流程。原始令牌需要设计团队批准。语义令牌需要同时经过设计和工程团队的审查。组件令牌可以由组件所有者管理。如果没有这种治理，就会出现重复令牌，“单一事实来源”的保证也会失效。

组件为什么应该引用语义令牌，而不是原始令牌？

主题会在同一品牌内切换色彩模式；品牌则代表不同的视觉标识。原始令牌是原始调色板，语义令牌表达含义并支持主题化。组件只使用语义令牌。暗色模式和品牌覆盖只会改变语义令牌映射，组件本身不变。运行时主题化使用带有 [data-theme] 选择器的 CSS 自定义属性；构建时品牌化则为每个品牌生成独立的 CSS。令牌治理和版本控制可以在系统不断演进时保持一致性。