1. 项目缘起与核心定位1.1 一个被名字耽误的宝藏工具第一次看到 impeccable 这个词很多人会愣一下——这到底是个什么项目名字本身是无可挑剔的、完美的意思听起来像是一个设计规范文档或者某个高冷的设计系统。但实际上它是一个面向 AI 编程代理时代的前端设计增强工具核心形态是一个 CLI 命令行工具同时配套浏览器扩展。说白了它解决的是这样一个问题现在用 AI 编程代理比如各种 codex cli、claude code 这类工具写前端代码速度是快了但生成出来的界面往往能用但不好看——间距随意、配色辣眼、层级混乱、响应式一塌糊涂。impeccable 就是在这个环节介入给 AI 生成的前端代码做一次设计体检和自动修复让输出结果从能跑提升到能看。这个定位非常精准。我观察下来2024 年到 2025 年这段时间AI coding agents 的爆发让大量开发者开始用 CLI 工具直接生成整个前端页面。但大家普遍遇到一个痛点AI 写逻辑很强写视觉很弱。它能给你一个功能完整的表单但那个表单的 padding 可能是 13px按钮颜色是默认蓝卡片阴影重得像贴了张纸。impeccable 就是冲着这个缝隙来的。1.2 它到底能做什么从实际使用角度拆解impeccable 的能力可以分成三层第一层是检测。它扫描你的前端代码HTML/CSS/JSX/Vue 模板等识别出设计层面的问题。注意它不是 ESLint 那种语法检查而是设计规则检查——比如间距是否遵循统一的 scale、颜色是否超出调色板、字体层级是否超过三级、对比度是否达标、触摸目标是否小于 44px 等等。第二层是建议。针对检测出的问题它会给出具体的修改建议而且这些建议是可执行的——不是泛泛地说改善间距而是告诉你把 margin-bottom: 13px 改成 16px符合 4px 基准网格。第三层是自动修复。这是最实用的部分。通过 CLI 命令它可以直接改写你的样式文件把不规范的数值替换成规范值。对于用 AI 生成的大量前端代码来说这个自动修复能省掉大量手动调整的时间。浏览器扩展则是另一个入口。你在浏览器里打开一个页面扩展可以实时标注出设计问题适合做设计审查或者给非技术同学演示。1.3 适合谁来用我梳理了一下这几类人用 impeccable 收益最明显用 AI CLI 工具生成前端代码的开发者你已经在用 codex cli 或者类似的工具批量产出页面impeccable 可以作为后处理步骤接在流程里。独立开发者和小团队没有专职设计师但希望产品界面看起来专业。前端工程师想建立一套可维护的设计规范但不想手动写一堆 lint 规则。设计工程师Design Engineer这个角色现在越来越吃香impeccable 正好是这类岗位的日常工具。反过来说如果你团队已经有成熟的设计系统和完善的 code review 流程impeccable 的增量价值会小一些但作为自动化检查的一环仍然有用。2. 核心设计思路与方案拆解2.1 为什么选择 CLI 浏览器扩展的双形态这个架构选择值得说道说道。很多类似工具只做 CLI或者只做浏览器插件impeccable 两个都做背后是有逻辑的。CLI 的定位是批量和自动化。你可以在 CI/CD 流程里跑它可以在生成代码后立刻调用它可以写脚本批量处理整个项目。它的用户是开发者和自动化流程。CLI 的优势在于可组合性——你可以把 impeccable 的输出 pipe 给其他工具可以集成到 git hook 里可以用在构建流程中。浏览器扩展的定位是实时和可视化。设计问题很多时候是看到了才知道有问题纯文本报告不够直观。扩展能在真实渲染的页面上直接标注鼠标悬停显示问题详情这种交互方式对设计审查场景更友好。它的用户包括设计师、产品经理以及需要快速检查页面的开发者。两者共享同一套核心规则引擎这是关键。如果规则不一致CLI 说没问题、扩展说有问题那就乱套了。impeccable 的做法是把规则抽成独立的配置层两个前端都读取同一份配置。这个设计思路值得借鉴——任何做多端工具的项目都应该这样分层。2.2 规则引擎的设计哲学impeccable 的规则引擎不是拍脑袋定的它背后有一套设计原则。我研究了一下它的规则分类大致遵循这几个维度一致性优先于绝对正确。设计里很少有绝对的对错但一致性是硬要求。如果项目里有的地方用 8px 间距、有的用 10px、有的用 12px那就是问题。impeccable 会检测这种不一致而不是规定你必须用某个具体值。可配置但有好默认。它内置了一套基于主流设计系统类似 Tailwind 的 spacing scale、Material 的 elevation 等的默认规则开箱即用。同时允许你通过配置文件覆盖。这个平衡点找得不错——新手直接用默认老手可以定制。分级告警。问题分 error、warning、info 三级。error 是明确违反规则的比如对比度不达标影响可访问性warning 是建议改进的比如间距不在 scale 上info 是提示性的比如可以考虑用 CSS 变量。这种分级让团队可以根据自己的严格程度选择阻断级别。2.3 与 AI 编程代理的协作模式这是 impeccable 最有意思的部分也是它区别于传统 lint 工具的地方。它专门考虑了和 AI coding agents 的协作。传统流程是人写代码 → lint 检查 → 人修复。AI 时代的流程变成了人下指令 → AI 生成代码 → impeccable 检查 → AI 修复或人修复。impeccable 的输出格式对 AI 友好——结构化的 JSON 报告包含文件路径、行号、问题类型、建议修改值。这意味着你可以把 impeccable 的报告直接喂回给 AI 代理让它自动修复。我实测过这个循环用 codex cli 生成一个页面跑 impeccable 检查把报告贴回给 AI 让它修复再跑一次检查。两轮下来页面的设计规范度提升非常明显。这个工作流值得单独拿出来讲后面会详细展开。3. 核心功能细节与实操要点3.1 安装与初始化配置impeccable 的安装走的是标准 CLI 工具路线。根据我的使用经验推荐用包管理器全局安装这样在任何项目里都能直接调用。# 以 npm 为例具体包名以官方为准 npm install -g impeccable-cli # 验证安装 impeccable --version安装完成后在项目根目录初始化配置impeccable init这个命令会生成一个配置文件通常是impeccable.config.json或类似名称里面包含规则集、忽略路径、告警级别等。初始化时会问你几个问题项目类型React/Vue/原生 HTML、是否使用 Tailwind、设计基准间距基准值、调色板来源。这些回答决定了默认规则的生成。注意初始化时如果选了 Tailwind它会读取你的tailwind.config.js来生成间距和颜色的规则这样检测结果会和你的实际设计系统对齐。如果你用的是 CSS 变量方案它会扫描你的:root定义。这一步别跳过配置准确了后续误报会少很多。3.2 规则配置的实操细节配置文件是 impeccable 的核心。我拿一个实际项目的配置举例说明关键字段{ spacing: { base: 4, scale: [0, 4, 8, 12, 16, 24, 32, 48, 64], tolerance: 0 }, colors: { palette: auto, maxColors: 12, contrastStandard: WCAG_AA }, typography: { maxLevels: 4, minBodySize: 14, lineHeightRange: [1.4, 1.8] }, ignore: [node_modules/**, dist/**, *.min.css] }几个关键点解释一下spacing.base设为 4意味着所有间距应该是 4 的倍数。scale定义了允许的具体值。tolerance设为 0 表示严格模式不允许偏差如果设为 1则允许 ±1px 的误差。实际项目里我建议初期用 tolerance: 1避免大量误报打击信心等修复得差不多了再收紧。colors.maxColors限制调色板颜色数量。这个规则很有用——AI 生成代码时经常随手造颜色一个页面搞出二十几种颜色。限制在 12 种以内能强制收敛。typography.maxLevels限制字体层级数量。超过 4 级比如 h1-h4 加 body就会告警。这条规则能有效防止字号通胀。3.3 检测命令的用法与输出解读基础检测命令impeccable check ./src输出默认是彩色终端报告按文件分组每个问题显示行号、类型、当前值、建议值。我更喜欢用 JSON 输出方便后续处理impeccable check ./src --format json --output report.jsonJSON 报告的结构大致是这样{ summary: { files: 24, errors: 3, warnings: 47, infos: 12 }, issues: [ { file: src/components/Button.tsx, line: 18, rule: spacing/scale, severity: warning, current: padding: 13px, suggested: padding: 12px, message: Spacing value 13px is not on the 4px scale } ] }这个结构对 AI 非常友好。你可以写个脚本把 issues 数组转成自然语言提示喂给 AI 代理让它批量修复。3.4 自动修复功能的使用与边界自动修复命令impeccable fix ./src --severity warning这个命令会直接改写源文件。--severity参数控制修复哪些级别的问题。我强烈建议先跑 check 看清楚要改什么再跑 fix而且 fix 之前一定要有 git 提交或者备份。实操心得自动修复对间距和颜色数值的替换很可靠但对涉及布局结构调整的问题比如这个卡片应该用 flex 而不是 float它不会动因为那超出了安全替换的范围。所以 fix 之后仍然需要人工 review 一遍。我一般的工作流是check → 看报告 → fix → git diff 审查 → 手动处理剩余问题。还有一个--dry-run参数只显示会改什么但不实际写入。第一次用某个项目时务必先 dry-run 看看改动范围。3.5 浏览器扩展的安装与使用浏览器扩展的安装方式取决于你用的浏览器。装好之后在任意页面点击扩展图标它会扫描当前页面的计算样式computed styles在页面上用彩色边框标注有问题的元素侧边栏显示问题列表点击可定位到元素支持导出报告这个功能在做设计审查时特别好用。我经常用它来检查第三方页面或者线上环境看看别人的设计系统是怎么落地的学习角度或者检查自己项目的线上表现。扩展的一个隐藏用法它可以检测动态渲染后的样式而 CLI 只能检测源码。有些问题比如 JS 动态计算出的间距只有扩展能发现。两者互补。4. 与 AI 编程代理的完整协作流程4.1 为什么这个流程值得单独讲前面提到过impeccable 最大的价值场景是和 AI coding agents 配合。这个流程不是简单的生成完检查一下而是一个可以闭环的迭代系统。我把它拆成四个阶段每个阶段都有讲究。4.2 阶段一生成前的规则注入在让 AI 生成代码之前你可以把 impeccable 的规则摘要作为上下文注入给 AI。具体做法是把配置文件里的关键规则转成自然语言放在 prompt 里。比如生成前端代码时请遵循以下设计规范 - 所有间距使用 4px 的倍数推荐值4/8/12/16/24/32/48/64 - 颜色不超过 12 种优先使用项目已有的 CSS 变量 - 字体层级不超过 4 级正文不小于 14px - 行高在 1.4 到 1.8 之间 - 所有交互元素触摸目标不小于 44x44px这一步能显著降低后续修复的工作量。AI 在有明确约束时生成质量会好很多。我实测下来注入规则后impeccable 的 warning 数量能减少一半以上。4.3 阶段二生成后的自动检测AI 生成完代码立刻跑检测impeccable check ./src --format json --output .impeccable/report.json把报告存到一个固定路径方便后续步骤读取。如果你的 AI 代理支持读取文件大部分 CLI 代理都支持可以直接让它读这个报告。4.4 阶段三报告回喂与自动修复这是关键一步。把 JSON 报告转成 AI 能理解的指令。我写过一个简单的转换脚本import json with open(.impeccable/report.json) as f: report json.load(f) prompt 请修复以下前端设计问题只修改指定的值不要改动其他逻辑\n\n for issue in report[issues]: if issue[severity] in (error, warning): prompt f- {issue[file]}:{issue[line]} prompt f将 {issue[current]} 改为 {issue[suggested]}\n print(prompt)把这段输出贴给 AI 代理它就能批量修复。对于用 codex cli 这类工具的场景你可以把这个脚本集成到工作流里实现半自动甚至全自动。4.5 阶段四验证与迭代修复完再跑一次 check对比前后报告impeccable check ./src --format json --output .impeccable/report-after.json impeccable diff .impeccable/report.json .impeccable/report-after.jsondiff命令会显示修复了多少问题、还剩多少。一般两轮迭代就能把 warning 降到可接受范围。剩下的通常是需要人工判断的复杂问题。经验之谈不要追求零 warning。有些 warning 是合理的例外比如品牌色故意不在调色板里、某个特殊组件需要非标准间距。impeccable 支持在代码里加注释来忽略特定行类似 ESLint 的// impeccable-disable-next-line。合理使用这个机制避免为了消除 warning 而破坏设计意图。5. 常见问题与排查技巧实录5.1 误报太多怎么办这是新手最常遇到的问题。跑完 check 发现几百个 warning直接劝退。我的处理顺序是第一步检查配置是否匹配项目实际。如果你用的是 Tailwind但初始化时没选 Tailwind那间距规则就是错的必然大量误报。重新跑impeccable init或者手动改配置。第二步放宽 tolerance。初期把 spacing 的 tolerance 设为 1 或 2颜色规则先关掉只保留 error 级别的检查。等基础问题修完再逐步收紧。第三步用 ignore 排除第三方代码。node_modules、dist、vendor这些目录必须排除否则你会被第三方库的样式淹没。第四步逐条审查剩余 warning。如果某条规则在你的项目里确实不适用直接在配置里关掉它。工具是为你服务的不是反过来。5.2 自动修复改坏了代码怎么办首先永远在 git 干净状态下跑 fix。这样出问题一个git checkout .就恢复了。如果 fix 之后发现某些改动不对可以针对性回滚。impeccable 的 fix 是逐条应用的你可以在 git diff 里看到每一处改动选择性保留。预防措施先用--dry-run看改动清单确认没问题再实际执行。对于大型项目建议分目录逐步 fix而不是一次性全项目跑。5.3 和现有 lint 工具冲突impeccable 检查的是设计层面ESLint/Stylelint 检查的是代码层面理论上不冲突。但实际使用中可能有重叠比如 Stylelint 也有 spacing 相关的规则。我的建议是明确分工Stylelint 管语法和代码风格比如属性顺序、单位规范impeccable 管设计规范比如间距 scale、颜色数量。如果发现重复在其中一个工具里关掉对应规则。通常我会在 Stylelint 里关掉设计相关的规则让 impeccable 统一管。5.4 浏览器扩展检测结果和 CLI 不一致这个问题的根源通常是CLI 检测源码扩展检测渲染后的计算样式。两者看到的东西不一样。比如你在 CSS 里写了padding: 1remCLI 看到的是1rem扩展看到的是计算后的16px。如果配置里 scale 只认 pxCLI 可能报 warning 而扩展不报或者反过来。解决办法配置里同时支持多种单位或者在 CLI 配置里开启单位转换。impeccable 较新版本支持在配置里指定rootFontSize这样 rem 和 px 能互相换算两边结果就一致了。5.5 常见问题速查表问题现象可能原因排查方向解决方式大量 spacing warning配置基准值与项目不符检查 spacing.base 和 scale重新 init 或手动改配置颜色规则疯狂告警项目用了大量 CSS 变量检查 palette 配置设为 auto 或指定变量文件fix 后样式错乱自动替换了不该替换的值查看 git diff回滚用 ignore 排除扩展不显示标注页面用了 Shadow DOM检查扩展权限更新扩展版本或手动检查CLI 和扩展结果不一致单位换算问题检查 rootFontSize 配置统一单位或开启换算检测速度慢扫描了 node_modules检查 ignore 配置添加排除路径5.6 几个独家避坑技巧技巧一把 impeccable 加进 git pre-commit hook。只对 staged 文件跑 checkerror 级别阻断提交warning 级别只提示。这样能防止新的设计问题进入代码库。# .husky/pre-commit 示例 npx impeccable check --staged --severity error技巧二为不同环境准备不同配置。开发环境用宽松配置只看 errorCI 环境用严格配置error warning。通过--config参数切换。技巧三定期导出报告做趋势分析。把每次 CI 的 report.json 存档用脚本统计 warning 数量的变化趋势。如果某段时间 warning 激增说明有新代码引入了设计问题可以及时干预。技巧四用 impeccable 的输出训练团队规范。把常见的 warning 类型整理成团队的设计规范文档比干巴巴地讲要用 4px 网格有效得多因为每条规则都有实际代码案例支撑。6. 工具选型与生态位分析6.1 和同类工具的对比市面上做前端设计检查的工具不多impeccable 的定位比较独特。我把它和几个相关工具做个对比工具检查层面自动修复AI 协作浏览器扩展impeccable设计规范支持原生支持有Stylelint代码风格部分支持一般无ESLint代码质量部分支持一般无Lighthouse性能/可访问性无无内置设计系统文档人工审查无无无impeccable 的差异化在于它专注设计规范这个细分领域而且原生考虑了 AI 协作场景。这个定位在 AI 编程普及的当下非常应景。6.2 什么情况下不该用它工具再好也有适用边界。这几种情况我建议先别上 impeccable项目还在原型阶段设计频繁变动此时规范检查是负担团队没有设计规范共识impeccable 的默认规则可能不符合团队审美项目是纯后端或者 CLI 工具没有前端界面已经有一套非常成熟的设计系统且有自动化检查增量价值有限6.3 和其他 CLI 工具的配合在实际工作流里impeccable 通常不是单独使用的。我的典型工具链是这样的代码生成用 AI CLI 工具代码质量用 ESLint代码风格用 Prettier设计规范用 impeccable构建用 Vite 或类似工具。每个工具管好自己的事通过 npm scripts 串起来{ scripts: { check:design: impeccable check ./src, fix:design: impeccable fix ./src --severity warning, check:all: npm run lint npm run check:design } }这样一条npm run check:all就能跑完所有检查集成到 CI 里也很方便。7. 实际项目中的落地体会我在几个不同类型的项目里用过 impeccable感受差异挺大的。一个用 React Tailwind 的 SaaS 项目接入非常顺滑。因为 Tailwind 本身就是基于 scale 的impeccable 读取配置后误报很少自动修复的准确率也高。这个项目里它主要帮我抓出了一些手写的 inline style 和少数偏离 scale 的地方。一个用原生 CSS 的老项目接入就麻烦一些。老代码里间距值五花八门第一次 check 出来上千个 warning。我的做法是先排除掉历史遗留的大文件只对新写的组件开启检查逐步推进。这个过程急不得想一次性清理完老项目基本不现实。还有一个用 Vue 的项目模板语法导致 impeccable 对某些动态绑定的样式解析不准。这种情况我就在配置里排除掉那些文件或者用行内注释忽略。工具是死的人是活的遇到解析不了的就绕过别跟工具较劲。最让我意外的是浏览器扩展在跨团队协作里的价值。有次和产品经理讨论一个页面我直接打开扩展把设计问题可视化标注出来沟通效率比对着代码讲高太多了。后来产品同学自己装了一个提需求前先自己检查一遍减少了很多来回。关于 AI 协作流程我现在的习惯是把它固化成一个脚本生成代码后自动跑检测、自动生成修复 prompt、自动调用 AI 修复、再自动验证。整个循环不需要人工干预只有最后 review 的时候才需要人看。这个自动化程度下前端代码的设计规范度能稳定维持在一个不错的水平。最后分享一个配置上的小技巧impeccable 支持从多个配置文件合并规则你可以建一个团队共享的基础配置再在每个项目里覆盖项目特定的规则。这样团队规范和个人项目灵活性都能兼顾。具体做法是在项目配置里用extends字段指向共享配置类似 ESLint 的 extends 机制。这个用法官方文档里提得不多但实际很实用。