better-interface

将界面作为一个整体进行评审

优秀的界面不是把一堆互不相关的审计结果拼在一起。评审完整体验，让每项 better-* 技能负责自己的领域规则，然后将证据整合成一份优先级明确的结论。

此技能只负责协调。无障碍规则归 better-accessibility 所有；结构归 better-layout 所有；文案归 better-writing 所有；字体排印归 better-typography 所有；颜色归 better-colors 所有；视觉润色和动效归 better-ui 所有。此处绝不重复或覆盖这些技能的规则。针对未提交改动、分支和拉取请求的变更范围评审归 interface-review 负责；它会确定范围并对发现进行分类，然后将评审交回此处。

核心原则

1. 先确定范围和模式

将调用解析为 [quick|full] [scope]。只有第一个标记恰好是 quick 或 full 时，才将其视为模式；否则，它属于范围的一部分。模式默认为 full。

根据请求和当前工作区推断屏幕、流程、功能或代码库范围。在输出中说明确定的范围。

模式	覆盖范围	发现数量上限
quick	覆盖范围内的主要路径及其实际到达的状态；仅报告 HIGH 和 MEDIUM 问题	5
full	覆盖原则 3 中列出的所有领域技能所涉及的整个请求范围，包括其中存在的空状态、加载状态、错误状态和窄屏状态	15

如果请求的范围过大，无法可信地完成检查，就将其缩小为一个完整流程：优先选择请求本身重点关注的流程；否则，选择该范围内所有用户都必须经过的入口路径。说明边界及未包含的内容。绝不要暗示已评审未检查的界面。

如果请求提到了分支、拉取请求、提交范围或未提交的改动，这是变更评审，而不是屏幕评审。请说明这一点，并要求用户运行 interface-review；它由用户主动调用，因此此技能无法启动它。此处绝不要确定变更范围：读取差异、对发现进行分类，以及将变更文件扩展到受影响的界面，都属于 interface-review 的职责；猜测这些内容会导致报告的范围无法核实。

interface-review 会将评审交回此处。交回时，它会提供已确定的变更范围、受影响的界面，以及每项发现的状态；严重程度、整合方式、数量上限、输出格式和结论仍由此处负责，具体规则见下文的 变更范围评审。

2. 先侦察，再判断

确定框架、样式系统、组件库、设计令牌、支持的视口，以及可用的预览或测试命令。所有修复建议都应采用项目自身的惯用方式，确保发现不会变成要求采用不同技术栈。此要求决定的是修复形式，而不是当前代码是否足够好。

接着阅读项目关于自身界面的说明：CONTRIBUTING.md、CODING_STANDARDS.md、AGENTS.md、CLAUDE.md、设计系统文档、Storybook 文档、界面 ADR。在输出中列出找到的文档，或说明没有找到。

阅读这些文档是为了寻找可用的切入点，而不是征求许可。记录在案的约定并不能证明约定本身合理，“风格指南里这么写”也不能让问题不再成立。它们改变的是你报告的位置：如果问题由某项指南或共享令牌导致，就针对该来源报告一次，并将相关组件列为位置。

3. 以领域技能作为事实依据

开始审查前，确认以下各项所属技能均可用。加载并应用所有可用的所属技能。在 quick 模式下，检查每个领域，但只对主要流程中有证据支持的领域深入审查。在 full 模式下，先完成每个可用领域的审查，再进行汇总。

按以下顺序审查，以免基础问题被表面修饰掩盖：

1. better-accessibility
2. better-layout
3. better-writing
4. better-typography
5. better-colors
6. better-ui

此技能负责最终回复。通过 better-interface 加载领域技能时，应用其原则和参考资料，但忽略其 Reporting 部分以及其中指向的 review-output.md。改用本文档中的汇总格式、统一严重程度标准和发现数量上限。

如果某项所属技能不可用，将该领域标记为 Not reviewed，注明缺少的技能，并继续审查其余领域。不要凭记忆还原其规则，不要用相近技能替代，也不要声称已完成全面审查。

如果两个技能看似涵盖同一问题，应将其归属到负责底层规则的技能，并在 Why 单元格中说明次要影响。只报告一次。

4. 要求提供证据

每项发现都必须引用 path/to/file:line，并展示当前实现。如果审查材料不包含源文件，则引用确切的屏幕和组件。若运行时行为决定结果，不要仅凭视觉表现报告代码层面的问题，也不要仅凭源代码报告视觉问题。

5. 按用户影响排序

使用统一的严重程度标准：

• HIGH：阻碍任务、误导用户、隐藏内容或控件、造成数据丢失风险，或导致反复出现的系统性故障。
• MEDIUM：明显损害理解、效率、适应性或一致性。
• LOW：对任务影响有限的局部润色问题。仅在 full 模式下纳入。

同一严重程度内，按影响范围和修复杠杆排序。修复令牌或共享组件，优先于在单个叶级组件中修复同一问题。

升级触发条件。 所属技能一旦确认存在以下任一情况，立即定为 HIGH，不得因表面影响轻微而降低等级，也不得在 quick 模式下省略：

• 交互控件没有可访问名称。
• 键盘可访问的控件没有可见的焦点指示器。
• 可通过指针访问的控件或路径无法通过键盘访问。
• 动画或自动播放内容忽略 prefers-reduced-motion。
• 在 320px 宽度或 200% 缩放下，内容或控件被裁切、遮挡或无法访问。
• 正文或控件文本的实际渲染对比度未达到规定比例。
• 状态或含义仅通过颜色传达。
• 破坏性操作没有确认、撤销或明确的差异化处理。

触发项的排序高于其他所有发现。如果触发项数量超过上限，先列出这些触发项，并说明上限排除了多少项发现；上限可以缩短报告，但绝不能成为漏报阻碍项的理由。

这些条目规定的是严重程度，而非新规则。症状是否存在仍由所属技能判定，其影响程度则由此列表决定。在变更审查中，已确认的、针对触发项的 Regression 属于 HIGH，即使同一症状作为既有问题时可能属于 MEDIUM。

6. 汇总系统性发现

一个根本原因对应一项发现。将所有已确认的位置列在同一行中，不要按出现次数逐条列出。不要为了凑足发现数量上限而填充报告；简短的审查结果或没有发现均属有效结果。

7. 明确说明审查克制

记录已考虑但有意排除的候选问题。若所属技能允许当前实现、证据不足、项目约定虽非仅因既有而存在但仍有充分理由，或拟议变更会增加复杂度却无法让用户受益，则应排除该候选问题。

8. 验证可验证的内容

运行项目中可用且安全、相关的检查。如果需要根据运行时行为或视觉表现做判断，请检查渲染后的界面。报告具体的命令或操作，以及观察到的结果。如果无法运行某项检查，请标记为 Not verified 并说明仍有哪些内容未验证；绝不要把验证缺口转化为问题。

9. 默认以只读方式审查

将审查请求视为只读操作。除非用户也要求实现审查结果，否则不要编辑源代码。用户要求实现时，应以汇总后的报告为变更范围，并在之后重新运行相关验证。

常见错误

错误	修正方法
六份彼此独立的领域报告	汇总为一张按优先级排序的问题表
多项技能报告了同一个问题	将问题归给负责底层规则的技能
问题没有精确位置	引用 path/to/file:line 和当前实现
仅凭源代码推断视觉问题	检查渲染状态，或标记为未验证
无限制地进行低影响润色	遵守模式上限；在 quick 模式下省略 LOW 问题
覆盖情况存在未说明的空白	说明实际检查了哪些领域和状态
技能缺失却被默认为已覆盖	将领域标记为 Not reviewed，并指出不可用的技能
没有列出被否决的候选项	加入要求的「已考虑但否决」表格
审查时悄悄编辑代码	除非用户要求实现，否则保持只读
尚有待处理的可操作问题却给出“Approve”	使用 Needs changes 或 Block
报告所触及文件中的所有历史问题	在单独的部分中将既有问题限制为三项
既有问题阻碍变更审查	既有问题不计入上限，也不影响判定
变更未涉及的领域却标记为 Clear	标记为 Not reviewed: no evidence in the change scope

审查输出格式

始终使用以下各部分。

范围与覆盖情况

说明模式、准确范围、技术栈和样式约定、在侦查阶段找到的项目约定文档，以及任何审查边界。然后列出覆盖情况：

领域	检查的证据	结果
无障碍	文件、组件、状态或检查	问题数或 Clear

包括原则 3 中列出的所有领域。Clear 表示已检查且没有可操作的问题；Not reviewed 必须说明原因。

问题

使用一张按严重程度、影响范围和改进价值排序的表格：

#	严重程度	领域	位置	改动前	改动后	原因
1	HIGH	无障碍	src/Dialog.tsx:42	<button><XIcon /></button>	添加 aria-label="Close"，并将图标从无障碍树中隐藏	仅含图标的控件没有可访问名称

每行对应一个根本原因。领域值应为负责该问题的技能名称，去掉 better- 前缀。遵守模式的问题数量上限。如果没有问题，省略该表并说明“没有可操作的界面问题”。

已考虑但否决

quick 模式列出 1–3 个候选项，full 模式列出 2–5 个候选项：

位置	候选项	否决原因
src/Card.tsx:28	加强阴影	现有层次与共享表面令牌相符；单独更改此卡片会降低一致性

这些应是在审查期间实际检查过的候选项，而非凭空编造的填充内容。如果范围内确实只有更少的边缘候选项，请列出已有的候选项并说明。

验证

列出每项检查或操作、准确命令或步骤，以及观察到的结果。将已通过的检查与标记为 Not verified 的检查分开。

判定

最后只能使用以下一项：

• Block：仍有一个或多个 HIGH 问题。
• Needs changes：只剩 MEDIUM 或 LOW 问题。
• Approve：没有可操作的问题，且所声称的覆盖范围均已验证。

变更范围审查

当 interface-review 从版本控制中解析出审查范围时，上述格式适用，并增加以下四项内容。此处说明这些内容，是因为本文件负责规定格式、上限和结论；interface-review 则提供审查范围和状态。

1. 范围区块。 在 范围与覆盖情况 中，先放入 interface-review 生成的变更范围表，再放入上方的覆盖情况表，保持原样。变更范围内没有证据的领域应标记为 Not reviewed: no evidence in the change scope。这是覆盖情况说明，并非问题。

2. 状态列。 发现项表格在 Domain 后新增 Status 列，填写 Introduced 或 Regression：

   #	Severity	Domain	Status	Location	Before	After	Why
   1	HIGH	Accessibility	Regression	src/Dialog.tsx:42	此次变更移除了 aria-label="Close"	在仅含图标的控件上恢复 aria-label="Close"	此变更前，关闭控件具有无障碍名称；此变更后则不再具有

   如果没有 Introduced 或 Regression 发现项，则省略该表，并注明“此次变更没有可处理的界面问题。”

3. 既有问题部分。 将其放在 已考虑但不采纳 之后，最多列出三个，按严重程度从高到低排列，并明确说明这不属于此次变更的责任范围。没有此类问题时省略。

   Severity	Domain	Location	Issue
   MEDIUM	Typography	src/Toolbar.tsx:7	数字徽标使用比例数字；此问题早于此次变更

4. 上限与结论。 两者仅涵盖 Introduced 和 Regression。Pre-existing 发现项不计入上限，因此触及遗留文件不会导致对整个文件进行全面审查；也不影响结论，因此如果变更仅涉及既有问题，结论应为 Approve。