impeccable 技术质量审计指南：用 /impeccable audit 对 Web 界面进行五维评分与 P0-P3 分级整改

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. Dont fix issues; document them for other commands to address.即系统化地执行技术质量检查并生成综合报告不修复问题而是把问题记录下来交给其他命令处理。这是审计与polish、adapt等修复型命令的分工边界——audit 只负责诊断与举证。同时它强调This is a code-level audit, not a design critique. Check whats 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:1AAA 级为 7:1动效敏感性Motion sensitivityprefers-reduced-motion需要有意识地保留状态变化与层级关系的替代方案。需要标记的动效包括全局0.01ms的一刀切动效禁用会破坏有用反馈、超过阈值的闪烁flashing、以及阻碍焦点、阅读或任务完成的动效ARIA 缺失交互元素缺少正确的 role、label 或 state键盘导航缺少焦点指示器、Tab 顺序不合逻辑、键盘陷阱keyboard trap语义化 HTML标题层级错误、缺少 landmark、用div冒充button替代文本图片缺少 alt 或 alt 质量差表单问题输入框无 label、错误提示差、缺少必填标识。0–4 评分分数含义0完全不可访问未通过 WCAG A1重大缺口几乎没有 ARIA 标签、无键盘导航2部分达标有一些无障碍努力但缺口显著3良好基本满足 WCAG AA仅有小缺口4优秀完全满足 WCAG AA接近 AAA3.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 detectcrates/detect/src/lib.rs中ROOT_USAGE描述为detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issuescrates/detect/src/lib.rs。审计需要在上下文中验证每个 finding意味着拿到 detector 的结论后要回到真实组件代码里确认其成立并把纯视觉判断排除在确定性发现之外。四、评分细则与防误报纪律每个维度单独按 0–4 评分后汇总为Audit Health Score。审计协议特别强调几条纪律不要报告无法解释影响的 issuewhy does this matter?不要给出泛泛的建议要具体、可执行不要跳过正面发现好的实践同样值得记录不要忘记排优先级不可能一切都是 P0不要在未验证的情况下报告误报。这些纪律与detect引擎的确定性优先设计互为表里crates/detect/src/engines.rs定义了两个引擎接缝——静态 HTML 引擎HtmlEnginecrates/detect/src/engines.rs#L50-L59与浏览器/URL 引擎UrlEnginecrates/detect/src/engines.rs#L64-L73而扫描选项ScanOptionscrates/detect/src/engines.rs#L16-L30携带inline_ignores是否尊重行内忽略注释、design_systemDESIGN.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 Report5.1 Audit Health Score健康评分表报告以如下表格呈现五个维度得分与总分#DimensionScoreKey Finding1Accessibility?[most critical a11y issue or --]2Performance?3Responsive Design?4Theming?5Implementation Integrity?Total??/20[Rating band]评级区间Rating bands分数段评级含义18–20Excellent只需小幅打磨minor polish14–17Good修复薄弱维度即可10–13Acceptable需要显著工作6–9Poor需要大改造0–5Critical根本性问题注意表中第 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组件、文件、行号CategoryAccessibility / Performance / Theming / Responsive / Implementation IntegrityImpact对用户的影响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环节与 Refinepolish / bolder / quieter / distill / harden / onboard、Enhanceanimate / colorize / typeset / layout / delight / overdrive、Fixclarify / adapt / optimize等命令共同构成完整工作流audit 负责找出问题并分级其余命令按映射关系接手修复最后以 polish 收尾、复跑 audit 验证。命令元数据触发场景、参数提示统一维护在 command-metadata.jsoncrates/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），仅供参考