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 合并而自动完成这一步。

Token 单一事实源与双端交付关系

下面用一个最小样例核对“改源数据,产物随之改变”。在同一目录创建 tokens.json,采用 Design Tokens 格式中常见的 $type、$value 与别名引用写法:

json
{
  "color": {
    "brand": {
      "600": { "$type": "color", "$value": "#2563EB" }
    },
    "action": {
      "primary": { "$type": "color", "$value": "{color.brand.600}" }
    }
  }
}

创建 check.py。它是教学用的最小解析器,不代替生产构建器的类型、主题完整性和色域校验。

python
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 后,在这两个文件所在目录运行:

bash
python check.py

预期输出:

css
:root { --color-action-primary: #2563EB; }

将源文件中的 #2563EB 改为 #1D4ED8 再运行,输出色值也应相应改变。若有人只改生成的 CSS,下一次构建便会覆盖该改动,这正是禁止直接修改产物的原因。

把发布边界写成可验收规则

正式流水线应在合并前检查 JSON 结构、别名是否存在及是否循环、语义命名和各主题覆盖情况;合并后才生成 CSS 与多端产物。发布包须带独立版本,应用更新依赖并检查按钮默认、悬停、禁用及浅深主题效果,而不是仅看构建成功。

可用一次模拟发布检验边界:假设 Token 包从 1.3.0 发布到 1.4.0,应用仍锁定 1.3.0 时,不能宣称新色已上线;只有升级、构建并部署应用后才生效。若回归失败,先将应用依赖回退至已验证的 1.3.0,再按该版本同步正式设计变量。PR、发布记录、应用依赖版本三者能互相对应,才算完成从设计变更到生产代码的交付。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

确定设计与代码的单一事实源

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通