impeccable audit 全解析：Web UI 五维技术审计、健康评分与 P0–P3 分级修复清单

导读

本文以 impeccable 技能仓库中 audit 参考文档 为主体，完整讲解 /impeccable audit 的工作方式：它只负责系统性执行可测度的技术质量检查并生成综合报告，不直接修问题，而是把问题归档给后续的 adapt、animate、polish 等命令去修复。读完本文，你将掌握 audit 的五维（无障碍 / 性能 / 主题 / 响应式 / 实现完整性）打分细则、0–4 分与 P0–P3 严重度分级体系、报告的标准骨架，以及“审计结果如何映射到具体修复命令”的路由规则，从而在 AI 协作开发流程里把 UI 质量审计变成一个可复现、可打分、可追踪闭环的工程环节。

---

一、audit 在 impeccable 技能体系中的定位

在 impeccable 中，audit [target] 属于 Evaluate（评估）类别命令，与 UX 设计评审命令 critique 并列，定义位于 SKILL.md 的命令表：Technical quality checks (a11y, perf, responsive)，即技术质量检查；而 critique 负责的是启发式 UX 设计评审（UX design review with heuristic scoring）。二者的边界非常清晰——audit 检查“实现得对不对”，critique 评审“体验好不好”。

从技能元数据 command-metadata.json 可以看到对 audit 的权威描述：

"Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review."

即：audit 跨无障碍、性能、主题、响应式、反模式五个维度做技术检查，产出一份带 P0–P3 严重度评分与可执行计划的报告。当用户想要无障碍检查、性能审计或技术质量评审时，就路由到该命令。

audit 参考文档的开头就划定了三条边界，必须首先理解：

1. 只做代码级审计，不做设计批评。审计对象是“在实现里可测量、可验证”的东西（contrast ratio、touch target 尺寸、是否走 design token、是否 layout thrash 等），而不是审美偏好。
2. 只归档，不修复。审计结果“document them for other commands to address”，问题的修复由下一轮命令（polish、adapt、optimize……）来承担。
3. 仅面向 Web。原生平台（ios / android / adaptive）会路由到 audit.native.md，其报告骨架与 web 版保持一致，但检查清单按 SwiftUI / UIKit / Compose / React Native / Flutter 的平台规约重写，且不适用浏览器工具与 HTML 规则检测器。

命令执行前还有一个前置于会话的上下文准备环节：SKILL.md 的 Setup 要求每次会话先运行一次技能运行时上报的 node <skill-base-dir>/scripts/context.mjs，它会加载项目中的 PRODUCT.md、DESIGN.md、匹配的 surface brief，以及原生平台指引；audit 应在这些上下文已被装载之后运行，以保证它基于真实的产品事实而非猜测。

---

二、五维诊断扫描：每一维查什么、怎么打分

audit 对五个维度执行检查，每维使用 0–4 的整分制，随后汇入 20 分制的健康总分。参考文档要求审计者“只依据可测量、可验证的事实”评分，因此五个维度全部给出了具体的检查项与分数锚点。

2.1 无障碍 Accessibility（A11y）

检查项：

• 对比度：正文文本对比度低于 4.5:1（AAA 目标为 7:1）即为问题；
• 动效敏感度：prefers-reduced-motion 需要提供保留状态变化与层级信息的刻意替代方案——需要标记三类违规：一刀切地把所有动效时长设成全局 0.01ms（摧毁了有用的反馈）、超过闪烁阈值的动画、以及阻断焦点/阅读/任务完成的动画；
• ARIA 缺失：可交互元素没有正确的 role、label 或 state；
• 键盘导航：缺少焦点指示、Tab 顺序不合逻辑、键盘陷阱；
• 语义化 HTML：标题层级错乱、缺少 landmark、用 div 冒充 button；
• Alt 文本：缺失或质量差的图片描述；
• 表单问题：输入项无 label、错误提示不佳、缺少必填指示。

0–4 分数锚点：

分数	含义
0	完全不可访问（不满足 WCAG A）
1	重大缺口（几乎没有 ARIA label、无键盘导航）
2	部分达标（有一些无障碍努力，但缺口明显）
3	良好（基本满足 WCAG AA，少量缺漏）
4	优秀（完全满足 WCAG AA，接近 AAA）

2.2 性能 Performance

检查项：

• 布局抖动（layout thrashing）：在循环中反复读写布局属性（如先读 offsetWidth 再写 width，迫使浏览器反复重排）；
• 昂贵的动画：随意动画布局属性、无界的 blur / filter / shadow 效果，或明显掉帧的效果；
• 优化缺失：图片无懒加载、资源未优化；
• will-change 滥用：will-change 被大面积使用或静止状态仍残留——它是“已知昂贵动画”的定向提示，不是默认基线要求；
• 包体积：多余 import、未使用依赖；
• 渲染性能：无意义的重复渲染、缺少 memoization。

分数锚点：0=严重问题（layout thrash、一切未优化）；1=重大问题（无懒加载、昂贵动画）；2=部分优化仍有缺口；3=大体已优化、仅小改进空间；4=快速、精简、充分优化。

2.3 主题 Theming

检查项：

• 硬编码颜色：颜色未走设计令牌（design tokens）；
• 暗色模式损坏：缺少暗色变体、暗色主题下对比度差；
• 令牌不一致：用错令牌、混用令牌类型；
• 主题切换问题：主题变化时值不更新。

分数锚点：0=无主题系统（全部硬编码）；1=最少令牌（大多硬编码）；2=部分（有令牌但不一致）；3=良好（主要使用令牌，个别硬编码值）；4=优秀（完整令牌体系，暗色模式完美）。

2.4 响应式设计 Responsive Design

检查项：

• 固定宽度：硬编码宽度在移动端破裂；
• 触控目标：可交互元素小于 44×44 px；
• 横向滚动：窄视口下内容溢出；
• 文本缩放：系统字号放大时布局破裂；
• 断点缺失：没有移动 / 平板变体。

分数锚点：0=仅桌面（移动端即坏）；1=严重问题（有部分断点但大量失败）；2=移动端可用但有粗糙边缘；3=良好（仅少量触控或溢出小问题）；4=优秀（流式布局、全视口覆盖、触控目标合规）。

2.5 实现完整性 Implementation Integrity（CRITICAL，最关键维度）

这是五维中唯一被标注 CRITICAL 的维度，它回答一个更深层的问题：这个实现是否表达了一套自洽的、产品专属的设计系统？ 检查时：

• 运行**捆绑的检测器（bundled detector）**并在真实上下文中逐条核实每个 finding；
• 寻找：反复出现的实现捷径、设计系统漂移（design-system drift）、误导性或纯装饰性内容，以及“与无关产品可以互换”的结构化页面；
• 把确定性发现（deterministic findings）与视觉判断分开，并主动指出误报（false positive）。

关于“捆绑检测器”，routing.md 给出了重要的运行约束：detect.mjs 是本地文件检测器——无网络、不经过 npx，直接读 HTML/CSS，因此原生项目应跳过。质量 / 对比度命中多时路由到 audit 或 polish，特定反模式家族则路由到对应命令（渐变色文本或 eyebrow chip → quieter / typeset，扁平灰白配色 → colorize）。SKILL.md 还说明该检测器可以以 hooks 形式注册：打开 /impeccable hooks on 后，检测器会在每次 UI 文件编辑后自动运行并浮出 findings，让 audit 的问题在编码当下就被拦截。

分数锚点：0=系统性漂移；1=大量反复出现的失败；2=若干已核实的孤立问题；3=零星的次要问题；4=连贯且有意为之。

---

三、生成报告：可复现的标准骨架

审计完成后，报告必须按照固定的骨架产出。这份骨架同时被 audit.native.md 镜像使用（原生报告只是把维度和平台规约替换掉），说明它是整个 impeccable 质量闭环的通用契约。

3.1 健康总分表 Audit Health Score

#	维度	得分	关键发现
1	Accessibility	?	[最关键的无障碍问题或 "--"]
2	Performance	?
3	Responsive Design	?
4	Theming	?
5	Implementation Integrity	?
总分		??/20	[评级区间]

等级区间（Rating bands）是判断严重程度的统一标尺：

区间	等级	含义
18–20	Excellent	只需细粒度打磨
14–17	Good	针对弱势维度做补强
10–13	Acceptable	需要显著工作量
6–9	Poor	需要大规模翻修
0–5	Critical	存在根本性问题

3.2 Implementation Integrity Verdict：最先落笔的结论

参考文档明确要求 Start here——报告的阅读顺序和撰写顺序都从实现完整性裁决开始：通过 / 不通过：该实现是否表达了一套连贯的、产品专属的系统？ 必须引用已核实的证据与检测器 findings 作答。把这一维放在最前，是为了防止“分数好看但实现是通用模板拼贴”的幻觉式通过。

3.3 Executive Summary 执行摘要

摘要必须包含四类信息：

• Audit Health Score：??/20（附评级区间）；
• 总问题数（按 P0/P1/P2/P3 严重度分别计数）；
• Top 3–5 关键问题；
• 建议的下一步动作。

3.4 Detailed Findings by Severity：逐条问题档案

每个问题用 P0–P3 严重度标记：

等级	名称	处置时机
P0 Blocking	阻塞性	阻止任务完成，需立即修复
P1 Major	重大	造成显著使用困难或违反 WCAG AA，发布前必须修复
P2 Minor	次要	令人烦恼但有变通方案，下一轮迭代修复
P3 Polish	打磨	可修可不修、无真实用户影响，有空再修

每条问题须完整记录以下字段：

• [P?] 问题名称
• Location：组件 / 文件 / 行号
• Category：Accessibility / Performance / Theming / Responsive / Implementation Integrity
• Impact：它如何影响用户（不允许只报问题不解释影响）
• WCAG/Standard：违反的标准（如适用）
• Recommendation：如何修复（必须是具体、可执行的，禁止空泛建议）
• Suggested command：交由哪条命令处理（见第六节）

3.5 Patterns & Systemic Issues：从单点到系统性

单点问题之外，还必须识别“反复出现、指向系统性缺口”的模式，而不是孤立失误。参考文档给了一组范例句式，可直接套用为审计结论的措辞范式：

• “Hard-coded colors appear in 15+ components, should use design tokens”
• “Touch targets consistently too small (<44px) throughout mobile experience”

这类表述把两个观察点连成因果：现象数量 + 系统性成因。这正是 audit 区别于“随手挑刺”的关键：它要输出的是能驱动架构级修正的证据链。

3.6 Positive Findings：不要只报坏消息

报告必须记录做得好的地方——值得保持与复制的优秀实践。“忽略正向发现”（Skip positive findings）被明确列为 NEVER 行为，因为正向发现是团队维持质量的参照系，也是防止下一轮过度修改的护栏。

---

四、Recommended Actions：把 findings 映射成命令队列

报告的收尾部分是按优先级排列的命令建议清单（P0 在前、P1 其次、P2 再次）：

1. [P0] /impeccable optimize：修复确认的 layout thrashing 循环与无界阴影动画（来自 Performance 维度 findings）
2. [P1] /impeccable adapt：补充 <48rem 断点并修正 44px 以下触控目标（来自 Responsive 维度 findings）
3. ……

命令白名单与映射原则

建议清单只能推荐以下命令：/impeccable adapt、animate、audit、bolder、clarify、colorize、critique、delight、distill、document、harden、layout、onboard、optimize、overdrive、polish、quieter、shape、typeset。

把每个 finding 映射到最贴切的命令（而非机械套用）。从这些命令在 SKILL.md 中的分类可以看出典型映射逻辑：

• Fix 类：adapt（跨设备与屏幕尺寸适配）、optimize（UI 性能诊断修复）、clarify（文案 / label / 错误消息）——对应 a11y、responsive、performance 问题；
• Refine 类：polish（发布前最终质量关）、harden（错误态、i18n、边界）、colorize（为单色 UI 补策略性色彩，修复扁平灰白）、quieter（收敛过度刺激）——对应 theming 与实现完整性中的漂移问题；
• Enhance 类：layout（间距节奏与视觉层级）、typeset（排版与字体）、animate（有目的的动效，可替代“全局 0.01ms 一刀切”的错误做法）。

只要推荐了任何修复，最后一棒必须是 /impeccable polish，作为发布前的收口步骤。

收尾话术

展示完摘要后，必须把下面这段原样转述给用户，形成“审计 → 修复 → 复检”的循环入口：

You can ask me to run these one at a time, all at once, or in any order you prefer.

Re-run /impeccable audit after fixes to see your score improve.

这句“修复后重跑 audit 看分数上涨”正是该闭环的设计核心：audit 的产出是可量化基线，修复命令按图施工，复检验证分数变化——这比一轮轮无记号的自由发挥可追踪得多。

---

五、审计纪律：宁可少而准，不可多而噪

参考文档在结尾给出两条收口准则与一条 NEVER 清单，它们定义了 audit 报告的质量标准：

收口准则：Be thorough but actionable——要详尽但必须可行动。P3 问题过多只会制造噪音，应聚焦真正重要的问题。

NEVER 清单（违规即视为审计失败）：

• 报问题不解释影响（why does this matter？缺失）；
• 给出空泛建议（必须具体、可行动，绑定 Location 与 Recommended command）；
• 跳过正向发现（做得好的要庆祝并记录）；
• 忘记分级优先级（不可能所有问题都是 P0）；
• 误报未经验证就上报（false positives 必须经上下文核实）。

其中最后一条与第 2.5 节的“keep deterministic findings separate from visual judgment and call out false positives”互为表里：audit 之所以要求“每条 finding 都要在真实上下文里核实”，就是为了把检测器输出的确定性信号与审计者的视觉判断分开，避免机器命中与主观偏好互相污染报告的可信度。

---

六、从参考文档到真实执行：它与周边命令如何协同

把 audit 放进 impeccable 的整体工作流，可以清晰看到它的“承上启下”位置：

• 承上（评估）：它与 critique（critique.md）同属 Evaluate 类别，分别覆盖“技术质量”与“UX 启发式评分”两个评估面，可先后执行形成互补视图；
• 启下（修复）：audit 报告本身不写修复代码，而是产出带严重度、位置、WCAG 依据与推荐命令的问题档案，交给 Fix / Refine / Enhance 类命令逐一消化；
• 循环（复检）：修复完成后重跑 /impeccable audit，通过总分区间（Excellent / Good / Acceptable / Poor / Critical）的变化客观衡量一轮迭代的质量增量；
• 并行防回归：注册 hooks 后，捆绑检测器在每次 UI 文件保存时自动扫描，等于把 audit 的“Implementation Integrity + 质量反模式”检查前置到了编码时刻，而不是等整轮审计才发现；
• 原生分支：若项目是 ios / android / adaptive，同一份报告骨架由 audit.native.md 承担，五维替换为 VoiceOver/TalkBack 无障碍、性能、外观与主题、平台一致性、自适应性，并对照 ios.md / android.md 打分——两套文档被要求“keep the two in sync when changing it”，保证跨平台审计口径统一。

仓库内还有多份随各 Agent 分发的 audit 副本（如 skill/reference/audit.md 及其模板化版本 SKILL.src.md），供不同宿主运行时装载；其中模板化副本把命令前缀抽象为 {{command_prefix}}、把白名单抽象为 {{available_commands}}，内容与本文主体一致，可作为跨平台接入时的同一语义来源。

---

结语

/impeccable audit 的价值不在于“抓出多少 bug”，而在于它把 UI 技术质量变成一个有维度的（五维）、有刻度的（0–4 / 20 分制与评级区间）、有优先级的（P0–P3）、有去向的（每条 finding 都映射修复命令） 的可审计对象。基于 audit.md 这份参考文档，任何 AI Agent 或开发者都可以在每次迭代后执行一次 audit：先做实现完整性裁决，再输出健康分与执行摘要，最后给出按 P0→P3 排序的命令建议并以 /impeccable polish 收口——而修复之后重跑 audit 看分数上涨，就是这套设计语言让 AI 协作流程保持“可度量进步”的最小闭环。