Impeccable Audit 技术体检指南：为 Web 界面实现做系统化、可量化的质量审查

导读

Impeccable 是一套围绕"让 AI 具备更好的设计能力"而构建的 Agent Skill（设计语言与工具集，版本 v4.1.2，Apache 2.0）。其中 /impeccable audit 是其"评估（Evaluate）"类命令中的技术审查子命令：它不评判视觉好不好看，而是对实现代码做系统性、可测量、可验证的技术质量检查，产出带分数与 P0–P3 严重度分级的报告，把问题交给其他命令去修复。读完本文，你将掌握 audit 的五维诊断框架、0–4 分评分口径、报告模板、P0–P3 严重度标记方法以及如何把审计结论映射到修复命令的工作流，并了解它与 native 版本 audit.native.md 的分流关系。

---

一、audit 的定位：代码级审查，而非设计批评

在 Impeccable 的 SKILL.md 命令表中，audit [target] 被明确归入 Evaluate（评估） 类别，官方描述为 "Technical quality checks (a11y, perf, responsive)"，即围绕无障碍、性能、响应式等技术维度做检查；与之相邻的 critique [target] 才是面向 UX 的启发式设计评审（"UX design review with heuristic scoring"）。二者分工清晰：

• critique 关心界面是否好懂、信息层级是否合理、情感张力是否到位；
• audit 只关心实现里"可测量、可验证"的东西——对比度比值、触摸目标尺寸、是否硬编码颜色、是否产生布局抖动，等等。

命令元数据进一步说明了适用场景与参数形式：command-metadata.json 中 audit 的 description 为 "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"，其 argumentHint 为 [area (feature, page, component...)]，即可以针对某个具体功能、页面或组件执行局部审计。SKILL.md 的全局 argument-hint 也印证了该命令的典型调用形态：

[shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · ...]

audit 有三个铁律般的原则：

1. 只审计、不修复：把所有问题记录成文档化的 finding，交给其他命令（adapt、optimize、polish 等）按优先级处理；
2. 面向 Web：audit 是 Web 流程。若项目是 iOS / Android / 自适应原生应用，应切换到 audit.native.md（详见下文第七节）；
3. 全程跑在真实实现上：每个结论都必须在代码与渲染上下文中被验证，报告里要明确区分"确定性发现（deterministic findings）"与"视觉判断"，并主动标记误报。

二、Diagnostic Scan：五个技术维度与评分标准

audit 在 5 个维度上做全面扫描，每个维度用 0–4 分评分。0 = 最差，4 = 优秀，维度之间独立打分，最终汇总为 20 分制健康分。下面逐维展开（均为文档口径，括号内为判断要点）。

1. Accessibility（无障碍，A11y）

检查项：

• 对比度问题：文本对比度低于 4.5:1（WCAG AA），或追求 AAA 时低于 7:1；
• 动效敏感度：prefers-reduced-motion 需要一种保留状态变化与层级的有意替代方案。要特别标记三类问题——用全局 0.01ms 的"暴力关闭"毁掉有效反馈的动效、超过闪烁阈值的内容、阻碍聚焦/阅读/完成任务的动作；
• ARIA 缺失：交互元素缺少正确的 role、label 或状态；
• 键盘导航：缺少焦点指示、Tab 顺序不合逻辑、出现键盘陷阱；
• 语义化 HTML：标题层级错乱、缺少 landmark、用 div 充当 button；
• Alt 文本：图片描述缺失或质量差；
• 表单问题：输入框没有 label、错误提示糟糕、缺少必填标识。

评分口径：

分数	含义
0	完全不可访问（未通过 WCAG A）
1	重大缺口（几乎没有 ARIA 标签、无键盘导航）
2	部分达标（有一些无障碍投入，但缺口显著）
3	良好（基本满足 WCAG AA，仅剩轻微缺口）
4	优秀（完全满足 WCAG AA，接近 AAA）

2. Performance（性能）

检查项：

• 布局抖动（Layout thrashing）：在循环中反复读写布局属性；
• 昂贵的动画：随意动画化布局属性、无上限的 blur/filter/shadow 效果，或肉眼可见的掉帧；
• 缺失的优化：图片未懒加载、资源未优化；
• will-change 滥用：will-change 被大面积使用或静止时仍保留——它只是针对"已知昂贵动画"的定向提示，不是基线要求；
• 包体积：多余 import、未使用的依赖；
• 渲染性能：无谓的重复渲染、缺少 memoization。

评分口径：0 = 严重问题（布局抖动 + 全未优化）；1 = 重大问题（无懒加载、昂贵动画）；2 = 部分优化、仍有缺口；3 = 基本优化、尚有小的改进空间；4 = 优秀（快速、精简、优化到位）。

3. Theming（主题化）

检查项：

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

评分口径：0 = 无主题化（全硬编码）；1 = 极少令牌（基本硬编码）；2 = 部分（存在令牌但使用不一致）；3 = 良好（使用令牌，仅个别硬编码残留）；4 = 优秀（完整令牌系统，暗色模式工作完美）。

4. Responsive Design（响应式）

检查项：

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

评分口径：0 = 仅桌面端（移动端直接破版）；1 = 重大问题（有一些断点但大量失败）；2 = 部分（移动端可用但有粗糙边缘）；3 = 良好（响应式正常，仅轻微触摸目标或溢出问题）；4 = 优秀（流式布局，覆盖全部视口与触摸目标）。

5. Implementation Integrity（实现完整性，CRITICAL）

这是五个维度中唯一被标记为 CRITICAL 的一维，也最体现 Impeccable 的差异化：运行仓库自带的检测器（bundled detector），并逐条在真实上下文中验证发现。要寻找的是：

• 反复出现的实现捷径（repeated implementation shortcuts）；
• 设计系统漂移（design-system drift）；
• 误导性或装饰性的内容（misleading or decorative content）；
• "与无关产品可以互换的结构"——即缺乏产品独特性的通用模板痕迹。

同时必须"把确定性发现与视觉判断分开"，并主动标注误报（call out false positives）。

评分口径：0 = 系统性漂移；1 = 大范围重复失败；2 = 若干已验证问题；3 = 少量孤立问题；4 = 连贯而有意为之的实现。

仓库佐证：所谓 "bundled detector" 不是空话。仓库在 tests/fixtures/antipatterns/ 维护了一套可被检测器消费的"反模式样例语料"，包括 design-system.html、color.html、hard-coded 场景、dark-gradient-ground.html、typography.html、should-flag.html / should-pass.html、scoped-ignore.html 等成对的正反样本，覆盖 CSS-in-JS、CSS Modules、Tailwind、Svelte/Vue/JSX 等多种形态；同一份语料同时支撑了 skill 行为测试（如 tests/skill-behavior/）与 hooks.md 描述的设计检测器 Hook（在 UI 文件编辑后自动跑检测并上报发现）。audit 的第五维正是站在这些确定性检测能力之上，再叠加"设计师级"的语境判断，而不是只做无脑匹配。

三、Generate Report：结构化审计报告

扫描完成后，audit 要求按固定骨架产出报告。骨架顺序与内容如下。

3.1 Audit Health Score（审计健康分）

用一张汇总表呈现五个维度的分数与最关键发现：

#	Dimension	Score	Key Finding
1	Accessibility	?	最严重的无障碍问题，或 "--"
2	Performance	?
3	Responsive Design	?
4	Theming	?
5	Implementation Integrity	?
Total		??/20	[评级区间]

**评级区间（Rating bands）**是判断优先级的总纲：

• 18–20 Excellent：只需轻微打磨（minor polish）；
• 14–17 Good：针对薄弱维度修复即可；
• 10–13 Acceptable：需要大量工作；
• 6–9 Poor：需要重大返工；
• 0–5 Critical：存在根本性问题。

3.2 Implementation Integrity Verdict（实现完整性裁决）

报告要求从这里开始读。给出 pass/fail 结论："该实现是否表达了一套连贯的、产品特定的系统？"必须引用已验证的证据和检测器发现。这一节是防止"全部维度分数尚可、但整体是通用模板套壳"的守门员。

3.3 Executive Summary（执行摘要）

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

3.4 Detailed Findings by Severity（按严重度详述）

每条 issue 都必须打上 P0–P3 标签，四档定义如下：

• P0 Blocking（阻塞）：阻止任务完成，需立即修复；
• P1 Major（重大）：造成显著使用困难或违反 WCAG AA，需在发布前修复；
• P2 Minor（次要）：令人烦恼但有绕行方案，下一轮处理；
• P3 Polish（打磨）：值得修但不影响真实用户，有空再修。

每条 issue 必须记录以下字段：

字段	说明
[P?] Issue name	问题名称与严重度
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"（15+ 个组件里出现硬编码颜色，应使用设计令牌）；
• "Touch targets consistently too small (<44px) throughout mobile experience"（移动端体验中触摸目标持续小于 44px）。

"同一缺陷出现在多处"本身就是比单点缺陷更高的优先级信号，因为它意味着缺少令牌系统、组件库或规范约束。

3.6 Positive Findings（正向发现）

明确记录"做得好、值得保持和复制"的部分——audit 不是只挑刺，健康的代码模式要写进报告，供后续命令（以及未来的人类开发者）作为参考基线。报告底部的 NEVER 清单也同步提醒：不要跳过正向发现（"celebrate what works"）。

四、Recommended Actions：把结论映射为修复命令

报告的收尾是一份按优先级排序的命令清单（先 P0，再 P1，再 P2）。推荐命令有严格白名单，只能从以下命令中选择并映射到具体审计发现：

/impeccable adapt、/impeccable animate、/impeccable audit、/impeccable bolder、/impeccable clarify、/impeccable colorize、/impeccable critique、/impeccable delight、/impeccable distill、/impeccable document、/impeccable harden、/impeccable layout、/impeccable onboard、/impeccable optimize、/impeccable overdrive、/impeccable polish、/impeccable quieter、/impeccable shape、/impeccable typeset。

常见映射关系（供实战参考）：

• 无障碍 / 对比度问题 → /impeccable colorize（补色与对比）、/impeccable clarify（文案与 label）；
• 性能问题 → /impeccable optimize（专项性能诊断与修复）；
• 响应式 / 触摸目标 / 断点缺失 → /impeccable adapt（跨设备适配）、/impeccable layout（间距与层级）；
• 主题令牌 / 暗色模式 → /impeccable colorize 或 extract 系令牌抽取；
• 动效过度或缺失 reduce-motion 替代 → /impeccable quieter（收敛过度刺激）、/impeccable animate（补充有意动效）；
• 实现完整性 / 系统漂移 → /impeccable distill、/impeccable adapt。

命令清单的收尾规则：如果推荐了任何修复，最后一步必须是 /impeccable polish，作为统一的质量收口。每条推荐项都要带上从具体审计发现提炼的上下文说明（"specific context from audit findings"），不能只写一句空泛的 /command-name。

呈现摘要后，必须以固定话术告知用户后续执行方式：

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 清单）

文档为审计者划定了五条不可逾越的红线：

• 不要只报问题不解释影响（为什么这个问题重要？）；
• 不要给空泛建议（要具体、可执行）；
• 不要跳过正向发现（要肯定做对的部分）；
• 不要忘记优先级排序（不可能全是 P0）；
• 不要未经验证就上报误报。

此外还有一条被单独标注的总体纪律："Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters."——审计要全面但可落地，P3 刷屏只会制造噪音，聚焦真正重要的问题。这解释了为什么报告结构强制要求 severity 分层 + Rating bands 定级：所有问题不可能同等重要，报告的价值在于帮下一个命令（或人）一眼看清先修什么。

六、与 native 分流：audit.native.md 与平台参考

audit.md 开头就声明 "Web only"：当目标是 iOS / Android / 自适应（adaptive）原生项目时，路由到同目录下的 audit.native.md。两条审计路径共享同一报告骨架与 P0–P3 / Rating bands / 推荐命令规则（文档要求"keep the two in sync when changing it"），但诊断维度与工具链完全不同：

Web audit 维度	Native audit 维度（iOS/Android）
Accessibility（WCAG）	Accessibility（VoiceOver / TalkBack、Dynamic Type/sp、Reduce Motion）
Performance	Performance（启动耗时、未虚拟化列表、主线程卡顿、重渲染/重组）
Theming	Appearance & Theming（语义系统色、Material color roles、Dynamic Color）
Responsive Design	Platform Conformance（系统手势、安全区 inset、跨平台导航/图标漂移）
Implementation Integrity	Adaptivity（平板拉伸、横竖屏、键盘、多窗口、折叠屏铰链）

native 路径的关键差异还在于：不适用任何浏览器工具链与 detect.mjs，而是直接从源码（SwiftUI / UIKit / Compose / React Native / Flutter）审计，并按平台参考文件打分——score against ios.md 或 android.md，adaptive 则两者都要读。其 Platform Conformance 维度的裁决问题异常尖锐："这读起来像一个原生 App，还是一个套壳网站？"（"does this read as a native app or a ported website?"）。

七、运行前提与适用边界

/impeccable audit 是 skill 命令体系的一环，运行它需要满足以下前提（均以本仓库实际内容为准）：

1. 加载 skill：本仓库在 .trae-cn/skills/impeccable/SKILL.md（及其他厂商目录下）分发该 skill，其中 name: impeccable、version: 4.1.2、license: Apache 2.0、user-invocable: true；
2. 上下文文件：SKILL.md 的 Setup 要求先运行 node <skill-base-dir>/scripts/context.mjs（一次会话一次），并保证 cwd 停留在用户项目根目录；该脚本负责加载 PRODUCT.md、DESIGN.md 等上下文；
3. 目标定位：用 --target <path> 指定要审计的源码/路由，或直接对当前 UI 执行（argumentHint: [area (feature, page, component...)]）；
4. Web 与非 Web 分流：Web 项目直接走 audit.md 流程；原生项目切换 audit.native.md 并按 ios.md / android.md 打分。

边界提醒：audit 的评分体系是面向"实现质量"的主观-客观混合框架，其中对比度阈值（4.5:1 / 7:1）、触摸目标（44px）、WCAG AA/AAA、评级区间等属于可对照标准复核的硬指标；而 Implementation Integrity、模式识别等维度需要结合检测器输出与人工语境验证。因此审计报告的权威性建立在"每一条 finding 都能定位到具体 Location 并说明 Impact"之上——这正是文档强制字段结构的目的。

结语：audit 在设计工作流中的价值

在 Impeccable 的设计哲学里，"verify in bounded passes"（有限轮次验证）是核心原则之一：构建完整 → 批量检查 → 一次批量修复 → 至多再确认一轮 → 停止打磨。/impeccable audit 正是这条原则里"批量检查"环节的标准化载体——它把无障碍、性能、主题、响应式、实现完整性五件事放进同一份带分数的报告，用 P0–P3 排序把模糊的"感觉不对"翻译成"下一个命令先去改哪一行"。读懂 audit.md，等于拿到了这套质量闭环的说明书：你可以复现它的五维扫描清单，照它的报告骨架组织自己的评审，并把它与其他 reference 文档（如 adapt.md、optimize.md、polish.md）衔接成完整的"审查 — 修复 — 打磨"流水线。