impeccable 的 /impeccable audit面向 Web 界面的可量化代码级技术审计指南【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable/impeccable audit是 impeccable 技能体系中负责技术体检的 Evaluate 类命令。它不做设计评价而是对界面实现中可测量、可验证的部分执行系统化检查输出一份综合审计报告并标注问题优先级把发现问题与动手修复明确分离——发现问题后不直接改代码而是记录下来交给其他命令分头处理。读完本文你将掌握 audit 的完整操作协议5 大审计维度及其 0–4 评分标准、Audit Health Score 报告的生成骨架、P0–P3 问题分级与逐条记录模板、以及按优先级编排修复命令的推荐清单方法。本命令的规范定义位于 skill/reference/audit.md原生平台变体为 skill/reference/audit.native.md文章正文以该参考文档为主线并结合仓库中的命令表、CLI 与反模式检测相关实现进行展开。audit 的定位代码级审计而非设计评审审计文档开篇就划定了三条边界任何一次 audit 的执行都应先对齐这些前提只审计不修复文档明确要求 Dont fix issues; document them for other commands to address。audit 的输出物是一份报告后续由adapt、colorize、layout、optimize、polish等命令去执行修复。关注可测量的实现This is a code-level audit, not a design critique。凡是可以从代码中客观核实的问题对比度数值、触摸目标尺寸、是否硬编码颜色、是否缺少懒加载都纳入审计纯主观的视觉口味不在其列。仅限 WebWeb only.当目标项目是原生平台ios/android/adaptive时审计应立刻切换到 skill/reference/audit.native.md它面向 SwiftUI / UIKit / Compose / React Native / Flutter 从源码审计且不适用浏览器检测工具。在 impeccable 的命令体系中audit 与邻居命令的分工非常清晰这一点可以从 skill/SKILL.src.md 的 Commands 表直接看出critique属于 Evaluate 类负责的是UX 启发式审查audit属于 Evaluate 类负责的是可测量的技术质量检查a11y、性能、响应式polish属于 Refine 类负责发布前的最终质量收尾。三者构成设计评价 → 技术体检 → 上线打磨的闭环。值得一提的是这份 skill 被分发到多个 AI 编码工具的 harness 目录中如.opencode/、.claude/、.cursor/、.codex/等各自有一份.opencode/skills/impeccable/reference/audit.md之类的编译后副本而 skill/ 目录是其在仓库中的权威来源真正的源文件以模板变量{{command_prefix}}、{{available_commands}}占位编译后每个 harness 会替换为各自的命令前缀常见形如/impeccable audit。所以下文统一使用/impeccable audit表示该命令实际运行时以你所在 harness 注入的前缀为准。诊断扫描五个维度的检查点与 0–4 评分audit 的诊断扫描阶段跨 5 个维度执行综合检查每个维度按下面的标准打0–4 分。1. Accessibility可访问性A11y检查清单对比度问题文本对比度低于 4.5:1追求 AAA 时需 7:1动效敏感度prefers-reduced-motion需要提供有意的替代方案替代方案必须保留状态变化与层级关系。需要标记的反模式包括用一个全局0.01ms的 kill 把有用反馈全部消灭、超过闪烁阈值的动画、以及会阻碍焦点移动、阅读或任务完成的动效缺失 ARIA交互元素缺少正确的角色role、标签label或状态state键盘导航缺少焦点指示、Tab 顺序不合逻辑、出现键盘陷阱keyboard trap语义化 HTML标题层级混乱、缺少 landmark、用 div 代替 buttonAlt 文本图片描述缺失或质量差表单问题输入框没有关联 label、错误提示文案差、缺少必填标识。0–4 评分量规分数含义0完全不可访问不满足 WCAG A1重大缺口几乎没有 ARIA 标签、没有键盘导航2部分达标有一定 a11y 努力但缺口明显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主题化检查清单硬编码颜色颜色没有走设计 token深色模式损坏缺少深色变体、深色主题下对比度差token 使用不一致用错 token、混用 token 类型主题切换问题主题切换时部分值不更新。分数含义0完全没有主题化一切硬编码1token 极少基本是硬编码2部分达标存在 token 但使用不一致3良好使用 token存在少量硬编码值4优秀完整 token 体系深色模式完美运转4. Responsive Design响应式设计检查清单固定宽度硬编码宽度导致移动端破版触摸目标交互元素小于 44×44px横向滚动窄视口下内容溢出文字缩放字体尺寸放大后布局崩坏缺少断点没有移动/平板变体。分数含义0仅桌面端移动端直接崩坏1主要问题有少量断点但多处失败2部分达标移动端可用但粗糙3良好响应式可用触摸目标或溢出有少量问题4优秀流式布局、全视口适配、触摸目标合规5. Implementation Integrity实现完整性CRITICAL这是标记为CRITICAL的一维audit 在此需要运行仓库自带的检测器bundled detector并对每一条发现做上下文核实。它关注的是反复出现的实现捷径、design-system 漂移、误导性或纯装饰性内容、以及结构上与任何无关产品都可以互换的同质化 UI。要点是把确定性deterministic的发现与主观视觉判断分开记录并主动指出误报false positives。分数含义0系统性漂移1大范围反复失败2有若干条经核实的问题3零散的轻微问题4连贯且有意图的实现运行 bundled detectoraudit 背后的可复用检测能力Implementation Integrity 要运行 bundled detector 在 impeccable 中并不是抽象说法仓库里有真实可执行的检测器。从 package.json 可以看到包的main指向检测引擎、并暴露了impeccable这个 bincli/bin/cli.js 中detect子命令会加载检测引擎的detectCli并对文件/目录/URL执行反模式扫描入口即命令注释里的npx impeccable detect [file-or-dir-or-url...]同时还提供ignores子命令用于管理检测忽略规则文件、具体值等。也就是说audit 需要核实的每条实现完整性发现都可以在命令行用同一套检测器复现再回到源码上下文判断是否成立。仓库还维护了一套庞大的反模式夹具语料 tests/fixtures/antipatterns/里面以should-flag/should-pass/*-should-flag/*-should-pass成对命名的 HTML/JSX/Vue/Svelte 样例刻画了检测器应当命中 / 应当放行的边界——例如should-flag.html、should-pass.html、visual-contrast.html、motion.html、typography-should-flag.html等。这套语料既服务于检测器自身的回归测试也意味着 audit 文档反复强调的在上下文中核实每条 finding、隔离误报是有工程基础支撑的。生成报告Audit Health Score 与五段式骨架当 5 个维度打完分后audit 进入生成报告阶段。报告骨架在 skill/reference/audit.md 中是固定模板且 skill/reference/audit.native.md 明确要求自己的报告骨架与 Web 版保持同步The report skeleton mirrors audit.md。Audit Health Score 总表先汇总一张评分表#维度分数关键发现1Accessibility?[最严重的 a11y 问题或 --]2Performance?3Responsive Design?4Theming?5Implementation Integrity?总计??/20[评级区间]总分对应如下评级区间rating bands区间评级含义18–20Excellent仅需少量打磨14–17Good修复薄弱维度10–13Acceptable需要显著返工6–9Poor需要大改0–5Critical存在根本性问题Implementation Integrity Verdict从这里开始报告的第一个实质章节不是总表而是实现完整性结论。audit 要求从这里开始就一个 pass/fail 问题作答当前实现是否表达出一套连贯的、产品特有的系统必须引用经核实的证据和检测器发现来支撑结论不能凭观感下判断。Executive Summary执行摘要摘要以固定格式汇总Audit Health Score??/20[评级区间]问题总数按 P0/P1/P2/P3 严重度计数最关键的 3–5 个问题Top 3–5 critical issues推荐的下一步行动Detailed Findings by Severity按严重度逐条列出发现每条问题必须打上P0–P3严重度标签级别名称处置时机P0 Blocking阻断问题阻止任务完成立即修复P1 Major重大问题造成显著使用困难或违反 WCAG AA发布前修复P2 Minor次要问题造成困扰但存在绕过方案下一轮处理P3 Polish打磨项可修可不修无真实用户影响有空再修对每一条问题报告需要完整记录以下字段[P?] 问题名称Location组件、文件、行号CategoryAccessibility / Performance / Theming / Responsive / Implementation Integrity 五选一Impact它如何影响用户这是为什么重要的论证WCAG/Standard违反了哪条标准如适用Recommendation如何修复Suggested command建议用哪条命令处理从下方命令白名单中选取例如一条典型的记录- [P1] 表单输入框缺少关联 label - Location: components/SignupForm.tsx, L42 - Category: Accessibility - Impact: 屏幕阅读器用户无法获知该输入框用途 - WCAG/Standard: WCAG 1.3.1 / 3.3.2 - Recommendation: 为 input 提供可见 label 并通过 for/id 关联 - Suggested command: /impeccable adaptPatterns Systemic Issues模式与系统性问题audit 要求识别反复出现的同型问题因为它们暴露的是系统性缺口而非一次性失误。文档给出的两个示范句式值得照搬使用Hard-coded colors appear in 15 components, should use design tokens硬编码颜色出现在 15 个组件中应改用设计 tokenTouch targets consistently too small (44px) throughout mobile experience整个移动端体验中触摸目标持续小于 44pxPositive Findings正面发现审计报告不是批斗会。文档专门提醒记录哪些做得好、值得保留与复刻的实践并在报告完成后积极反馈给用户。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推荐格式如下每条命令后要附上来自审计发现的具体上下文而不是空泛的描述1. [P1] /impeccable adapt修复移动端多处 44px 的触摸目标与固定宽度引起的横向滚动 2. [P2] /impeccable layout统一卡片间距节奏消除 15 处硬编码 margin 值「把发现映射到最合适的命令」这一步可以参考各命令在 skill/SKILL.src.md Commands 表中的语义adapt负责多设备/多尺寸适配、layout负责间距节奏与视觉层级、optimize负责 UI 性能诊断修复、colorize负责战略性配色、typeset负责排版层级与字体、animate负责有目的的动效、clarify负责 UX 文案与错误提示、harden负责错误态/国际化/边界情况、distill负责删繁就简、bolder/quieter分别放大与收敛视觉强度、polish负责发布前的最终质量收尾。如果本轮推荐了任何修复命令最后一步必须以/impeccable polish收尾。在呈现摘要之后audit 还要原样告知用户这是一段写死在参考文档里的对白模板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.你可以让我一次跑一条、一次全跑或按你喜欢的任意顺序执行。修复后请重跑/impeccable audit你会看到分数提升。这揭示了 audit 的迭代定位它不追求一次到位而是把体检 → 修复 → 复检做成可循环的闭环用同一个 20 分制标尺追踪改进。报告的克制原则与 NEVER 清单文档在末尾用IMPORTANT和NEVER强调了报告质量的底线Be thorough but actionableP3 打磨项过多会制造噪音聚焦真正重要的问题NEVER 清单报告问题却不解释影响它为什么重要给出空泛的建议要具体、可执行跳过正面发现值得庆祝的做法要写进去忘记排优先级不可能每条都是 P0未经核实就报告误报false positives 必须验证后再判定。在 impeccable 工作流中的位置audit 如何与相邻文件协作从仓库结构可以看清 audit 参考文档所处的完整生态这对理解它的调用约定很有帮助命令路由audit属于 Evaluate 类命令与critiqueUX 启发式审查并列当平台是ios/android/adaptive时路由要求切换到 skill/reference/audit.native.md其 5 个维度变为 AccessibilityVoiceOver/TalkBack、Performance、Appearance Theming、Platform ConformanceCRITICAL、Adaptivity评分前须先阅读平台基准 skill/reference/ios.md 与 skill/reference/android.md配套文档audit建议的修复命令各有自己的参考页如 skill/reference/adapt.md、skill/reference/optimize.md、skill/reference/polish.md 等遵循文档记录 → 命令修复的接力模式执行入口差异/impeccable audit是发生在 AI 编码工具会话内的 slash 命令仓库 CLI 甚至在检测到用户在终端误输入init时会提示它属于 AI 编码工具Claude Code、Cursor、Codex…的聊天而不是终端而检测器本身可脱离会话独立运行例如npx impeccable detect 路径|URL与 hooks 的配合仓库还提供了设计检测 hookskill/reference/hooks.md可在 UI 文件编辑后自动运行检测器并浮出发现这相当于把 audit 中最机械的跑检测器环节前置到了每次编辑之后。总而言之/impeccable audit是一套有明确评分协议、固定报告骨架、严格问题分级与受限修复命令编排的技术审计方法。它的价值不在于挑错而在于把界面质量变成一组可复现、可打分、可追踪的工程度量20 分制的健康分让你对当前状态一目了然P0–P3 分级让修复优先级没有争议命令白名单则保证每一条发现都有对应的、恰到好处的处理通道——而最后那句 Re-run/impeccable auditafter fixes to see your score improve 始终提醒你这是一场可以量化的、可持续改进的质量游戏。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考