reviewing-design-system

reviewing-design-system — SKILL.md

**变体：**标准 · **适用场景：**将已完成的设计系统文档（或修订差异）作为验收门槛进行评审——检查设计师／工程师能否据此构建一致且无障碍的 UI，然后输出 VERDICT: approve|revise，并给出可执行的发现。

概述

此技能是设计系统编写／评审技能组合中的 评审 部分。评审者加载此技能时，手头应有一份已完成的设计系统文档（或针对先前版本的修订差异）。评审围绕一个问题展开：设计师能否根据此文档构建一致的 UI，工程师能否据此实现，而无需询问作者？目录是否涵盖了产品屏幕所需的组件？ 此技能会应用一份固定的可用性 + 一致性 + 无障碍检查清单——与作者编写时遵循的标准（authoring-design-system）一致，避免编写标准与评审标准偏离——然后输出一个可由机器解析的单一裁定，以及作者可在一轮修订中采取行动的发现。评审对象是文本形式的 Markdown 产物（令牌值 + DTCG 形式 + 规格表），而非渲染后的设计文件。这是一个验收门槛——不会编写、修复或重写文档。

何时启用

• 已完成的设计系统文档需要在基于它进行线框设计／高保真设计／UI 工程开发之前，作出接受／修订的决定。
• 修订（现有系统的带版本差异）需要针对差异范围作出接受／修订的决定。
• 在先前裁定为 revise 后，重新评审修订后的设计系统。

请勿在以下情况启用：

• 编写或修复设计系统 → 使用 authoring-design-system。
• 评审线框图／逐屏布局文档 → 使用线框图评审技能（本技能评审的是更上一层的可复用词汇）。
• 评审用户流程文档 → 使用用户流程评审技能。
• 评审工程设计文档（架构／ADR／RFC）→ 使用设计评审技能。
• 检查模板／章节是否符合规范 → 这是模板相关问题；本技能评估的是质量是否达到标准。
• 评估已编码的组件库 → 本技能评审的是文档。

工作流

第 1 步：以全新、独立的视角阅读整份文档

从头到尾阅读，不受作者的框架影响。你要作为后续步骤（线框设计 + 高保真设计 + UI 工程开发）的把关者：只有当发现能证明设计师／工程师无法按文档所述构建一致且无障碍的 UI时，才有分量。识别产品类型（轻量 CLI／实用工具、内容应用或完整 UI 产品），并在可用时查看流程／屏幕清单——覆盖范围 + 比例适当性条件需据此校准。如果产物是修订差异，还要阅读先前版本和变更范围（第 2b 步）。

第 2 步：运行检查清单——逐项评估条件

逐项判定通过或存在缺口。只有存在真实且明确指出的不足时，条件才算失败——“我会选另一套配色”不属于缺口。记录每个缺口的准确位置。这些条件是唯一的标准来源（作者编写时遵循的两种评审角度）；不要自行增加标准。每项条件都指出了其比例适当性失效情形——即该条件在何种情况下确实不适用。

1. 明确陈述原则。 列出 3–6 条可执行原则（而非陈词滥调）。缺失或流于陈词滥调时判定为缺口。
2. 定义令牌，采用 DTCG 格式，使用意图命名，并保持一致。 将颜色（包括语义角色令牌）、字体比例、间距、层级和动效定义为具有具体值的命名令牌；使用 W3C DTCG 格式（带类型的 $value + 别名）——任何规模都必须遵循，不允许以值表替代；组件引用语义令牌，绝不引用原始值（#1A73E8、16px）。令牌族缺失或无值、令牌只是没有 DTCG 结构的纯十六进制列表，或组件规范引用原始值时，判定为缺口。不适用的情形： DTCG 不适用情形为无（普遍适用）；现代色彩空间（Oklch/P3）按比例适用——仅支持 sRGB 不构成缺口。
3. 基础内容的广度。 在产品类型需要的情况下，提供网格/布局与密度、图标规范（网格/描边/尺寸/样式），以及层级/动效。UI 产品省略了它实际使用的网格或图标基础规范时，判定为缺口。不适用的情形： 没有图标或复杂布局的轻量/工具型产品可以合理地省略这些内容。
4. 通过别名切换实现主题。 浅色/深色主题以及（如有）多品牌主题，应在同一固定层级上重新指向语义别名，而不是拆分组件。通过复制/拆分组件实现主题时，判定为缺口。不适用的情形： 单品牌、单主题无需赘述。
5. 组件完整性（逐个组件检查）。 每个编入目录的组件都包含以下五项：结构、状态、变体、使用时的应做/不应做事项、无障碍。任何组件缺少其中一项（例如有变体但没有状态/无障碍说明）时，判定为缺口。
6. 组件 API 一致性。 整个目录使用统一的属性/选项/默认值术语体系（同一变化维度在各处使用同一名称，而不是此处叫 type，彼处叫 mode）；共享值可以组合使用。组件之间的 API 不一致时，判定为缺口。不适用的情形： 目录规模很小时，一致性自然容易保证。
7. 目录覆盖范围——两条底线。 覆盖产品流程/屏幕使用的每个组件（硬性底线，且规范完整），并涵盖符合产品类型规模的标准组件集。真实屏幕需要的组件未收录或规范不足时，判定为缺口。不适用的情形： 标准组件集应随产品类型调整规模（不追求大而全）。
8. 包含模式。 涵盖流程所需的常见多组件场景（表单验证、空状态、破坏性操作确认等）。缺少必要模式时，判定为缺口。
9. 布局与国际化。 说明断点/网格/焦点顺序；对于本地化产品，应处理 i18n/RTL（文本扩展、逻辑属性、RTL/双向文本、区域设置字体）。本地化产品忽视 i18n，或会重排的屏幕未说明相关行为时，判定为缺口。不适用的情形： 明确声明仅面向单一语言区域的工具可以明确将 i18n 排除在范围之外（明确说明不纳入范围不构成缺口；未作说明则构成缺口）。
10. 无障碍要求量化，符合 WCAG 2.2 AA。 明确声明以 WCAG 2.2 AA 为目标，并给出可核验的阈值：文本 ≥4.5:1（大文本/UI ≥3:1）；具有可见且不被遮挡的焦点指示器（SC 2.4.7 + 2.4.11，AA），并采用 AAA 焦点外观 ≥2px/3:1（与未聚焦状态及相邻颜色对比，SC 2.4.13）作为内部规范；目标尺寸 24×24（+ 间距例外）；键盘支持；减少动态效果；不只依赖颜色传递信息；逐组件说明角色/名称/状态。无障碍要求仅停留在愿景层面、缺少具体数值，或遗漏 WCAG 2.2 特有标准时，判定为缺口。不适用的情形： 无——无障碍要求不可妥协（但静态信息屏幕无需赘述其不具备的状态）。
11. 包含语气与内容规范。 说明语气及语调范围（高风险场景优先清晰易懂，而非品牌语气）；规定术语（每个概念使用一个术语）和组件文案规则（按钮 = 动词优先；错误 = 原因 + 修复方法；空状态 = 引导用户采取行动）。面向用户的产品未提供这些规范，或错误/空状态规则未包含原因 + 修复方法/行动引导时，判定为缺口。不适用的情形： 没有面向用户文案的产品可简化这部分内容。
12. 生命周期与治理（达到门槛以上时）。 对于拥有多个使用方/团队，或有外部版本化发布的系统，需说明版本管理 + 更新日志、弃用/迁移政策、贡献模式、所有权、采用情况，并将目标受众记录为一项决策（而非假定的人物画像）。达到门槛以上但缺少治理/版本管理，或由假定的受众决定术语时，判定为缺口。不适用的情形： 低于门槛时（单一维护者 + 单一使用方 + 无外部版本化发布）可完全省略——此时强行判定存在治理缺口属于错误的修改要求。
13. 以实际情况为依据，而非套用模板；便于下游使用。 令牌/组件应体现该产品的特点（规模符合产品类型）；将缺口呈现为假设/待解决问题，而非凭空捏造；线框图/高保真设计可以引用真实组件/令牌，工程团队也能直接实现，无需向作者确认。内容泛化、捏造品牌/对比度结论或存在悬而未决的引用时，判定为缺口。 比例原则。“基于它构建一致的 UI”应与产品规模相适应。对于精简型产品，其系统可以合理地省略上文标记的条件；但无论规模大小，硬性底线（条件 7a）、DTCG（条件 2）和数值化无障碍要求（条件 10）始终适用。评估决策是否完整，而不是统计条目数量。不要因内容简短就臆造缺漏。

步骤 2b：如果该产物是修订版（差异）——审查差异，而非整份文档

评估相对于先前版本的版本化差异时，审查范围应限定于差异：

• 范围限定 — 仅更改声明中列出的令牌／组件；不得进行无关的重新命名、调色板变动或层级调整。超出范围的更改属于范围蔓延 → revise（或拆分）。
• 连带影响／回归 — 每个组件仍引用有效的语义令牌（没有令牌因重命名／移除而成为孤项）；别名层可正常解析；主题变体仍保持一致（没有暗中破坏暗色模式／品牌）。
• 版本号与变更日志准确性 — semver 版本递增符合更改类型（重命名／移除／重新定义类型 ⇒ MAJOR；新增 ⇒ MINOR；修复 ⇒ PATCH）；变更日志与差异相符。
• 安全弃用 — 破坏性更改须提供弃用说明和迁移路径；不得暗中移除。
• 一致性 — 更改符合现有的层级／意图命名／目录 API；该差异仍须在局部满足相关的步骤 2 条件。
• 按比例重新审查 — 评估差异；不要重新争论已定案且未更改的令牌／组件。

步骤 3：确定结论

• approve — 所有适用条件（对于差异，则为所有限定于差异范围的检查）均通过；设计师／工程师可以按文档内容直接构建。即使你能想到风格上的改进，也应予以批准；标准是可用性、一致性和无障碍，而非完美或面面俱到。
• revise — 一个或多个明确的问题妨碍构建（令牌未定义／不一致／不符合 DTCG、规范中出现原始值、组件缺少组成部分、API 不一致、无障碍要求不是数值化或未达到 2.2、覆盖有缺口、本地化产品遗漏 i18n 且未说明、超过门槛却缺少治理要求、差异超出范围或未版本化、内容系臆造）。

不要为了体现工作量或索要锦上添花的改进而要求修订。

步骤 4：给出结论和可执行的发现

结论须单独一行输出——仅输出字面文本 VERDICT: approve 或 VERDICT: revise，独占一行，不加代码围栏／引号／其他文字：

VERDICT: approve

然后列出发现。若结论为 revise，每条发现都必须可执行——指出未通过的条件、确切位置和修复方法，使作者一轮即可解决。若结论为 approve，可选列出不影响批准的备注。

良好的发现：

revise — 令牌（条件 2），“Button”规范：background: #1A73E8 是原始十六进制值。修复方法：引用语义令牌 color.action.primary（在颜色部分定义），并以 DTCG 格式表示。

不好的发现：“令牌可以做得更好。”（哪些令牌？为什么？如何修复？）

规则

硬性规则（绝不违反）：

• 只输出一行判定：VERDICT: approve 或 VERDICT: revise——该字面标记必须单独占一行。
• 只评审，不撰写。 返回问题；不要重写或修正文档。
• 以单一标准为准。 根据第 2 步的条件（增量变更还要根据第 2b 步）进行评判——作者撰写时也遵循同一标准。不要另设私下标准。
• 不要错误地要求修改。 满足所有适用条件的系统应予以通过，即使内容精简；只要按比例精简后仍覆盖了整个范围，就不算缺陷。
• 不要错误地通过。 存在实际缺漏就应判为 revise。
• 原始值或非 DTCG 令牌属于一致性缺漏（条件 2）。组件缺少五个部分中的任意一项，都属于缺漏（条件 5）。API 漂移属于缺漏（条件 6）。
• 无障碍要求必须符合 WCAG 2.2 AA 的量化标准（条件 10）——包括可见且不被遮挡的焦点（AA）、AAA 焦点外观 ≥2px/3:1 的内部规则，以及 24px 的目标尺寸。
• 无论规模大小，都必须满足范围覆盖底线、DTCG 和量化无障碍要求——这些要求不会因规模而取消。
• 治理要求可在低于门槛时省略；高于门槛时则为必需（条件 12）——不要对精简的内部系统凭空挑出治理缺漏。
• 增量变更应评审差异（第 2b 步）——检查范围限制、连带影响、语义化版本和弃用；不要重新评审未变更部分。
• 编造内容属于缺漏，而非有据可依（条件 13）。
• 依据文档所提供的上游资料进行评判。 未提供的上游资料绝不能成为要求修改的理由；如果文档忽略了已提供且本应参考的上游资料，则可以据此提出问题。
• 每条修改意见都必须可执行——指出未满足的条件、具体位置和明确的修复方法。

偏好（可调整）：

• 按严重程度排列问题——优先列出阻塞性缺漏。
• 每条意见都标明条件编号或名称。
• 通过意见应少而明确，并且不得涉及阻塞问题。

易错点

• 因内容齐全而通过，却忽略无法构建。 每个章节都在，但仍无法构建（规格中出现原始值、组件缺少状态或无障碍要求、对比度没有量化）。评判能否构建，而不是模板是否填满。
• 原始值或非 DTCG 令牌藏在规格中。 令牌章节看似正确，但“Button”硬编码了 #1A73E8，或者令牌只是没有 DTCG 结构的扁平十六进制列表——这两种情况都不满足条件 2。
• 组件规格不完整。 有结构、变体和用法，却没有状态或无障碍要求，看起来完整，实则不然（条件 5）。
• 遗漏 2.2 特有的无障碍要求。 只写“焦点对比度 ≥3:1”，却没有说明焦点不得被遮挡（AA，SC 2.4.11）、未达到 ≥2px 的焦点外观内部规则（SC 2.4.13），或未规定 24px 的目标尺寸，都不符合要求（条件 10）。
• 对精简系统错误地要求修改。 精简产品的设计系统规模小是合理的——不需要的章节可以合并，不需要考虑国际化的范围可以排除，低于门槛时可以省略治理要求。这属于合理控制规模，而非规格不完整。
• 在低于门槛时凭空制造治理缺漏——由单个维护者维护、仅有一个使用方的系统，完全可以省略生命周期／治理章节（条件 12）。
• 增量变更却重新审查整份文档——应评审差异（第 2b 步）；重新审查已确定且未变更的令牌，就是对增量变更错误地要求修改。
• 让带有破坏性变更的增量版本以 MINOR 通过，却没有弃用说明——第 2b 步的版本和弃用检查。
• 判定标记不一致。 “Approved”“LGTM”或埋在正文中的判定都无法解析。必须将字面标记 VERDICT: approve|revise 单独放在一行。

反模式

• 敷衍通过。 草草浏览后就通过，以避免反复修改。
• 吹毛求疵地要求修改。 把配色偏好或锦上添花的内容包装成缺漏，并据此阻止通过。
• 暗中重写。 在评审过程中代为撰写。
• 臆造条件（例如要求提供 Figma 链接，或在不需要时要求深色模式）——偏离产出标准，擅自抬高门槛。
• 过度要求。 对精简产品强求全套宽泛标准或完整治理要求。
• 把增量变更当成全新文档重新评审。
• 含糊其辞的判定。 “大体通过，不过……”或输出两行判定。

输出

单一审查结果：

• 一行判定 — 在单独一行原样写出 VERDICT: approve 或 VERDICT: revise。
• 发现项 — 若判定为 revise，针对每个阻塞缺口列出一条可执行的发现项（未通过的条件 + 位置 + 修复方法）；若判定为 approve，可选列出非阻塞备注。

抽象消费者是负责编排“产出→审查”循环的对象：approve 表示接受该系统进入下一阶段（线框图 / 高保真设计 / UI 工程）；revise 则返回发现项，以便进行范围受限的修订。

相关内容

• authoring-design-system — 负责产出的部分；以本审查所用的同一标准编写。配对使用可确保标准单一来源。
• wireframe-review 技能 — 把关每个屏幕的布局（下一层）。
• user-flow-review 技能 — 把关导航路径。
• design-review 技能 — 把关工程设计文档。
• design-system 模板 / content-template 工具 — 负责章节结构；本工具则依据标准评判质量。

渐进式披露

• references/buildability-bar.md — 展开说明各项条件，提供逐项的通过 / 缺口信号、已完成的发现项示例，以及差异审查检查项。
• references/sources.md — 方法的研究溯源，以及单一来源标准（与同级的 authoring-design-system 共享）。

正文预算

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个令牌。
• 每个参考文件：超过 10k 个令牌时警告，超过 25k 时错误。参考文件总计：超过 25k 个令牌时警告，超过 50k 时错误。