impeccable audit 实战：Web 界面的五维技术质量审计与 P0-P3 分级报告

导读

/impeccable audit 是 Impeccable 设计语言体系中的技术审计命令：它不评价审美品味，而是对实现代码做可测量、可验证的质量检查，覆盖无障碍（Accessibility）、性能（Performance）、主题化（Theming）、响应式（Responsive Design）与实现完整性（Implementation Integrity）五个维度，最终产出一份带 0-4 分评分、P0-P3 严重度分级和修复命令建议的综合报告。读完本文，你将掌握 audit 的完整诊断维度与评分标准、报告骨架的每个组成部分，以及如何把每个发现映射到对应的修复命令（如 /impeccable adapt、/impeccable optimize、/impeccable polish），让审计结果真正落地为可执行的改进计划。

什么是 audit：技术审计，不是设计评审

在 Impeccable 的 Commands 表 中，audit 属于 Evaluate（评估） 类命令，其定位是：

Run systematic technical quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.

这决定了 audit 的三个核心原则：

1. 只审技术、不改代码：audit 的输出是问题清单与修复建议，修复动作交给其他命令完成（adapt、optimize、polish 等）。
2. 只查可测量、可验证的事实：对比度比值、点击目标尺寸、是否使用设计令牌、是否存在布局抖动——这些都是可以量化的实现事实，而不是主观审美。
3. Web 专属：原生平台（ios / android / adaptive）应切换到 audit.native.md，其报告骨架与 Web 版保持一致（源文件中有明确注释："The report skeleton mirrors audit.md; keep the two in sync when changing it"），但审计维度替换为 VoiceOver/TalkBack 无障碍、平台一致性（Platform Conformance）、适配性（Adaptivity）等原生指标。

对应命令元数据在 plugin/skills/impeccable/scripts/command-metadata.json 中登记为："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."

五维诊断扫描：评分标准与检查清单

audit 在每个维度按 0-4 分评分，满分 20 分。评分锚点高度一致：0 分代表该维度完全缺失或系统性失败，4 分代表达到优秀水平。下面逐维度展开检查清单与评分标准。

1. 无障碍 Accessibility（A11y）

检查项	具体要求
对比度	文本对比度 < 4.5:1（WCAG AA），或追求 7:1（WCAG AAA）时需要标记
动效敏感度	prefers-reduced-motion 需要提供保留状态变化与层级关系的有意替代方案；需标记全局 0.01ms 级"杀死所有动效"的粗暴做法（它会摧毁有用的反馈）、超过阈值（约 3 次/秒）的闪烁，以及阻碍聚焦、阅读或任务完成的动效
ARIA	交互元素缺少正确的 role、label 或 state
键盘导航	缺少焦点指示、Tab 顺序不合逻辑、存在键盘陷阱（keyboard trap）
语义化 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）

这是最高优先级的维度，且是唯一明确要求"运行内置检测器"的维度：

Run the bundled detector and verify each finding in context.

需要重点排查：反复出现的实现捷径、设计系统漂移（design-system drift）、误导性或纯装饰性内容，以及"与无关产品可互换"的结构化模板感。同时必须把确定性发现（deterministic findings）与视觉判断分开，并明确标注误报（false positives）。

评分锚点：0=系统性漂移；1=重大反复失败；2=数个已验证问题；3=少量孤立问题；4=连贯且有意为之（coherent and intentional）。

审计报告的完整骨架

诊断完成后，audit 按固定骨架生成报告。以下每个小节都不可或缺。

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	存在根本性问题

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

报告从这一节开始。核心问题是：这个实现是否表达了一个连贯的、产品专属的系统？必须引用已验证的证据和检测器发现来回答。

Executive Summary（执行摘要）

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

Detailed Findings by Severity（按严重度分级的问题明细）

每个问题必须标注 P0-P3 严重度：

级别	含义	处理时机
P0 Blocking	阻止任务完成	立即修复
P1 Major	造成显著困难或违反 WCAG AA	发布前修复
P2 Minor	烦扰、存在变通方案	下一轮修复
P3 Polish	锦上添花、无实质用户影响	有时间再修

每个问题的记录模板包含 8 个字段：

• [P?] 问题名称
• 位置：组件、文件、行号
• 类别：Accessibility / Performance / Theming / Responsive / Implementation Integrity
• 影响：对用户的影响方式
• WCAG/标准：违反了哪个标准（如适用）
• 建议：如何修复
• 推荐命令：从下面 19 个命令中挑选最合适的一个

Patterns & Systemic Issues（模式与系统性问题）

识别反复出现的、表明系统性缺口而非偶发失误的问题。文档给出的典型例子：

• "Hard-coded colors appear in 15+ components, should use design tokens"（硬编码颜色出现在 15+ 组件中，应改用设计令牌）
• "Touch targets consistently too small (<44px) throughout mobile experience"（移动端触控目标普遍过小）

Positive Findings（积极发现）

记录运行良好的部分：值得保持和复制的良好实践。文档明确要求不要跳过这部分。

修复命令映射：从发现到行动

每个问题必须映射到一条修复命令，且只能从以下白名单中选择：/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。

推荐命令按优先级排序（P0 在前，随后 P1、P2）：

1. [P0] /impeccable optimize：布局抖动、昂贵动画、包体积、渲染性能等性能问题
2. [P1] /impeccable adapt：触控目标过小、断点缺失、固定宽度等响应式问题
3. [P1] /impeccable typeset：标题层级混乱、字号可读性等排版无障碍问题
4. [P2] /impeccable colorize：主题令牌缺失、暗色模式对比度不足等主题化问题
5. [P2] /impeccable clarify：表单 label 缺失、错误提示不清晰等 UX 文案问题
6. [P2] /impeccable harden：交互元素的 ARIA 状态、表单语义等健壮性问题

如果推荐了任何修复，必须以 /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.

（修复后重跑 /impeccable audit，即可看到分数提升——这也说明 audit 是一个可迭代、可量化的闭环流程。）

源码级佐证：检测器如何支撑 "Implementation Integrity"

audit 第 5 维度的"运行内置检测器"并非空话——Impeccable 仓库的 Rust 实现中确实存在一个独立完整的检测引擎 impeccable-detect（crates/detect），它是从 JS 版 cli/engine 移植而来，负责 UI 反模式与设计质量问题扫描。

双引擎架构

从 engines.rs 可以看到两个引擎接缝：

• HtmlEngine（静态 HTML 引擎）：由 crates/html 实现，对 .html / .htm 文件直接扫描，不需要浏览器。
• UrlEngine（浏览器/URL 引擎）：由 crates/browser 实现，通过 CDP 驱动真实浏览器扫描在线页面，支持 waitUntil: 'networkidle0' 的独立扫描模式与共享浏览器会话模式（open_shared，waitUntil: 'load'、settleMs: 100）。

detect 本身不依赖这两个 crate，而是由 CLI 二进制通过 Engines 注入具体实现——从源码结构看，这是为了保持 detect 与具体引擎解耦。

规则集的组织方式

检测规则按关注点拆分为多个模块（crates/core/src/checks/mod.rs）：

• rules：纯元素检查（checkBorders、checkColors、checkHoverContrast、checkIconTile、checkItalicSerif、checkHeroEyebrow、checkKickerAboveHeading、checkMotion、checkGlow 等）；
• css_scan：CSS 文本扫描器（glow、grid background、radial halo、pseudo-stripe、marquee、pulsing dot、organic clip-path、buried raster 等反模式）；
• measures：数值门槛检查（oversized H1、cream 色板识别、透明装饰盒等）；
• text_rules：文本规则（kicker 候选、编号章节标签、em-dash 滥用、重复文本容器检测）。

这些正是 audit 报告里"确定性发现"的来源：每个 finding 对应一条可验证的规则，因此报告要求把确定性发现与视觉判断分开、并标注误报，是完全有实现依据的。

设计系统对照：Theming 维度的底层机制

audit 的主题化维度检查"硬编码颜色"与"令牌不一致"，其背后是 design_system.rs 中的设计系统解析能力：

• DESIGN.md 发现：向上查找项目根目录（以 .git、package.json、.impeccable 为边界标记）中的 DESIGN.md（含 Design.md / design.md 大小写变体），并回退到 .agents/context 与 docs 目录；
• Frontmatter 解析：解析 DESIGN.md 中的 YAML 子集（typography、colors、rounded 等区块），同时读取侧车文件 .impeccable/design.json 或 DESIGN.json 中的 colorMeta、roundedMeta、shadows 扩展；
• 允许清单（allowlist）：将设计系统归一化为允许字体、允许颜色键（带 ±6 通道容差）、允许圆角（±0.5px 容差）、允许字号（±0.5px 容差）与允许阴影颜色。

检测器据此判断页面中出现的颜色/字体/圆角是否属于设计系统允许清单——这正是 audit 第 3 维度"Theming"和第 5 维度"design-system drift"的判定依据。

性能可观测性：Profiler

profiler.rs 提供了检测器自身的性能剖析能力：profile_findings 对每条规则计时并记录 finding 数量与 ID，summarize_detector_profile 则按 engine/phase/ruleId/target 分组汇总，输出 calls、totalMs、avgMs、p50、p95 等统计。虽然该能力主要用于库调用方（CLI 无 --profile 标志），但它印证了 Impeccable 对"性能可测量"的一贯态度——连检测器自己的性能都是可量化的。

执行审计的完整流程

结合 SKILL.md 的 Setup 约定，一次完整的 audit 运行流程如下：

1. 加载上下文：在用户项目目录下运行 "${CLAUDE_SKILL_DIR}/scripts/impeccable" context（Windows 无 sh 时用 impeccable.cmd），加载 PRODUCT.md、DESIGN.md、匹配的 surface brief 与原生平台指引。该启动器是自包含二进制，无需 Node 运行时。
2. 加载审计规程：读取 reference/audit.md（Web 项目）或 reference/audit.native.md（原生项目），按其五维标准执行扫描。
3. 运行检测器：对 Implementation Integrity 维度运行内置检测器（HTML 引擎或 URL 引擎），并在真实上下文中逐条验证 finding。
4. 生成报告：按上文骨架输出评分表、裁决、执行摘要、分级明细、系统性问题、积极发现与按优先级排序的修复命令清单。
5. 闭环迭代：用户选择按任意顺序逐条或全部执行修复命令，修复完成后重跑 /impeccable audit 验证分数提升；若推荐了任何修复，最后一步总是 /impeccable polish。

结语与关键守则

audit 文档在结尾给出了五条 NEVER 守则，它们共同定义了高质量审计报告的底线：

• 不报告问题却不说清影响（为什么它重要？）；
• 不给泛泛的建议（要具体、可执行）；
• 不跳过积极发现（值得庆祝的也要记录）；
• 不忘记优先级排序（不能全是 P0）；
• 不核实就报告误报。

最后，文档还强调："Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters."——审计要彻底，但要克制；过多的 P3 细节只是噪音，聚焦真正影响用户与发布的事项，才是 audit 的价值所在。这正是 Impeccable 把审计做成"可评分、可分级、可闭环"流程的核心设计意图。