UI 视觉设计 / 系统课时
确定设计与代码的单一事实源
确定设计与代码的单一事实源
当 Figma 按钮色和线上 CSS 出现两个值时,必须明确谁有最终裁决权、从哪里修改、哪些产物允许发布。本课以可版本化的 Token 仓库为例,制定设计师、前端和规范维护者的协作规则,并验证一条从源数据到代码的交付链路。
学习目标
- 区分权威源、设计草稿、同步副本和已发布产物。
- 明确三类角色的修改、审核及发布权限。
- 用可核对的 Token 示例建立发布与回滚验收标准。
选择唯一可裁决的权威源
权威源必须能回答三个问题:冲突时以哪份记录为准、谁批准修改、如何找回任意一次发布所用的值。两种常见选择都可行,但只能选一种作为正式发布入口。
| 方案 | 正式修改入口 | 启用前必须具备 |
|---|---|---|
| Figma Variables 为权威源 | 受控的变量修改与导出 | 可审计的版本快照、稳定导出、发布审批 |
| Git 中的 Token JSON 为权威源 | 合并到主分支的 Pull Request | 设计侧同步机制、自动校验和版本发布 |
本例约定:design-tokens 仓库 main 分支的 tokens/*.json 是待发布版本的唯一权威源。Figma Variables 是设计消费副本,dist/*.css 和包文件是构建产物,均不得直接修改后当作新源。注意,仓库最新值不等于线上生效值:线上由应用锁定并部署的 Token 包版本决定。
例如,Figma 草稿使用 #1D4ED8,仓库仍是 #2563EB,不能让设计同步脚本直接覆盖生产 CSS;应先提交变更提案,审批合并后再构建发布。
固定修改权限和冲突处理
| 角色 | 可以直接操作 | 必须交给谁确认 |
|---|---|---|
| 设计师 | 在 Figma 草稿中试色、提出语义和色值变更、提交源数据 PR | 规范维护者确认命名与语义 |
| 前端工程师 | 审核变量兼容性、测试生成 CSS、升级应用依赖 | 与设计师核对可见效果 |
| 规范维护者 | 审查并合并 Token PR、批准发布和弃用规则 | 对破坏性改动征求消费方确认 |
以 color.action.primary 改色为例,PR 至少记录旧值、新值、影响组件、浅深主题检查结果和变更原因。若设计草稿与仓库冲突,先暂停同步,按 PR 审核结果更新权威源;不要用“最后保存时间”决定胜负。一人兼任多个角色时,也要保留可追溯的审核记录。
从源数据生成代码消费值
约定交付链路为:设计提案进入 PR,维护者审核后合并源 JSON,持续集成校验并构建版本化产物,前端明确升级依赖;设计工具经已配置的同步适配器读取指定发布版本。Figma 本身不会因 Git 合并而自动完成这一步。

下面用一个最小样例核对“改源数据,产物随之改变”。在同一目录创建 tokens.json,采用 Design Tokens 格式中常见的 $type、$value 与别名引用写法:
{
"color": {
"brand": {
"600": { "$type": "color", "$value": "#2563EB" }
},
"action": {
"primary": { "$type": "color", "$value": "{color.brand.600}" }
}
}
}创建 check.py。它是教学用的最小解析器,不代替生产构建器的类型、主题完整性和色域校验。
import json
from pathlib import Path
# 只读取权威源文件,不反向读取生成的 CSS。
data = json.loads(Path("tokens.json").read_text(encoding="utf-8"))
def resolve(path, seen=None):
seen = set() if seen is None else seen
if path in seen:
raise ValueError(f"循环别名:{path}")
seen.add(path)
node = data
for part in path.split("."):
node = node[part]
value = node["$value"]
# 追踪别名,避免组件依赖某个固定基础色号。
if isinstance(value, str) and value.startswith("{") and value.endswith("}"):
return resolve(value[1:-1], seen)
return value
print(f":root {{ --color-action-primary: {resolve('color.action.primary')}; }}")安装 Python 3 后,在这两个文件所在目录运行:
python check.py预期输出:
:root { --color-action-primary: #2563EB; }将源文件中的 #2563EB 改为 #1D4ED8 再运行,输出色值也应相应改变。若有人只改生成的 CSS,下一次构建便会覆盖该改动,这正是禁止直接修改产物的原因。
把发布边界写成可验收规则
正式流水线应在合并前检查 JSON 结构、别名是否存在及是否循环、语义命名和各主题覆盖情况;合并后才生成 CSS 与多端产物。发布包须带独立版本,应用更新依赖并检查按钮默认、悬停、禁用及浅深主题效果,而不是仅看构建成功。
可用一次模拟发布检验边界:假设 Token 包从 1.3.0 发布到 1.4.0,应用仍锁定 1.3.0 时,不能宣称新色已上线;只有升级、构建并部署应用后才生效。若回归失败,先将应用依赖回退至已验证的 1.3.0,再按该版本同步正式设计变量。PR、发布记录、应用依赖版本三者能互相对应,才算完成从设计变更到生产代码的交付。