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.json

JSON 报告的结构大致是这样：

{ "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 浏览器扩展的安装与使用

浏览器扩展的安装方式取决于你用的浏览器。装好之后，在任意页面点击扩展图标，它会：

1. 扫描当前页面的计算样式（computed styles）
2. 在页面上用彩色边框标注有问题的元素
3. 侧边栏显示问题列表，点击可定位到元素
4. 支持导出报告

这个功能在做设计审查时特别好用。我经常用它来检查第三方页面或者线上环境，看看别人的设计系统是怎么落地的（学习角度），或者检查自己项目的线上表现。

扩展的一个隐藏用法：它可以检测动态渲染后的样式，而 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.json

diff命令会显示修复了多少问题、还剩多少。一般两轮迭代就能把 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: 1rem，CLI 看到的是1rem，扩展看到的是计算后的16px。如果配置里 scale 只认 px，CLI 可能报 warning 而扩展不报，或者反过来。

解决办法：配置里同时支持多种单位，或者在 CLI 配置里开启单位转换。impeccable 较新版本支持在配置里指定rootFontSize，这样 rem 和 px 能互相换算，两边结果就一致了。

5.5 常见问题速查表

5.6 几个独家避坑技巧

技巧一：把 impeccable 加进 git pre-commit hook。只对 staged 文件跑 check，error 级别阻断提交，warning 级别只提示。这样能防止新的设计问题进入代码库。

# .husky/pre-commit 示例 npx impeccable check --staged --severity error

技巧二：为不同环境准备不同配置。开发环境用宽松配置（只看 error），CI 环境用严格配置（error + warning）。通过--config参数切换。

技巧三：定期导出报告做趋势分析。把每次 CI 的 report.json 存档，用脚本统计 warning 数量的变化趋势。如果某段时间 warning 激增，说明有新代码引入了设计问题，可以及时干预。

技巧四：用 impeccable 的输出训练团队规范。把常见的 warning 类型整理成团队的设计规范文档，比干巴巴地讲"要用 4px 网格"有效得多，因为每条规则都有实际代码案例支撑。

6. 工具选型与生态位分析

6.1 和同类工具的对比

市面上做前端设计检查的工具不多，impeccable 的定位比较独特。我把它和几个相关工具做个对比：

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 机制。这个用法官方文档里提得不多，但实际很实用。