UI 视觉设计 / 系统课时

为 Token 更新建立评审清单

为 Token 更新建立评审清单

一次颜色或间距调整,可能通过别名同时改变多个组件。这里把新增、修改、删除 Token 的审核标准整理成可直接复用的 Pull Request 清单,并用具体色值、引用范围和视觉证据判断能否合并,避免设计稿通过而代码消费端遗漏。

学习目标

  • 区分三类 Token 变更的必查项目与拒绝条件。
  • 为一次修改补齐引用范围、主题状态和视觉验证证据。
  • 建立设计师与前端工程师共同批准的合并流程。

按变更类型确定必查项目

先按 Token 的实际影响分类,而不是按修改文件数量判断风险。同一个 PR 允许包含多种变更,但要逐条注明对象;删除共享 Token 即使只改一行,也可能导致下游构建失败。

类型 评审者必须看到 不应直接通过的情况
新增 语义用途、命名、$type 与 $value、Light/Dark 覆盖、首个消费组件 与现有 Token 重复,或没有明确使用场景
修改 旧值与新值、别名引用链、受影响组件、状态与主题截图 只展示源文件差异,未确认实际渲染结果
删除 替代 Token、所有消费者迁移记录、兼容期限、受影响版本 仍有有效引用,或未说明破坏性变更

团队可约定三级风险:未被消费的新增项为低风险;只影响单一局部组件为中风险;修改跨页面共享语义值或删除公开 Token 为高风险。高风险项必须检查下游应用,并明确回退负责人。DTCG 的类型与别名规则可对照格式规范。

用实际组件证明视觉影响

假设将 Light 模式的 color.action.primary 从 #155EEF 改为 #0B5ED7,Dark 模式不变。它被 button.primary.background 和 link.action.color 引用;评审不能只看改动后的蓝色色块,还要核对 Button 与 Link 的渲染结果。

证据项 此次 PR 应填写的内容
变更标识 color.action.primary,类型 color,仅 Light
值变化 #155EEF → #0B5ED7;Dark 无变化
引用范围 button.primary.background、link.action.color;列出实际消费页面
视觉对比 相同尺寸下的 Light/Dark 截图;Button 的 Default、Hover、Disabled 与 Link 的 Default、Hover
验证结果 白字与新蓝色背景对比度约 5.84:1;其他实际前景/背景组合另行检查

普通文字的 WCAG AA 对比度门槛为 4.5:1,但单个色对达标不等于整个组件通过验收,仍需检查实际文字、焦点状态与主题切换(见 WCAG 2.2)。引用范围要结合 Token 别名解析结果、设计工具中的变量绑定以及项目中的组件消费位置,不能仅靠搜索一个十六进制颜色值。

把审核清单放进 Pull Request

使用 GitHub 时,可在仓库默认分支创建 .github/pull_request_template.md,让新建 PR 自动带入以下完整模板。方括号勾选项是审核记录,不代表 CI 已实际执行;自动检查结果应附对应构建或测试链接。文件位置参见 GitHub 文档。

markdown
## Token 变更内容

- [ ] 新增
- [ ] 修改
- [ ] 删除
- Token 路径与类型:
- 使用场景与主题模式:
- 原值、新值或替代 Token:
- 别名链、消费组件及影响页面:
- 设计稿与前后截图链接:
- 可访问性、状态及主题检查结果:
- 迁移安排、版本影响和回退方法:

## 合并前审核

- [ ] 命名、类型、引用解析检查通过
- [ ] 视觉差异已说明并获得设计认可
- [ ] 受影响应用、兼容性与构建已核对
- [ ] 设计师审核通过
- [ ] 前端工程师审核通过

验证方法:从包含该模板的默认分支新建一个测试 PR,检查正文是否出现两组清单,再填入上述蓝色修改案例。若只出现空白描述,先检查文件路径及模板是否已合并到默认分支。

让双角色审核形成可追踪的闭环

  1. 变更作者提交 PR,填写用途、变更值、消费范围、截图和回退方案。缺证据时保留草稿状态。
  2. 自动校验检查 Token 结构、别名缺失与循环引用、产物构建和视觉回归;若项目尚未配置自动化,应附手动核查记录,不得勾选为自动通过。
  3. 设计师确认语义命名、Light/Dark 与状态视觉差异;前端工程师检查消费端、兼容迁移和构建结果。任一方拒绝,作者补证据或修改后重新请求评审。
  4. 维护者仅在检查和双方审核都通过后合并;发布后记录 PR、版本、受影响应用与回退提交。删除公共 Token 时,先弃用并迁移消费者,再按团队版本策略执行移除。

Token 更新从提交、自动校验到双角色批准及发布的评审流程

例如,有人申请删除 color.brand.600,但引用清单仍有 12 处消费记录,即使设计视觉已批准,前端也应拒绝合并。先把这 12 处迁移到约定替代项、再次检查引用计数归零并完成必要的版本通知,才能重新评审删除请求。

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

目录与阅读设置

阅读设置

17

记录一个想法

为 Token 更新建立评审清单

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

登录哪都通