impeccable：AI编程时代的前端设计质检CLI与浏览器扩展

1. 项目缘起与核心定位1.1 一个被名字耽误的实用工具第一次看到impeccable这个词很多人会愣一下——这词儿在词典里是无可挑剔的、完美的意思用作项目名多少有点自嘲或者高标准的意味。但真正用过之后你会发现它其实是一个面向AI coding agents时代的前端设计辅助工具核心形态是一个CLI 命令行工具同时配套了一个browser extension浏览器扩展。它的定位非常明确让开发者在跟 AI 编程助手协作时前端代码的产出质量能真正达到挑不出毛病的水准。说白了现在用 AI 写前端代码的人越来越多但普遍有个痛点——AI 生成的界面代码能跑但不好看、不规范、不符合设计系统。impeccable 就是冲着这个痛点来的。它不替代 AI而是给 AI 的产出加一道设计质检的关卡。这个项目适合谁三类人最该关注一是天天用 AI 辅助写前端、但总在 UI 细节上返工的开发者二是想给团队建立前端代码规范、又不想手动 review 每一行的技术负责人三是做独立产品、没有专职设计师、需要工具帮忙兜底的独立开发者。1.2 为什么是 CLI 浏览器扩展的组合这里有个设计思路值得拆解。为什么不做成纯 Web 应用也不做成纯编辑器插件而是选了 CLI 加浏览器扩展CLI 的价值在于可集成。它能塞进 CI/CD 流程能在 git hook 里跑能被其他脚本调用。对于 AI coding agents 来说CLI 是最自然的交互界面——agent 执行命令、拿到结构化输出、再决定下一步。这跟当前 codex cli、zcode cli 这类工具的使用习惯是一致的开发者已经习惯了在终端里跟 AI 协作。浏览器扩展的价值在于可视化验证。前端设计好不好最终得在浏览器里看。扩展能实时抓取页面渲染结果把设计层面的问题间距、对比度、层级、响应式断点直接标注出来。CLI 负责批处理和集成扩展负责实时反馈和视觉确认两者互补覆盖了开发流程的不同阶段。提示如果你只装 CLI 不装扩展能用但会丢掉实时视觉反馈这一块反过来只装扩展不装 CLI就没法集成到自动化流程里。建议两个都上。2. 核心能力拆解它到底在检查什么2.1 设计规范层面的静态检查impeccable 最核心的能力是对前端代码做设计规范层面的静态分析。注意它不是 ESLint 那种语法检查也不是 Prettier 那种格式化它检查的是设计意图层面的东西。具体来说它会扫描你的 CSS、Tailwind 类名、组件样式定义然后对照一套内置的设计规则库做比对。这套规则库覆盖了几个维度间距系统一致性你的 margin、padding 是不是遵循了统一的 scale比如 4px 基准的倍数有没有出现 13px、17px 这种随手写的值。颜色使用规范有没有硬编码的十六进制颜色散落在各处对比度是否达到可访问性标准WCAG AA 至少 4.5:1。字体层级字号、字重、行高的组合是否形成了清晰的视觉层级有没有出现标题和正文一样大这种问题。响应式断点媒体查询的断点值是否统一有没有在五个不同地方写了五个不同的断点。这些检查项听起来基础但实际项目里翻车率极高。我见过太多 AI 生成的前端代码功能没问题但间距全是 magic number颜色东一个西一个改起来比重写还累。2.2 与 AI coding agents 的协作机制这是 impeccable 最有意思的部分。它不是简单地报错而是输出结构化的、AI 可读的诊断报告。当你用 codex cli 或者类似的 AI 编程助手时可以让 agent 先跑一遍 impeccable拿到一份 JSON 格式的问题清单然后 agent 根据这份清单去修复。整个流程是这样的Agent 生成前端代码执行impeccable check命令拿到结构化的问题报告包含文件、行号、问题类型、建议修复值Agent 逐条修复再跑一次验证这个闭环的价值在于它把设计质量这个原本很主观的东西变成了 AI 能理解和执行的明确指令。AI 不需要猜你想要什么样的间距impeccable 直接告诉它这里应该是 16px 不是 13px。注意不同 AI agent 对结构化输出的解析能力不一样。实测下来codex cli 和 trae cli 对 JSON 格式的诊断报告处理得比较顺能自动定位到具体行去改。如果你的 agent 解析能力弱可以先用--formattext输出人类可读版本手动喂给它。2.3 浏览器扩展的实时标注能力浏览器扩展这块做的是运行时检查。它注入一个轻量的脚本到页面里实时计算每个元素的盒模型、颜色对比度、字体渲染结果然后在页面上叠加标注层。这个能力在调试响应式布局时特别有用。你可以拖动浏览器窗口改变宽度扩展会实时告诉你当前断点下哪些元素溢出了、哪些文字对比度不够了、哪些点击区域小于 44x44 的可访问性最小值了。这些问题是静态代码检查抓不到的必须运行时才能发现。扩展还支持快照对比。你可以保存一个设计基准快照然后每次改完代码刷新页面扩展会自动 diff 出视觉差异。这个功能在跟 AI 反复迭代界面时简直是救命稻草——AI 改了一版你一眼就能看出它是不是把之前调好的间距又改乱了。3. 实操落地从安装到集成进工作流3.1 安装与初始化配置安装部分CLI 走的是标准的包管理流程。假设你用 npm 生态npm install -g impeccable-cli装完之后在项目根目录初始化配置impeccable init这个命令会生成一个impeccable.config.json文件。这个配置文件是整个工具的核心它决定了检查规则、忽略路径、输出格式等。一个典型的配置长这样{ designSystem: { spacingScale: [0, 4, 8, 12, 16, 24, 32, 48, 64], colorPalette: ./tokens/colors.json, typographyScale: ./tokens/typography.json, breakpoints: [640, 768, 1024, 1280, 1536] }, ignore: [node_modules/**, dist/**, **/*.test.*], severity: { spacing: error, color: error, contrast: error, typography: warn }, output: { format: json, reportPath: ./.impeccable/report.json } }这里有几个配置项值得展开说。spacingScale定义了你项目允许的间距值集合任何不在这个集合里的间距都会被标记。colorPalette指向你的设计 token 文件impeccable 会检查代码里有没有绕过 token 直接用硬编码颜色。severity让你能分级处理——间距和颜色这种硬性问题设成 error字体层级这种偏主观的设成 warn。提示初始化时如果你项目里已经有 Tailwind 配置impeccable 能自动读取tailwind.config.js里的 theme 配置帮你预填 spacingScale 和 colorPalette。省得手动抄一遍。3.2 跑第一次检查与读懂报告配置好之后跑一次全量检查impeccable check --path./src第一次跑报告大概率会很长。别慌这是正常的。重点看报告的结构{ summary: { filesScanned: 47, issuesFound: 213, errors: 156, warnings: 57 }, issues: [ { file: src/components/Button.tsx, line: 23, column: 5, rule: spacing-scale, severity: error, message: Padding value 13px is not in the spacing scale, suggestion: Use 12px or 16px instead, context: padding: 13px 20px; } ] }读报告有个技巧先按 rule 分组看别按文件看。因为同一类问题往往在项目里成片出现按规则分组能让你一次性理解我这类问题有多严重然后批量修。比如你发现 spacing-scale 报了 80 个错那说明整个项目的间距系统是失控的这时候该做的是统一重构而不是一个个改。3.3 集成进 AI 协作流程真正发挥威力是把它接进 AI coding agent 的工作流。以 codex cli 为例你可以在项目根目录放一个 agent 指令文件告诉它每次改完前端代码后自动跑 impeccable# 在 agent 的工作流配置里加入 impeccable check --path./src --formatjson --reportPath./.impeccable/latest.json然后给 agent 的提示词里加上一句修改完成后读取 .impeccable/latest.json修复所有 severity 为 error 的问题修复后重新运行检查直到 error 数为 0。实测下来这个闭环能把 AI 生成前端代码的设计返工率降低一大半。以前 AI 写完你得手动调半天间距颜色现在它自己就能收敛到一个规范的状态。注意别让 agent 无限循环修复。设个上限比如最多迭代 3 轮。有些问题比如设计 token 本身定义得有问题agent 是修不好的会陷入死循环。这时候需要人工介入调整配置。3.4 浏览器扩展的安装与使用浏览器扩展的安装走的是常规流程从扩展商店装或者开发者模式加载本地包都行。装完之后在任意页面上点扩展图标会弹出一个小面板。面板上有几个核心功能实时检查开关打开后页面上会叠加标注层有问题的元素会被高亮。快照保存点一下保存当前页面的视觉基准。差异对比刷新页面后点对比会显示跟基准快照的视觉差异。导出报告把当前页面的运行时问题导出成 JSON可以喂给 CLI 一起分析。我个人的使用习惯是开发阶段开着实时检查边写边看改完一个模块后保存快照让 AI 迭代几轮后做一次差异对比确认没有引入视觉回归。4. 踩坑记录与问题排查4.1 常见问题速查表问题现象可能原因排查与解决检查报告为空路径配置错误或文件被 ignore检查--path参数和 config 里的 ignore 规则大量误报设计 token 未正确加载确认 colorPalette/typographyScale 路径正确且文件格式合法扩展标注不显示页面有 CSP 限制或 iframe 隔离检查控制台是否有 CSP 报错尝试在非 iframe 页面测试AI agent 修复后问题依旧agent 未读取最新报告确认报告路径一致且 agent 有文件读取权限快照对比差异过大页面有动态内容时间、随机数在扩展设置里排除动态区域或改用静态测试数据CLI 执行超时扫描文件过多用--path缩小范围或增加--timeout参数4.2 几个我踩过的坑坑一spacingScale 设得太严。一开始我把 scale 设成只有 4 的倍数结果项目里所有 6px、10px 这种半格值全报错报告几千条根本没法看。后来改成允许 4 的倍数加上常用的半格值6、10、14误报率立刻降下来。设计系统不是越严格越好得贴合实际使用习惯。坑二忽略动态内容导致快照对比失效。有次做差异对比每次都报一大堆差异查了半天发现是页面上的时间戳和随机推荐位在变。后来在扩展设置里把这些区域标记为动态排除对比才准了。坑三让 AI 修 contrast 问题修出花来。对比度不够的问题AI 有时候会直接把文字改成纯黑或纯白对比度是够了但设计上很难看。后来我在配置里加了contrastStrategy: adjust-lightness让它优先调整明度而不是直接换色效果好很多。坑四CI 里跑 impeccable 没设阈值。有段时间 CI 天天红因为 impeccable 报了一堆 warn 级别的问题。后来在 CI 配置里加了--fail-onerror只有 error 级别才让流水线失败warn 只记录不阻断团队接受度立刻上来了。4.3 性能优化的小技巧项目大了之后全量检查会变慢。几个提速手段用--incremental模式只检查上次检查后变动的文件。把node_modules、dist、测试文件都加进 ignore。如果只是想在提交前快速过一遍用--changed-only只检查 git staged 的文件。浏览器扩展的实时检查可以调低采样频率默认是每 500ms 扫一次改成 1000ms 对体验影响不大但省不少 CPU。5. 进阶玩法与扩展思路5.1 自定义规则开发impeccable 支持自定义规则。规则文件是一个导出特定接口的 JS 模块module.exports { name: no-inline-style, severity: warn, check(node, context) { if (node.type JSXAttribute node.name.name style) { return { message: Inline style detected, use className instead, suggestion: Move styles to CSS module or Tailwind classes }; } return null; } };把规则文件放进.impeccable/rules/目录重启检查就会自动加载。这个能力让你能把团队内部的设计约定也变成可自动检查的规则。比如所有按钮必须有 hover 态、所有图片必须有 alt 属性这类约定都能写成规则。5.2 与设计工具的联动如果你的团队用 Figma 之类的设计工具可以把设计 token 导出成 JSON直接喂给 impeccable 的 colorPalette 和 typographyScale。这样设计稿和代码之间的 token 就完全同步了设计师改了颜色导出一次代码检查规则自动更新。这个联动做起来不难Figma 有 token 导出插件导出的 JSON 格式稍微转换一下就能用。关键是建立起设计 token 单一来源的机制避免设计和代码各维护一套。5.3 在 monorepo 里的用法monorepo 项目里可以在根目录放一份共享的 impeccable 配置各个子包通过 extends 继承{ extends: ../../impeccable.config.json, designSystem: { colorPalette: ./tokens/colors.json } }这样共享规则统一维护各包只覆盖自己特有的部分。跑检查的时候在根目录跑全量或者进到具体子包跑增量都行。6. 关于工具选型的一点个人看法市面上做前端代码质量检查的工具不少ESLint、Stylelint、Prettier 各管一摊。impeccable 的差异化在于它面向 AI 协作场景做了专门优化——结构化输出、可被 agent 解析、支持迭代修复闭环。这是传统 lint 工具没考虑的维度。但它也不是万能的。它管的是设计规范这一层语法错误、逻辑 bug、性能问题它都不管。所以实际项目里它是跟 ESLint、Stylelint 配合使用的各司其职。我的建议是把它当成设计质检员而不是全能代码检查器。另外工具再好设计 token 本身得先定义清楚。如果项目连一套统一的间距和颜色规范都没有impeccable 跑出来的报告只会是一团乱麻。上这个工具之前先把设计系统的基础打好收益会大得多。最后分享一个我自己的使用节奏新项目初始化时就配好 impeccable让 AI 从第一行代码就在规范内生成老项目接入时先跑一次全量把 error 级别的问题批量修掉warn 级别的慢慢来日常开发开着浏览器扩展的实时检查改完一个模块做一次快照对比。这套节奏跑下来前端界面的返工率能压到很低跟 AI 协作的体验也顺畅很多。