impeccable audit 技术审计实战指南Web 前端五维评分、P0–P3 分级与修复命令映射【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableimpeccable 的audit命令是一套面向 Web 前端的代码级技术质量审计流程在 5 个可度量维度上系统扫描可验证的实现缺陷生成带健康评分与严重度分级的综合报告并给出可执行的修复命令清单。本指南以 skill/reference/audit.md 为骨架结合仓库中detect检测引擎的真实源码说明每个维度的检查项、0–4 评分标准、报告结构与命令映射规则让你能独立完成一次「不修 bug、只做体检」的高质量审计。audit 的定位代码审计不是设计批评audit是 impeccable 的Evaluate评估类命令在 skill/SKILL.src.md 的命令表中与critique并列critique做 UX 启发式评分audit则做技术质量检查a11y、性能、响应式等。两者的分工体现在 audit 文档开头的一句原则This is a code-level audit, not a design critique. Check whats measurable and verifiable in the implementation.审计只检查实现中可度量、可验证的内容——对比度比值、是否存在懒加载、是否使用设计令牌、触控目标是否达到 44px——而不是对视觉风格的主观评价。同时它恪守一条纪律只记录问题、不修问题Dont fix issues; document them for other commands to address把修复动作留给polish、harden、optimize、adapt等后续命令。适用范围的硬性约束Web onlyaudit 明确声明Web only。对于原生平台ios/android/adaptive路由切换到 skill/reference/audit.native.md它从源码SwiftUI / UIKit / Compose / React Native / Flutter审计不使用浏览器工具链也不适用impeccable detect评分基准改为平台参考文档 skill/reference/ios.md 与 skill/reference/android.mdadaptive同时参考两者。两份文档的报告骨架刻意保持同步The report skeleton mirrors audit.md; keep the two in sync。因此使用 audit 的第一步是确认目标类型Web 项目走本流程原生项目立即切换到 native 变体。五维诊断扫描检查项与 0–4 评分标准audit 要求对目标进行五个维度的全面检查每个维度按 0–4 打分。下面逐维度展开检查项与评分锚点并补充仓库源码中的对应实现佐证。1. 可访问性Accessibility / A11y检查清单覆盖六类问题对比度问题文本对比度低于 4.5:1AAA 标准为 7:1动效敏感度prefers-reduced-motion需要保留状态变化与层级的有意替代方案要标记「全局 0.01ms 杀戮开关」式destroy useful feedback的处理、超过阈值的闪烁、以及阻塞聚焦/阅读/任务完成的动效缺失 ARIA交互元素缺少正确的 role、label 或 state键盘导航缺失焦点指示、不合逻辑的 Tab 顺序、键盘陷阱语义化 HTML标题层级错乱、缺失 landmark、用 div 充当 buttonalt 文本与表单问题图片描述缺失或低劣、输入无 label、错误提示差、缺少必填标识。评分锚点0不可访问不满足 WCAG A、1重大缺口几乎没有 ARIA、无键盘导航、2部分达标有 a11y 投入但缺口显著、3良好基本满足 WCAG AA少量缺口、4优秀完全满足 WCAG AA逼近 AAA。从源码看low-contrast、gray-on-color、skipped-heading、tiny-text、undersized-ui-text、tight-leading等规则都在检测器的内置反模式库中注册见 crates/foundation/src/registry.rs 的ANTIPATTERNS列表。例如low-contrast的规则描述即写明Text does not meet WCAG AA contrast requirements (4.5:1 for body, 3:1 for large text)与 audit 检查清单的对比度阈值完全一致说明审计维度与检测器规则是同源的。2. 性能Performance检查清单聚焦渲染与加载成本布局抖动Layout thrashing在循环中反复读写布局属性昂贵动画随意动画化布局属性、无限制的 blur/filter/shadow 效果、肉眼可见的掉帧优化缺失图片没有懒加载、资源未优化will-change滥用广泛使用或静止状态仍保留它是针对已知昂贵动画的定点提示不是基线要求包体积无意义的 import、未使用的依赖渲染性能不必要的重渲染、缺少 memoization。评分锚点0严重问题布局抖动、全未优化、1重大问题无懒加载、昂贵动画、2部分优化、3良好大体优化有可改进空间、4优秀又快又轻又省。检测器中对应规则如layout-transition动画化 width/height/padding/margin 导致布局抖动建议改用 transform/opacity 或 grid-template-rows正是性能维度的规则化表达注册在 crates/foundation/src/registry.rs 的 quality 类别下。3. 主题化Theming检查清单关注设计令牌的贯彻程度硬编码颜色未使用设计令牌的颜色暗色模式破损缺少暗色变体、暗色主题下对比度差令牌不一致用错令牌、混用令牌类型主题切换问题切换主题时值不更新。评分锚点0无主题化全部硬编码、1令牌极少大部分硬编码、2部分有令牌但使用不一致、3良好使用令牌少量硬编码值、4优秀完整令牌系统暗色模式完美。对应的检测器规则包括design-system-color、design-system-font、design-system-radius、design-system-font-size四个design-system-*规则——凡是字面颜色/字体/圆角/字号不在项目DESIGN.md声明的系统内就会记为设计系统漂移其中颜色、圆角、字号为 advisory 级别字体为普通 quality 级。这印证了 audit 的 Theming 维度「检验的是实现是否遵守项目自己的令牌体系」。4. 响应式设计Responsive Design检查清单覆盖五类典型失效模式固定宽度硬编码宽度在移动端撑破布局触控目标交互元素小于 44×44px横向滚动窄视口下内容溢出文本缩放字体放大后布局崩坏断点缺失没有移动/平板变体。评分锚点0仅桌面移动端必崩、1主要问题有断点但多处失败、2部分移动端可用但有毛边、3良好响应式良好少量触控目标或溢出问题、4优秀流式布局、全视口、触控目标达标。检测器中的text-overflow内容超出容器、body-text-viewport-edge正文贴视口边缘、edge-flush-cards卡片贴滚动容器边缘等规则都是响应式失效的具体可检测形态impeccable detect --viewport 390x844见下文 CLI 参数则可用移动宽度视口对 URL 做专门的移动端扫描。5. 实现完整性Implementation IntegrityCRITICAL这是唯一被标记为CRITICAL的维度也是 audit 报告最先输出结论的部分Start here。检查要点运行内置检测器Run the bundled detector并在上下文中逐一验证每条 finding寻找重复出现的实现捷径、设计系统漂移、误导性或装饰性内容识别「与无关产品可互换的结构」structure that is interchangeable with an unrelated product——即模板化、缺乏产品特异性的实现把确定性发现与视觉主观判断分开并指出误报call out false positives。评分锚点0系统性漂移、1重大反复失败、2多个已核实问题、3少量孤立问题、4连贯且有意为之。这里bundled detector即impeccable detect引擎。其ANTIPATTERNS内置规则库61 条见 crates/foundation/src/registry.rs分slop/quality两个大类别slop类规则识别 AI 生成界面的标志性特征如side-tab侧边彩色描边、the most recognizable tell of AI-generated UIs、overused-font过度使用字体、ai-color-paletteAI 配色、gradient-text渐变文字、em-dash-overuse破折号滥用、marketing-buzzword营销黑话等quality类规则识别客观质量问题低对比度、文本溢出、破损图片等。规则引擎支持矩阵定义在RULE_ENGINE_SUPPORTregex、static-html、browser、visual四种引擎各自支持source/page-analyzer/element/page/layout/visual-contrast等检查能力说明完整性核查可以穿透源码级与渲染级两层证据。生成报告从评分到结构化输出诊断完成后按固定骨架输出报告各小节如下。Audit Health Score评分表与评级区间五维得分汇总为一张表格最后一列填写各维度最关键的发现无则--#DimensionScoreKey Finding1Accessibility?[most critical a11y issue or --]2Performance?3Responsive Design?4Theming?5Implementation Integrity?Total??/20[Rating band]总分 20 分对应五个评级区间18–20 Excellent仅需小修补minor polish14–17 Good针对薄弱维度处理即可10–13 Acceptable需要大量工作6–9 Poor需要重大整改0–5 Critical存在根本性问题。Implementation Integrity Verdict从这里读起报告的第一个结论段落是实现完整性裁定通过/失败——实现是否表达了一个连贯的、产品特异性的系统要求引用已核实的证据与检测器 findingsCite verified evidence and detector findings。它解决的是最关键的问题这套 UI 是「为这个产品而设计」的还是任何产品都能套用的模板产物。Executive Summary执行摘要摘要需包含四项硬信息Audit Health Score??/20评级区间问题总数按 P0/P1/P2/P3 分级统计Top 3–5 关键问题建议的下一步行动。Detailed Findings by Severity按严重度逐条记录每条 finding 必须以P0–P3打标四档语义为P0 Blocking阻断任务完成立即修复P1 Major造成显著困难或违反 WCAG AA发布前必须修复P2 Minor造成困扰但存在绕行方案下一轮修复P3 Polish可修可不修无真实用户影响。每条问题需要完整记录七个字段[P?] 问题名称Location组件、文件、行号CategoryAccessibility / Performance / Theming / Responsive / Implementation IntegrityImpact对用户的实际影响WCAG/Standard违反的标准如适用Recommendation具体修法Suggested command建议使用的命令优先从{{available_commands}}中选取审计报告的 finding 记录结构与检测器的Finding数据结构一一对应。在 crates/foundation/src/findings.rs 中Finding按 JS 原实现的键序序列化antipattern, name, description, severity, category, file, line, snippet可选advisory标记与调用方附加的 extras如ignoreValue。CLI 的文本输出格式见 crates/detect/src/cli.rs 的format_findings会把 findings 按文件分组逐条输出line N: [antipattern] snippet与→ description这与审计报告中Location 影响 证据的记录粒度天然吻合。Patterns Systemic Issues识别系统性问题这一节要求区分「一次性失误」与「系统性缺口」给出模式化证据例如Hard-coded colors appear in 15 components, should use design tokensTouch targets consistently too small (44px) throughout mobile experience系统性问题之所以重要是因为它指向根本性修复引入令牌系统、统一触控规范而非逐个打补丁。Positive Findings正面发现审计不是只挑毛病还要记录做得好的实践celebrate what works作为后续维护与复用的基准。NEVER 清单中明确要求Skip positive findings。Recommended Actions命令映射与修复闭环报告最后按优先级P0 → P1 → P2列出推荐命令每条格式为[P?]{{command_prefix}}command-name针对审计发现的特定描述两条硬性规则只能推荐{{available_commands}}范围内的命令把 finding 映射到最合适的命令只要有推荐修复最后一步必须以{{command_prefix}}impeccable polish收尾。随后向用户呈现固定的交接文案You can ask me to run these one at a time, all at once, or in any order you prefer.Re-run{{command_prefix}}impeccable auditafter fixes to see your score improve.polish作为收尾命令在 skill/reference/polish.md 中有明确定义它是细化而非偷换的重设计Polish is refinement, never concealed redesign并按「功能缺陷 → 缺失状态 → 流程/层级/响应式/设计系统漂移 → 视觉与动效 → 代码与资产清理」的次序修复。polish 明确写道A detector result is defect evidence, not proof of quality——检测器结论是缺陷证据而非质量证明最终仍需人工走查真实交互路径这与 audit 的 Implementation Integrity 维度verify each finding in context一脉相承形成「审计 → 修复 → 复检」的闭环。报告纪律NEVER 清单文档最后给出五条红线直接约束报告质量不解释影响就不要报告问题why does this matter?不给泛泛建议要具体、可执行不跳过正面发现不忘记排序不可能全是 P0不经验证就报告误报。源码纵深audit 背后的 detect 引擎如何工作audit 的 Implementation Integrity 维度要求Run the bundled detector理解它需要知道impeccable detect的三种扫描模式与参数体系。USAGE文本定义在 crates/detect/src/cli.rsHTML 文件静态 HTML/CSS 分析默认模式会顺带解析链接的外部 CSS非 HTML 文件正则模式匹配CSS、JSX、TSX 等URLPuppeteer 全量浏览器渲染自动识别http(s)://与file://并纳入可访问的链接 CSS。常用参数包括--jsonJSON 输出人类可读结果走 stderr保证 stdout 留给结构化输出--quiet文本模式只打印最终计数--scope name按设计域过滤规则如type、layout逗号分隔--viewport WxHURL 扫描的浏览器视口默认 1280x800例如--viewport 390x844做移动宽度扫描--no-config/--no-inline-ignores/--no-design-system分别关闭项目配置、文件内impeccable-disable*忽略注释、本地DESIGN.md上下文--no-advisory完全抑制 advisory 类 finding。退出码语义0无 primary findings1至少一个目标无法扫描操作失败优先2存在 primary findings。advisory 类 finding 单列区块、不计入失败数、不改变退出码因此不会阻断自动化——这正是审计报告中可以把打磨项与阻断项区分开的机制基础。引擎的抽象层在 crates/detect/src/engines.rsEngines持有静态 HTML 引擎crates/html实现与浏览器/URL 引擎crates/browser实现两个 trait 对象ScanOptions携带 inline 忽略开关、设计系统上下文、视口与规则包。而规则包机制registry::extend见 crates/foundation/src/registry.rs允许外部规则包注册自定义反模式行——内置规则永远优先包规则不能遮蔽内置 id碰撞会直接 panic。这意味着 audit 所依赖的检测器是可扩展的团队可以把自己的技术规范注册为规则让审计的Implementation Integrity维度覆盖项目专属标准。与相关命令的分工audit 在 impeccable 工作流中的位置在 skill/SKILL.src.md 的命令表中audit 属于 Evaluate 类与周边命令形成清晰分工critique [target]UX 设计评审启发式评分评估体验层面audit [target]技术质量检查a11y、性能、响应式评估实现层面polish [target]发布前的最终质量通过Refine 类承接 audit 的修复建议optimize [target]专项诊断并修复 UI 性能adapt [target]适配不同设备与屏幕尺寸。一次标准的质量闭环是critique评审体验 →audit审计实现并产出 P0–P3 分级报告 → 按报告执行映射命令 →polish统一收尾 → 重新运行audit验证评分提升。audit 文档要求Be thorough but actionable并提醒Too many P3 issues creates noise. Focus on what actually matters——一份高质量审计报告的价值不在于条目多而在于每一条都有影响解释、有位置定位、有可执行修复方案、有正确的优先级。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考