Impeccable Audit 技术体检指南为 Web 界面实现做系统化、可量化的质量审查【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读Impeccable 是一套围绕让 AI 具备更好的设计能力而构建的 Agent Skill设计语言与工具集版本 v4.1.2Apache 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 有三个铁律般的原则只审计、不修复把所有问题记录成文档化的 finding交给其他命令adapt、optimize、polish 等按优先级处理面向 Webaudit 是 Web 流程。若项目是 iOS / Android / 自适应原生应用应切换到 audit.native.md详见下文第七节全程跑在真实实现上每个结论都必须在代码与渲染上下文中被验证报告里要明确区分确定性发现deterministic findings与视觉判断并主动标记误报。二、Diagnostic Scan五个技术维度与评分标准audit 在 5 个维度上做全面扫描每个维度用 0–4 分评分。0 最差4 优秀维度之间独立打分最终汇总为 20 分制健康分。下面逐维展开均为文档口径括号内为判断要点。1. Accessibility无障碍A11y检查项对比度问题文本对比度低于 4.5:1WCAG AA或追求 AAA 时低于 7:1动效敏感度prefers-reduced-motion需要一种保留状态变化与层级的有意替代方案。要特别标记三类问题——用全局0.01ms的暴力关闭毁掉有效反馈的动效、超过闪烁阈值的内容、阻碍聚焦/阅读/完成任务的动作ARIA 缺失交互元素缺少正确的 role、label 或状态键盘导航缺少焦点指示、Tab 顺序不合逻辑、出现键盘陷阱语义化 HTML标题层级错乱、缺少 landmark、用div充当buttonAlt 文本图片描述缺失或质量差表单问题输入框没有 label、错误提示糟糕、缺少必填标识。评分口径分数含义0完全不可访问未通过 WCAG A1重大缺口几乎没有 ARIA 标签、无键盘导航2部分达标有一些无障碍投入但缺口显著3良好基本满足 WCAG AA仅剩轻微缺口4优秀完全满足 WCAG AA接近 AAA2. 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审计健康分用一张汇总表呈现五个维度的分数与最关键发现#DimensionScoreKey Finding1Accessibility?最严重的无障碍问题或 --2Performance?3Responsive Design?4Theming?5Implementation Integrity?Total??/20[评级区间]**评级区间Rating bands**是判断优先级的总纲18–20 Excellent只需轻微打磨minor polish14–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组件、文件、行号CategoryAccessibility / Performance / Theming / Responsive / Implementation IntegrityImpact对用户的实际影响WCAG/Standard违反的标准如适用Recommendation具体修复方式Suggested command建议使用的修复命令3.5 Patterns Systemic Issues模式与系统性问题识别反复出现的问题——它们指向系统级缺口而非一次性失误。文档给了两条示范表达Hard-coded colors appear in 15 components, should use design tokens15 个组件里出现硬编码颜色应使用设计令牌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 auditafter 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/AndroidAccessibilityWCAGAccessibilityVoiceOver / TalkBack、Dynamic Type/sp、Reduce MotionPerformancePerformance启动耗时、未虚拟化列表、主线程卡顿、重渲染/重组ThemingAppearance Theming语义系统色、Material color roles、Dynamic ColorResponsive DesignPlatform Conformance系统手势、安全区 inset、跨平台导航/图标漂移Implementation IntegrityAdaptivity平板拉伸、横竖屏、键盘、多窗口、折叠屏铰链native 路径的关键差异还在于不适用任何浏览器工具链与detect.mjs而是直接从源码SwiftUI / UIKit / Compose / React Native / Flutter审计并按平台参考文件打分——score against ios.md 或 android.mdadaptive则两者都要读。其 Platform Conformance 维度的裁决问题异常尖锐这读起来像一个原生 App还是一个套壳网站does this read as a native app or a ported website?。七、运行前提与适用边界/impeccable audit是 skill 命令体系的一环运行它需要满足以下前提均以本仓库实际内容为准加载 skill本仓库在 .trae-cn/skills/impeccable/SKILL.md及其他厂商目录下分发该 skill其中name: impeccable、version: 4.1.2、license: Apache 2.0、user-invocable: true上下文文件SKILL.md 的 Setup 要求先运行node skill-base-dir/scripts/context.mjs一次会话一次并保证 cwd 停留在用户项目根目录该脚本负责加载 PRODUCT.md、DESIGN.md 等上下文目标定位用--target path指定要审计的源码/路由或直接对当前 UI 执行argumentHint: [area (feature, page, component...)]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衔接成完整的审查 — 修复 — 打磨流水线。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考