Figma Variables 组织多主题界面颜色 token

如果界面同时支持浅色和深色主题，不要把每个按钮、卡片和文字颜色分别改两遍。更稳妥的做法是先在 Figma Variables 中建立颜色 token 集合，再用变量 mode 保存不同主题的值；画布只绑定语义变量，主题切换时由 mode 提供对应颜色。

官方地址：https://www.figma.com/

本文按“准备 token → 创建集合 → 映射语义颜色 → 切换主题 → 导出核对”的路径操作。示例只整理颜色，不展开间距、字号和动效变量。Figma 官方文档将 collection 描述为变量和 mode 的集合，颜色变量可以用于主题，也可以通过 alias 组织 design tokens。

最小可用结构是：一个 Color Tokens collection，里面分成 Primitive 和 Semantic 两组；Primitive 保存原始色值，Semantic 用于背景、文字和强调色，并在集合中设置 Light、Dark 两个 mode。画布只使用 Semantic 变量。

步骤一：准备一份可映射的颜色 token 表

先不要急着在画布上挑颜色。用一张简单表格把“稳定名称、变量类型、Light 值、Dark 值、界面用途”列出来。名称建议采用两层：原始值放在 Primitive，界面用途放在 Semantic。

这一步的重点不是一次定完所有颜色，而是先把“原始颜色”和“界面语义”分开。以后品牌色变化时，只需调整 Primitive；页面仍然只认识 action-primary 这样的语义名称。

步骤二：创建 Color Tokens 集合与分组

1. 打开 Figma Design 文件，从左侧导航进入 Variables 视图。
2. 在变量面板侧栏打开 More options，选择 Create collection，命名为 Color Tokens。
3. 先创建颜色类型的 Primitive 变量，例如 blue-500、gray-0，再使用集合中的分组能力整理到 Primitive。
4. 继续创建 bg-default、text-primary 和 action-primary，将它们归入 Semantic。

继续条件：面板中能按组找到原始色和语义色，变量类型都是 Color。如果所有变量都堆在一层，先整理分组再进入主题映射，否则后面切换 mode 时很难定位遗漏。

步骤三：增加 Light 与 Dark mode 并映射颜色

1. 在 Color Tokens 集合的列标题区域点击 New variable mode，保留默认列并新增一个 mode。
2. 把两个 mode 重命名为 Light 和 Dark。将 Light 放在左侧，使它成为默认 mode。
3. 在 Primitive 变量中分别填写两个主题的原始颜色；在 Semantic 变量上使用同类型变量的 alias，让语义 token 指向对应的原始 token。
4. 如果团队已有符合 DTCG 格式的设计 token JSON，也可以从 Variables 相关入口导入 mode；导入前先确认字段命名能对应到当前集合。

可见状态：同一个变量在 Light 与 Dark 列中分别有值，语义变量仍保持引用关系。不要只复制一份变量再手填两组十六进制值，那样颜色表面上能切换，但 Primitive 与 Semantic 的维护边界会丢失。

步骤四：把语义变量绑定到界面并切换主题

1. 回到设计画布，选中页面背景、卡片填充、主要文字和主操作按钮。
2. 在右侧 Appearance 区域的颜色属性中选择对应的 Semantic 变量，例如背景绑定 bg-default，文字绑定 text-primary。
3. 取消对象选择，或选中需要切换的 frame/container，在右侧找到 Apply variable mode，从 Color Tokens 中选择 Dark。
4. 检查页面背景、文字和按钮是否一起变化；再切回 Light，确认同一批绑定关系能够恢复。

成功标准：切换 mode 后，已绑定的界面区域成组变化，而不是逐层重新选择颜色。未变化的对象通常说明它仍使用了硬编码颜色、另一个 collection，或被更近的父容器 mode 覆盖。

步骤五：导出或核对集合，准备交付

1. 回到 Variables 视图，按集合检查 mode 名称、默认列位置和每个 Semantic 变量的来源。
2. 需要交付主题数据时，在 mode 标题上右键选择导出单个 mode；要交付整个集合，则在集合上选择导出全部 modes。
3. 打开导出的 JSON 或交接说明，核对是否包含 Light、Dark、语义变量名和 alias 关系；不要只交一张画布截图。

导出核对的目的，是让设计和开发双方共享同一份命名边界。画布负责展示结果，Variables 集合负责维护来源，mode 负责表达主题上下文。

常见问题

为什么切换 Dark mode 后只有背景变化，文字没有变化？

先选中文字图层，查看颜色属性是否真正绑定了 text-primary。如果它仍显示固定色值，先补上 Semantic 变量；如果已经绑定，再检查该变量在 Dark 列是否有值，以及父 frame 是否指定了另一个 mode。

Primitive 和 Semantic 为什么要分开？

Primitive 描述可复用的原始色值，Semantic 描述界面语义。按钮不应直接依赖某个蓝色色号，因为品牌色或无障碍主题调整时，Semantic 层可以重新指向另一组 Primitive，而不必逐个修改按钮。

Light 放在左侧有什么作用？

官方文档说明，集合中最左侧的 mode 会成为默认 mode。把常用的 Light 放在左侧，可以让新对象和没有单独指定 mode 的容器先得到预期的默认值；需要特殊上下文时再显式切换到 Dark。

什么时候应该导入或导出 mode？

当团队需要把已有设计 token 带入 Figma，或把一个集合交给其他文件、工具时，可以使用 mode 的导入或导出能力。导入前先确认 JSON 遵循支持的 DTCG 格式，并在当前集合中核对变量类型和命名。

操作速查