impeccable 技术质量审计指南：用 /impeccable audit 对 Web 界面进行五维评分与 P0-P3 分级整改
【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable
/impeccable audit是 impeccable 技能体系中负责技术质量评估的命令：它不做设计审美评判，而是以代码级、可测量、可验证的方式，对 Web 界面的可访问性、性能、主题化、响应式与实现完整性五个维度逐项打分（每维 0–4 分），产出一份带 P0–P3 严重度分级、整改命令映射与复测路径的完整审计报告。读完本文，你将掌握 audit 命令的完整执行协议（诊断扫描 → 评分 → 报告 → 推荐动作），理解每一条检查项背后的判定标准，并知道如何在审计通过后使用/impeccable polish等命令逐级收尾。
本文以 audit.md（其在skill/reference/、plugin/skills/impeccable/reference/等多个技能安装目录下保持同一份内容）为主体，结合仓库中检测器与评分引擎的 Rust 实现展开原理层面的补充。
一、定位与边界：这是代码审计，不是设计评审
/impeccable audit的执行纲要非常明确：
Run systematictechnicalquality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.
即：系统化地执行技术质量检查并生成综合报告；不修复问题，而是把问题记录下来交给其他命令处理。这是审计与polish、adapt等修复型命令的分工边界——audit 只负责"诊断与举证"。
同时它强调：
This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
这是代码层面的审计，不是设计评论。凡是不可测量、无法在实现中验证的"感觉问题"，都不属于 audit 的职责范围；audit 只检查能落到代码事实上的东西。这一原则与仓库中检测器的设计一脉相承：crates/detect的全部引擎都围绕"可判定、可定位、可复现"的实现事实展开（见下文"五、支撑引擎"）。
Web 平台限定：audit 明确标注Web only。对于原生平台（ios/android/adaptive），应改走 audit.native.md，其报告骨架与本文档保持一致（The report skeleton mirrors audit.md; keep the two in sync when changing it），但五个维度替换为 VoiceOver/TalkBack 可访问性、性能、外观与主题化、平台符合性（Platform Conformance）、自适应能力，并对照 ios.md 与 android.md 平台参考文档评分。如果项目是原生应用，应立即切换到原生版审计，而不是在 Web 检查项上生搬硬套。
命令在技能体系中的位置：在 SKILL.md 的 Commands 表中，audit [target]属于Evaluate（评估）类别，描述为 "Technical quality checks (a11y, perf, responsive)"，可携带[target]（feature、page、component 等）参数；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.
即触发场景是"无障碍检查、性能审计或技术质量评审"，产物是一份带 P0–P3 严重度评级和可执行计划（actionable plan）的评分报告。
二、整体流程：五维诊断扫描 → 报告生成 → 推荐动作
audit 的执行协议由三个阶段构成：
- Diagnostic Scan（诊断扫描）：跨 5 个维度执行全面检查，每个维度按 0–4 分评分；
- Generate Report（生成报告）：输出健康评分表、实现完整性裁决、执行摘要、按严重度排列的详细发现、模式化问题与正面发现；
- Recommended Actions（推荐动作）：按优先级（P0 优先，其次 P1、P2）列出建议执行的
/impeccable命令，并引导用户复跑审计验证改善。
下面依次展开五个维度的检查项与评分细则。
三、五个诊断维度：检查项与 0–4 评分细则
3.1 维度一：Accessibility（可访问性，A11y）
检查项包括：
- 对比度问题（Contrast）：文本对比度低于 4.5:1（AAA 级为 7:1）；
- 动效敏感性（Motion sensitivity）：
prefers-reduced-motion需要有意识地保留状态变化与层级关系的替代方案。需要标记的动效包括：全局0.01ms的"一刀切"动效禁用（会破坏有用反馈）、超过阈值的闪烁（flashing）、以及阻碍焦点、阅读或任务完成的动效； - ARIA 缺失：交互元素缺少正确的 role、label 或 state；
- 键盘导航：缺少焦点指示器、Tab 顺序不合逻辑、键盘陷阱（keyboard trap）；
- 语义化 HTML：标题层级错误、缺少 landmark、用
div冒充button； - 替代文本：图片缺少 alt 或 alt 质量差；
- 表单问题：输入框无 label、错误提示差、缺少必填标识。
0–4 评分：
| 分数 | 含义 |
|---|---|
| 0 | 完全不可访问（未通过 WCAG A） |
| 1 | 重大缺口（几乎没有 ARIA 标签、无键盘导航） |
| 2 | 部分达标（有一些无障碍努力，但缺口显著） |
| 3 | 良好（基本满足 WCAG AA，仅有小缺口） |
| 4 | 优秀（完全满足 WCAG AA，接近 AAA） |
3.2 维度二：Performance（性能）
检查项包括：
- 布局抖动（Layout thrashing）：在循环中交替读写布局属性；
- 昂贵动画：随意对布局属性做动画、无界 blur/filter/shadow 效果，或肉眼可见的掉帧；
- 优化缺失：图片未懒加载、资源未优化；
- will-change 滥用：
will-change被大面积应用或静止状态下仍保留（它应只是针对已知昂贵动画的定向提示，而不是基线要求）； - 包体积：多余 import、未使用的依赖；
- 渲染性能：不必要的重复渲染、缺少 memoization。
0–4 评分：0=严重问题（布局抖动、一切未优化）；1=主要问题（无懒加载、昂贵动画）；2=部分优化，仍有缺口；3=基本已优化，只有小改进空间；4=优秀（快速、精简、充分优化）。
3.3 维度三：Theming（主题化）
检查项包括：
- 硬编码颜色：颜色未使用设计令牌（design tokens）；
- 暗色模式损坏：缺少暗色变体、暗色主题下对比度差；
- 令牌不一致：用错令牌、混用令牌类型；
- 主题切换问题：主题变化时某些值不随之更新。
0–4 评分：0=无主题化（一切硬编码）；1=令牌极少（基本硬编码）；2=部分（有令牌但使用不一致）；3=良好（使用令牌，仅少量硬编码值）；4=优秀（完整令牌系统、暗色模式完美工作）。
这一维度与仓库的 DESIGN.md 设计系统解析高度对应：crates/detect/src/design_system.rs负责发现并规范化项目设计系统（resolve_design_md_path 以项目边界向上查找DESIGN.md/Design.md/design.md，并回退到.agents/context、docs目录），从 frontmatter YAML 与 sidecar JSON 中提取typography（字体、字号）、colors、rounded（圆角）、shadows等允许值白名单（normalize_design_system）。审计中"颜色是否使用设计令牌""令牌使用是否一致"等判断，正是依据这套允许列表与实现中的实际取值做比对——这也解释了为什么 audit 能做到"可测量、可验证"，而不是凭观感下结论。
3.4 维度四：Responsive Design（响应式）
检查项包括：
- 固定宽度：硬编码宽度在移动端破裂；
- 触摸目标：交互元素小于 44×44px；
- 横向滚动：窄视口下内容溢出；
- 文本缩放：文字尺寸增大后布局崩坏；
- 断点缺失：没有移动端/平板变体。
0–4 评分：0=仅桌面（移动端崩坏）；1=主要问题（有些断点但多处失效）；2=部分（移动端可用但有粗糙边角）；3=良好（响应式，偶有触摸目标或溢出小问题）；4=优秀（流式布局、覆盖所有视口、触摸目标合规）。
3.5 维度五：Implementation Integrity（实现完整性，CRITICAL）
这是最关键的维度，audit 要求：
- **运行内置检测器（Run the bundled detector）**并在上下文中逐一验证每条 finding；
- 寻找重复的实现捷径（repeated implementation shortcuts）、设计系统漂移（design-system drift）、误导性或装饰性内容（misleading or decorative content）、以及与无关产品可互换的结构（structure that is interchangeable with an unrelated product）；
- 把确定性发现（deterministic findings）与视觉判断分开，并指出误报（call out false positives）。
0–4 评分：0=系统性漂移；1=主要的重复性失败；2=若干已验证的问题；3=少量孤立问题；4=连贯且有意为之。
这里提到的 "bundled detector" 就是仓库中的impeccable detect：crates/detect/src/lib.rs中ROOT_USAGE描述为detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issues（crates/detect/src/lib.rs）。审计需要"在上下文中验证每个 finding"，意味着拿到 detector 的结论后要回到真实组件代码里确认其成立，并把纯视觉判断排除在确定性发现之外。
四、评分细则与防误报纪律
每个维度单独按 0–4 评分后，汇总为Audit Health Score。审计协议特别强调几条纪律：
- 不要报告无法解释影响的 issue（why does this matter?）；
- 不要给出泛泛的建议（要具体、可执行）；
- 不要跳过正面发现（好的实践同样值得记录）；
- 不要忘记排优先级（不可能一切都是 P0）；
- 不要在未验证的情况下报告误报。
这些纪律与detect引擎的"确定性优先"设计互为表里：crates/detect/src/engines.rs定义了两个引擎接缝——静态 HTML 引擎HtmlEngine（crates/detect/src/engines.rs#L50-L59）与浏览器/URL 引擎UrlEngine（crates/detect/src/engines.rs#L64-L73），而扫描选项ScanOptions（crates/detect/src/engines.rs#L16-L30）携带inline_ignores（是否尊重行内忽略注释）、design_system（DESIGN.md 治理的设计系统）、viewport（浏览器扫描视口）与rule_pack（可插拔规则包，impeccable二进制默认内置规则）。规则包实现在crates/core/src/checks/下，按css_scan.rs、html_patterns.rs、measures.rs、rules.rs、text_rules.rs等模块组织，并有crates/detect/tests/rule_pack.rs与crates/core/tests/rule_pack.rs等测试套件守护行为。审计报告中的每一条确定性 finding 都可以回溯到这类可运行、可测试的规则之上。
五、生成审计报告（Generate Report）
5.1 Audit Health Score（健康评分表）
报告以如下表格呈现五个维度得分与总分：
| # | Dimension | Score | Key Finding |
|---|---|---|---|
| 1 | Accessibility | ? | [most critical a11y issue or "--"] |
| 2 | Performance | ? | |
| 3 | Responsive Design | ? | |
| 4 | Theming | ? | |
| 5 | Implementation Integrity | ? | |
| Total | ??/20 | [Rating band] |
评级区间（Rating bands）：
| 分数段 | 评级 | 含义 |
|---|---|---|
| 18–20 | Excellent | 只需小幅打磨（minor polish） |
| 14–17 | Good | 修复薄弱维度即可 |
| 10–13 | Acceptable | 需要显著工作 |
| 6–9 | Poor | 需要大改造 |
| 0–5 | Critical | 根本性问题 |
注意表中第 3、4 行（Responsive Design 与 Theming）与原文档顺序一致；各维度"Key Finding"列应填写该维度最严重的问题，或 "--"。
5.2 Implementation Integrity Verdict（实现完整性裁决）
从这里开始写。Pass/fail 判定：该实现是否表达了一个连贯的、产品专属的系统？必须引用已验证的证据与 detector 的发现来支撑结论。这一节是整个报告的定调部分——先回答"产品是否自洽"，再谈具体缺陷。
5.3 Executive Summary（执行摘要）
- Audit Health Score：??/20（[评级区间]）
- 发现的问题总数（按严重度 P0/P1/P2/P3 计数）
- Top 3–5 个关键问题
- 推荐的下一步
5.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：推荐执行的命令（优先从命令白名单中选择，见下文）
5.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"（移动端体验中触摸目标持续过小）
5.6 Positive Findings（正面发现）
记录做得好、值得保持与复制的实践。audit 协议明确要求不要跳过正面发现——"celebrate what works"。
六、推荐动作（Recommended Actions）
按优先级顺序列出建议命令（P0 优先，然后 P1，再 P2）：
- [P?]
/command-name：简要描述（结合审计发现的具体上下文） - [P?]
/command-name：简要描述（具体上下文）
规则：
- 只允许推荐以下命令，并将发现映射到最合适的命令：
/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 polish作为收尾步骤； - 各命令对应实现细节见 SKILL.md 的 Commands 表，以及各自参考文档：如响应式/跨设备问题映射到 adapt.md，性能问题映射到 optimize.md，动效问题映射到 animate.md，文案问题映射到 clarify.md，最终打磨映射到 polish.md。
展示完摘要后，还需向用户说明：
You can ask me to run these one at a time, all at once, or in any order you prefer.
Re-run
/impeccable auditafter fixes to see your score improve.
即：这些命令可以逐个、全部或按任意顺序执行；修复后复跑 audit 即可看到评分提升——这构成了"审计 → 修复 → 复测"的闭环。
重要提醒：报告要彻底但可执行。过多的 P3 issue 只会制造噪音，请聚焦于真正重要的问题。
七、审计闭环与命令生态
audit 位于 impeccable 技能生态的Evaluate环节，与 Refine（polish / bolder / quieter / distill / harden / onboard）、Enhance（animate / colorize / typeset / layout / delight / overdrive）、Fix（clarify / adapt / optimize）等命令共同构成完整工作流：audit 负责找出问题并分级，其余命令按映射关系接手修复，最后以 polish 收尾、复跑 audit 验证。命令元数据（触发场景、参数提示）统一维护在 command-metadata.json（crates/context/src/command-metadata.json为同步镜像），可据此在 Agent 环境中做路由与提示。
适用前提：audit 的 Web 版检查项与检测器规则均针对浏览器端 UI 实现设计；原生项目应使用 audit.native.md，无浏览器工具链与impeccable detect适用。同时，审计报告中的确定性发现依赖 detector 的运行与上下文验证，任何未经验证的怀疑都不应写入正式结论——这既是报告质量的底线，也是"代码级审计"这一立场的直接体现。
【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
