Figma 变量架构:如何搭建一套能扛住生产环境的 Token 系统

大多数用 Figma 变量的团队,脑子里用的还是样式的心智模型,这正是问题所在。没有架构的变量,不过是多点几下鼠标的样式。

做对的团队,把 Figma 变量当成真正的设计 token层:有结构、有别名、有作用域、可导出。做错的团队,离一次深色模式需求就只差一步,然后就是彻底重建。下面这套架构,扛得住生产环境。

变量不是样式,它们是 token 层

Figma 样式是预设。你定义一个颜色、一个文字样式、一个效果,然后直接应用到图层上。对于单品牌、单模式、没有开发交付要求的文件,这样没问题。但只要有任何变化,它就不行了。

Figma 变量是 token。变量可以保存一个值,也可以保存对另一个变量的引用。这条引用链,加上通过模式切换整套解析值的能力,才是变量在架构上与样式截然不同的原因。这种区别不是表面功夫,而是预设系统和 token 系统之间的差别。

三层 token 架构

基础值(primitives)、语义(semantic)、组件(component)。每个能用的变量系统都有这三层。跳过语义层,是当下 Figma 文件里最常见的架构错误,没有之一。

三层对应三项工作:基础值保存原始值,语义 token承载含义,组件 token则限定在单个组件家族内。每一层只和它下面一层对话。不跳层,不抄近路。

这三层不会因为项目小就变成可选项。哪怕只有五个组件的小系统,也需要全部三层,否则第一次换主题需求就会把它炸得粉碎。

第一层:基础值

基础值就是原始值。blue-500、gray-900、space-4、radius-md。它们是色板、是刻度、是地基。它们绝不能直接挂到组件图层上。

基础值的工作就是存在、被上层引用、然后别挡路。如果设计师伸手去拿 blue-500 给按钮上色,架构就已经坏了。基础值只属于基础值集合,别处都不行。

命名规范在这里很重要。基础值应该基于刻度或色板命名,绝不能带语义。blue-500 是对的。把 button-blue 当作基础值,是类别错误,规模一大就会带来痛苦。

第二层:语义

语义 token 承载含义。surface、surface-elevated、text-primary、text-muted、border-default、border-focus。它们回答的是“这个颜色用来干什么?”,而不是“这是什么颜色?”

语义 token 别名指向基础值。这是它们唯一的关系。语义指向语义的别名,会让人搞不清值到底存在哪,也让模式覆盖变得不可靠。

这一层就是你的浅色、深色和品牌模式所在的地方。语义 token 会根据当前模式解析到不同的基础值,这就是主题化真正的运作方式。基础值 blue-500 不会变。语义 token text-link 会根据模式改变它解析到的目标。

第三层:组件

组件 token限定在单个组件家族内。button-bg、button-text、button-border、card-surface、card-border、input-bg。它们别名指向语义 token,绝不指向基础值。

组件 token 的工作是在不产生耦合的前提下做到具体。button-bg 解析到 surface-action,后者再解析到 blue-500。品牌变了,你更新语义层,按钮跟着更新,组件 token 纹丝不动。

常见的反对意见是:这感觉像是多出一堆没理由的 token。理由是 button-bg 和 surface-action 可能会分道扬镳。总有那么一刻,某个产品决策要求按钮用一个稍微不同的表面色。组件 token 给你一个覆盖点,而不用动语义系统。

模式与集合:决策树

模式在一个集合内部切换值。集合用来分离关注点。这是两码事,把它们混为一谈,是 Figma 变量搭建中大多数架构混乱的根源。

规则是:每个关注点一个集合,同一关注点的变体用模式。颜色是一个关注点。间距是一个关注点。浅色和深色不是各自独立的关注点,它们是同一个颜色关注点的不同模式。

何时用模式,何时用新集合:

• 同一个东西的不同值?模式。
• 完全不同的东西?集合。
• 在浅色和深色之间切换?颜色集合里的模式。
• 在紧凑和舒适间距之间切换?间距集合里的模式。
• 新增一个品牌?语义层里的模式,而不是新集合。

四条作用域规则

变量作用域控制变量在 Figma 里可以应用到哪里。这里搞错,意味着设计师可能不小心拿了基础值而不是语义 token,架构纪律就在使用的那一刻崩塌了。

这四条规则没有商量余地:

1. 基础值的作用域设为无。 基础值不应该能应用到任何地方。它们是内部值,不是面向使用者的 token。把它们从应用下拉菜单里彻底藏起来。
2. 语义 token 的作用域限定在其类型。 颜色语义 token 限定为填充和描边。间距 token 限定为间隙、内边距和尺寸字段。作用域要收紧。
3. 组件 token 的作用域限定在其家族。 按钮 token 不应该能应用到卡片上。作用域太宽,组件边界就毫无意义。
4. 绝不向使用者暴露基础值。 如果设计师或开发者把基础值应用到了图层上,说明系统在作用域层失守了。这是流程失败,不是用户的失败。

让主题成为可能的别名链

一个能用的主题就是一条别名链:组件别名指向语义,语义别名指向基础值,基础值保存数值。链条长度是三,永远是三。

两层的链(组件直接指向基础值)跳过了翻译层,没有在每个组件 token 上手动覆盖就无法使用模式。四层的链则让人搞不清到底哪个语义层承载模式,审计它会变成一场调试,而不是一次查表。

button-bg → surface-action → blue-500 → #0066FF

Copy

这条链能扛住深色模式:只要在语义集合的深色模式里,把 surface-action 改为指向 blue-300。button-bg token 会自动更新。基础值 blue-500 仍然解析为 #0066FF。其他任何东西都不用改。

浅色、深色和品牌模式

大多数变量系统需要的三种模式是浅色、深色和品牌。只有语义层承载它们,绝不是基础值层。

把模式用在基础值上是类别错误。blue-500 永远是 #0066FF。它是基础值,没有浅色或深色变体,因为它不承载含义。语义 token text-link 有浅色和深色变体,因为它承载的含义在不同情境下解析结果不同。

品牌模式的原理一样。第二个品牌不需要第二套基础值色板,除非该品牌确实使用了完全不同的原始值。大多数时候,在语义层加一个品牌模式,指向现有基础值的不同子集,才是正确选择。为两个品牌建两套完整的基础值集合,通常是过度设计。关于上游的颜色决策如何影响这一点,在敲定语义层结构之前,值得先读一读深色模式色彩系统这篇文章。

数字、字符串和布尔变量

Figma 变量不只是颜色。数字变量控制间距、尺寸和圆角。字符串变量控制设计文件里的文案。布尔变量控制图层可见性,这直接对应组件的 props。

这是大多数团队没有用上的那部分变量系统,也是最能显著弥合设计与代码鸿沟的部分。把间距刻度定义为数字变量,并应用到自动布局的间隙上,意味着变量里改一次间距,所有使用该 token 的组件都会更新。这才是真正的 token 系统该做的事。

带语言区域模式的字符串变量,让设计师能在英语和阿拉伯语之间切换文件,实时看到布局崩掉。映射到组件 props 的布尔变量,意味着 Figma 组件和代码组件之间有一一对应的 prop 关系,让开发交付变得可审查,而不是靠解读。

交付到代码:真正管用的模式

变量系统的价值取决于它的导出。管用的交付模式是 Tokens Studio 或 Figma Variables REST API,加上一条转换流水线,再加上代码端的导入脚本。

Tokens Studio 把变量集合导出为与 Style Dictionary 兼容的结构化 JSON 格式。Style Dictionary 再把 JSON 转换成代码库需要的任何输出:CSS 自定义属性、Swift 颜色集、Kotlin 资源文件、Tailwind 配置。转换这一步,就是统一命名规范、清理那些不符合代码约定的 Figma 特有命名的地方。

流水线应该在每次变量更新时运行,而不是手动。一个在 Tokens Studio 推送时触发的 GitHub Action,或是在变量变更时触发的 Figma webhook,能让代码端 token 保持同步,不用任何人记得去导出。这是 Stripe 和 Atlassian 在大规模下运行的模式,只要代码库有构建步骤就能做到。关于该输出中颜色 token 的格式决策,在敲定 CSS 自定义属性的值之前,值得读一读 OKLCH 颜色。

---

想要一套扛得住模式、品牌和开发交付、无需重写的 Figma 变量系统?Brainy 用三层模型、别名链,以及能顺畅接入你代码库的导出流水线,在 Figma 中设计生产级 token 架构。雇用 Brainy

---

破坏变量系统的七个常见错误

这些错误大多有同一个根源:把变量面板当成更好用的样式面板,而不是一个架构层。心智模型的转变就是解药,其他一切都由此而来。

变量系统审计

对任何 Figma 变量系统跑一遍这份审计,你就能在架构债务上线之前把它揪出来。

结构

• 至少三个集合:基础值、语义、组件(或等效命名)
• 每个集合只有一个明确的关注点
• 没有集合混合类型(颜色和间距放在同一个集合里就是失败)

别名链

• 每个组件 token 都别名指向语义 token,而不是基础值
• 每个语义 token 都别名指向基础值,而不是另一个语义 token
• 除基础值外,没有 token 保存原始值
• 所有颜色 token 的别名链长度恰好是三

模式

• 浅色和深色是语义集合里的模式,而不是单独的集合
• 品牌变体是语义集合里的模式,而不是单独的文件
• 基础值集合没有模式

作用域

• 基础值变量的作用域设为无(哪里都不能应用)
• 语义变量的作用域限定在其类型(颜色对应填充/描边,间距对应布局字段)
• 组件变量的作用域限定在其组件家族

交付

• 变量可通过 Tokens Studio 或 REST API 导出
• 转换流水线存在且已自动化
• 代码端 token 与 Figma 变量命名规范一致,例外情况有文档记录

如果这些项里有超过三项不合格,系统需要的是重建,而不是打补丁。如果审计发现最大的债务出在基础值层,品牌色板一文涵盖了喂给基础值层的上游颜色决策。

FAQ

Figma 变量和 Figma 样式有什么区别?

样式是直接应用到图层的预设。变量是可以互相引用、并通过模式切换值的 token。变量能做样式能做的一切,外加主题化,外加通过导出实现的开发交付。对于新的设计系统,变量是正确的选择。对于已有成熟样式系统的现有文件,切换之前值得先写一份迁移计划。

一个 Figma 变量系统应该有多少个集合?

大多数系统是三到五个:基础值、语义、组件,如果间距和字体排印的刻度足够复杂、值得拥有自己的作用域规则,还可以再单独加这两个集合。超过五个集合,通常说明关注点没有被正确归类。

Figma 变量能取代 Tokens Studio 吗?

在 Figma 内部创建和编辑,可以。原生变量面板能处理 Tokens Studio 在变量 API 发布之前所做的大部分事情。至于导出和转换,Tokens Studio 仍然有价值,因为它有成熟的 Style Dictionary 流水线,并能处理原生导出处理不了的边缘情况。目前这两个工具是互补关系,而不是竞争关系。

如果我把一个语义 token 别名指向另一个语义 token 会怎样?

模式解析会变得含糊不清。如果 text-secondary 别名指向 text-primary,然后你切换到深色模式,Figma 会解析这条链,但可能不会在你预期的地方应用深色模式覆盖。语义指向语义的别名,也会让大规模审计系统几乎不可能。规则很硬:语义 token 只别名指向基础值。

如何在不重建系统的前提下处理第三个品牌?

给语义集合加第三个模式。基础值集合在各品牌之间共享,除非这些品牌确实使用完全不同的原始值。语义层里一个指向基础值不同子集的品牌模式,就是正确的架构。如果品牌差异大到它们的基础值色板毫无重叠,那么两套基础值集合加一个共享的语义结构就是退路。

小项目也需要三层模型吗?

需要,只是每一层的规模会变小。小项目可能有十五个基础值、八个语义 token,每个组件两个组件 token。架构依然是三层。在小项目上想跳过语义层的诱惑,正是这么多小项目在第二位设计师加入或深色模式需求出现的那一刻就变成架构债务的原因。关于 token 架构在更大的技术栈决策中处于什么位置,Framer vs Webflow vs Next.js 这篇文章有相关背景。

Figma 变量真正解锁的转变

Figma 里一个真正的变量系统,是设计和开发两端迄今最接近“单一事实来源”的东西。不是交付文档,不是 Zeplin 链接,而是一个活的、可导出的、有结构的 token 层,双方读取的是同一套定义。

把变量当作架构的团队,正在把设计系统债务砍掉一半。不是因为变量有魔法,而是因为一个好的变量系统所要求的架构纪律,同时也逼着团队做出那些设计系统一直拖着不决的决策。这个 token 意味着什么?它能别名指向什么?谁拥有这个基础值?这些问题现在有答案了,而答案就在文件里。

没有架构的变量,不过是多点几下鼠标的样式。有了三层模型、别名链、作用域规则和导出流水线的变量,才是一套能扛住第二个品牌、深色模式,以及一个从没打开过 Figma 的开发者的设计系统。

要搭的是架构,而不只是 token。