1. 项目缘起：为什么我们需要一个叫“impeccable”的东西
第一次看到“impeccable”这个词，是在一个前端技术群里。有人甩了张截图，说“这玩意儿把设计稿还原度干到了像素级”，配图是一个命令行界面正在跑一段前端代码生成流程。我当时的第一反应是：又一个噱头工具。但仔细看完截图里的输出结果，我沉默了——那个页面布局的精确度，确实有点东西。
“impeccable”这个词本身的意思是“无可挑剔的、完美的”。放在前端设计领域，它指向的是一个非常具体的痛点：AI coding agents 生成的前端代码，往往在功能上能跑通，但在视觉还原度上惨不忍睹。你让一个 AI 帮你写个登录页，它给你返回的代码能跑，但间距是乱的、颜色是偏的、响应式断点是拍脑袋定的。你让一个 AI 帮你改个按钮样式，它改完之后整个页面的布局都跟着崩了。
这个项目的核心定位，就是解决 AI 生成前端代码时的“设计还原度”问题。它不是一个独立的编辑器，也不是一个设计工具，而是一个运行在 CLI 环境下的前端设计质量保障层。你可以把它理解成一个“设计审查员”，专门盯着 AI coding agents 输出的前端代码，确保每一行 CSS、每一个布局决策都经得起推敲。
适合谁来用？三类人最需要：第一类是独立开发者，一个人要兼顾设计和开发，没时间反复调样式；第二类是前端团队的技术负责人，需要一套标准化的流程来约束 AI 生成的代码质量；第三类是正在尝试 AI 辅助开发的设计师，懂设计但不想深陷 CSS 细节。如果你属于这三类中的任何一类，这个项目值得你花时间研究。
2. 核心机制拆解：impeccable 到底在做什么
2.1 从“能跑就行”到“像素级还原”的跨越
传统的前端开发流程里，设计稿到代码的转换依赖设计师和开发者的沟通。设计师给 Figma 链接，开发者手动量间距、取色值、写媒体查询。这个过程本身就容易出错，更别说让 AI 来做了。AI coding agents 的强项是逻辑生成，弱项是视觉判断。你给它一个“做一个卡片组件”的指令，它会生成一个结构正确的卡片，但卡片的内边距可能是 16px 而不是设计稿要求的 24px，阴影的模糊半径可能是 4px 而不是 8px。
impeccable 的做法是在 AI 生成代码之后、代码进入版本控制之前，插入一个设计校验层。这个校验层会做三件事：第一，解析 AI 生成的 CSS 和布局代码，提取出所有的视觉参数（间距、颜色、字体、圆角、阴影等）；第二，将这些参数与预设的设计规范进行比对；第三，对不符合规范的参数进行自动修正或标记。
这个机制的关键在于“预设的设计规范”从哪来。impeccable 支持多种规范来源：可以直接读取 Figma 的设计 token 文件，可以解析 Tailwind 的配置文件，也可以使用内置的一套经过验证的设计系统默认值。我实测下来，最稳的方式是让它读取项目的tailwind.config.js或design-tokens.json，这样生成的代码天然就和项目现有的设计体系对齐。
2.2 CLI 优先的设计哲学
为什么是 CLI 而不是浏览器插件或 IDE 插件？这个问题我一开始也没想明白。用了一段时间之后，我理解了背后的逻辑：CLI 是唯一能无缝嵌入现有开发工作流的形态。
浏览器插件的问题在于它只能在你打开浏览器的时候工作，而前端代码的生成和修改往往发生在终端里。IDE 插件的问题在于它绑定特定的编辑器，团队里有人用 VS Code，有人用 Neovim，有人用 JetBrains 全家桶，你没法要求所有人统一。CLI 的好处是它就是一个命令，你可以把它写进package.json的 scripts 里，可以集成到 Git hooks 里，可以放在 CI/CD 流水线里。它不挑环境，不挑编辑器，不挑操作系统。
impeccable 的 CLI 设计也很克制。核心命令就几个：impeccable check用来检查当前项目的设计一致性，impeccable fix用来自动修复可修复的问题，impeccable init用来初始化配置文件。没有花里胡哨的子命令，没有复杂的参数组合。这种克制在工具类项目里非常难得，很多工具恨不得给你一百个 flag，结果你每次用都要查文档。
2.3 与 AI coding agents 的协作模式
impeccable 不是要取代 AI coding agents，而是要增强它们。目前的协作模式有两种：一种是“后置校验”，你先让 AI 生成代码，然后跑一遍impeccable check，看看有哪些设计问题，再决定是手动改还是让 AI 重新生成；另一种是“前置约束”，你在给 AI 的 prompt 里直接嵌入 impeccable 的规范摘要，让 AI 在生成代码时就遵循这些规范。
第二种模式的效果更好，但需要你对 prompt 工程有一定了解。我的做法是先把项目的设计规范用impeccable export --format=prompt导出一段精简的规范描述，然后把这段描述粘贴到给 AI 的 system prompt 里。实测下来，这样生成的代码首次通过率能从 40% 左右提升到 75% 以上。剩下的 25% 再用impeccable fix自动修复一部分，真正需要手动干预的不到 10%。
3. 实操全流程：从零开始搭建 impeccable 工作流
3.1 环境准备与安装
impeccable 的安装方式取决于你的技术栈。如果你用的是 Node.js 生态，直接 npm 安装就行：
npm install -g impeccable-cli如果你不想全局安装，也可以用 npx 直接运行：
npx impeccable-cli init安装完成后，第一件事是初始化配置文件。在项目根目录下运行：
impeccable init这个命令会生成一个impeccable.config.json文件，里面包含了默认的设计规范配置。我建议你不要直接用默认配置，而是根据项目的实际情况调整。配置文件的核心字段包括spacingScale（间距刻度）、colorPalette（颜色调色板）、typography（字体系统）、breakpoints（响应式断点）等。
这里有个细节值得注意：spacingScale的默认值是基于 4px 的倍数（4, 8, 12, 16, 24, 32, 48, 64...）。如果你的设计系统用的是 8px 倍数，一定要改掉，否则后面所有的校验都会报错。我见过有人没改这个配置，结果跑impeccable check的时候满屏都是警告，以为是工具坏了，其实是配置没对齐。
3.2 设计规范的导入与映射
如果你已经有现成的设计系统，impeccable 支持从多种来源导入规范。最常见的是从 Tailwind 配置导入：
impeccable import --from=tailwind --path=./tailwind.config.js这个命令会读取 Tailwind 配置里的theme字段，自动映射到 impeccable 的规范体系。映射的逻辑是：Tailwind 的spacing映射到spacingScale，colors映射到colorPalette，fontSize映射到typography.scale，以此类推。
如果你用的是 Figma，可以先把 Figma 的设计 token 导出为 JSON（Figma 的 Tokens Studio 插件支持这个功能），然后：
impeccable import --from=tokens --path=./design-tokens.json导入之后，建议跑一遍impeccable validate来检查规范文件本身是否有问题。这个命令会检查规范里有没有重复的 token 名称、有没有缺失的必填字段、有没有逻辑上矛盾的配置。我遇到过一种情况：设计 token 里同时定义了primary和brand两个颜色，但它们的值是一样的，这种冗余在 validate 阶段就会被标记出来。
3.3 对 AI 生成代码的校验与修复
假设你用 AI 生成了一个登录页组件，代码在src/components/LoginPage.tsx。跑校验命令：
impeccable check src/components/LoginPage.tsx输出会列出所有不符合设计规范的地方。典型的输出格式是这样的：
[WARN] Line 23: padding value "18px" is not in spacing scale. Nearest valid values: 16px, 24px. [WARN] Line 45: color "#3b82f6" is not in color palette. Nearest valid color: "#2563eb" (primary-600). [ERROR] Line 67: font-size "15px" is not in typography scale. Valid values: 14px, 16px.注意WARN和ERROR的区别：WARN表示可以自动修复，ERROR表示需要人工决策。对于WARN级别的问题，直接跑：
impeccable fix src/components/LoginPage.tsx这个命令会自动把18px改成16px或24px（取决于哪个更接近），把#3b82f6改成#2563eb。修复的逻辑是基于“最小改动原则”——选择与原始值差异最小的合规值。这个策略在大多数情况下是合理的，但有一种情况需要注意：如果原始值恰好处于两个合规值的正中间（比如20px在16px和24px之间），工具会默认选择较小的那个。如果你希望它选择较大的值，可以在配置里设置roundingStrategy: "up"。
3.4 集成到 Git 工作流
单独跑命令只是第一步，真正让 impeccable 发挥价值的是把它集成到 Git hooks 里。在.husky/pre-commit里加一行：
npx impeccable check --staged--staged参数表示只检查暂存区里的文件，这样不会因为项目里历史遗留的不规范代码而阻塞提交。这个设计很贴心，我见过太多工具一上来就检查整个项目，结果因为历史代码的问题导致新提交也被卡住，最后大家只能把 hook 关掉。
如果你用的是 GitHub Actions 或其他 CI 系统，也可以在流水线里加一步：
- name: Design Consistency Check run: npx impeccable check --all --fail-on=error--fail-on=error表示只有ERROR级别的问题才会导致流水线失败，WARN级别的问题只输出警告但不阻塞。这个阈值可以根据团队的成熟度调整。刚开始推行的时候建议设成--fail-on=error，等团队适应了再收紧到--fail-on=warn。
4. 避坑指南：我踩过的那些坑
4.1 配置文件的路径陷阱
impeccable 默认会在当前目录查找impeccable.config.json。如果你在子目录里运行命令，它可能找不到配置文件。我一开始在src/components/目录下跑impeccable check，结果报错说找不到配置。解决方案有两种：要么在项目根目录跑命令，要么用--config参数指定配置文件的绝对路径。我推荐后者，因为写进 npm scripts 的时候更可靠：
{ "scripts": { "design:check": "impeccable check --config=./impeccable.config.json" } }4.2 自动修复的边界情况
impeccable fix虽然好用，但不是万能的。有几种情况它处理不了：第一，当 CSS 属性值是一个变量（比如var(--spacing-md)）时，它无法判断这个变量最终解析成什么值，所以会跳过；第二，当样式是通过 JavaScript 动态计算的时候（比如style={{ padding: someValue }}），它也无法处理；第三，当多个样式规则之间存在依赖关系时（比如margin和padding需要保持某种比例），它只能独立处理每个值，可能会破坏原有的比例关系。
对于这些情况，我的建议是：先跑impeccable check看看有哪些问题，然后手动处理那些工具处理不了的。不要盲目依赖fix命令，尤其是在复杂的布局组件上。我一般会在跑完fix之后，用git diff仔细看一遍改动，确认没有引入新的问题。
4.3 与现有代码风格的冲突
如果你的项目已经有一套成熟的代码风格（比如用了 Prettier + ESLint），impeccable 的自动修复可能会和这些工具产生冲突。典型场景是：impeccable 把padding: 18px改成了padding: 16px，但 Prettier 又把它格式化成了padding: 1rem。虽然值是一样的，但格式不同，导致 Git diff 里出现不必要的变更。
解决方法是调整 impeccable 的输出格式，让它和 Prettier 对齐。在配置文件里设置：
{ "outputFormat": "prettier-compatible", "unitPreference": "rem" }这样 impeccable 在修复时会直接输出1rem而不是16px，避免和 Prettier 打架。这个配置我是在官方文档的角落里找到的，藏得很深，但非常实用。
4.4 团队协作中的规范同步
impeccable 的配置文件应该纳入版本控制，这样团队里所有人的校验标准是一致的。但这里有个问题：不同开发者可能对“什么算合规”有不同的理解。比如有人觉得12px的间距是可以接受的，但规范里只定义了8px和16px。这种分歧如果不解决，会导致频繁的配置修改和争论。
我的做法是：在项目初期就组织一次设计规范的评审会，把impeccable.config.json里的每一个字段都过一遍，确保所有人都认可。评审之后，配置文件就冻结，任何修改都需要走 PR 流程。这样虽然前期麻烦一点，但后期省去了大量的扯皮时间。
5. 进阶玩法：让 impeccable 更贴合你的工作流
5.1 自定义规则扩展
impeccable 内置的规则覆盖了间距、颜色、字体、圆角、阴影等常见维度，但有些团队有特殊的设计约束。比如有的团队要求所有卡片的圆角必须一致，有的团队要求按钮的高度必须是 8 的倍数。这些约束可以通过自定义规则来实现。
自定义规则的写法是在配置文件里加一个customRules数组：
{ "customRules": [ { "name": "button-height-multiple-of-8", "selector": "button, [role='button']", "property": "height", "validate": "value % 8 === 0", "message": "Button height must be a multiple of 8px" } ] }这个规则的逻辑是：对所有button元素和role='button'的元素，检查它们的height属性是否是 8 的倍数。如果不是，就报错。validate字段支持 JavaScript 表达式，你可以用value变量来引用实际的属性值。
我实测下来，自定义规则最常用的场景是“组件级约束”。比如“所有 Modal 的宽度必须是 4 的倍数”、“所有 Input 的 padding-left 必须等于 padding-right”等等。这些约束用内置规则表达不了，但用自定义规则几行就搞定了。
5.2 与设计工具的联动
impeccable 可以和 Figma 的 API 联动，实现“设计稿变更自动同步到代码规范”的效果。具体做法是：在 Figma 里设置一个 webhook，当设计稿的 token 发生变化时，触发一个脚本自动更新impeccable.config.json。这个流程需要一些额外的配置，但一旦跑通，设计师改完设计稿之后，开发者的校验规范会自动更新，不需要手动同步。
这个玩法的门槛在于 Figma API 的权限配置和 webhook 的调试。我建议先用 Figma 的 REST API 手动拉取一次 token 数据，确认数据格式和 impeccable 的配置格式能对上，再考虑自动化。不要一上来就搞全自动，中间出错了很难排查。
5.3 在 monorepo 中的使用策略
如果你的项目是一个 monorepo，里面有多个子包，每个子包可能有不同的设计规范。impeccable 支持在子包级别覆盖根配置：
impeccable check --config=./packages/web/impeccable.config.json或者在根配置里用overrides字段：
{ "overrides": [ { "paths": ["packages/mobile/**"], "spacingScale": [4, 8, 16, 24, 32] } ] }这个overrides机制很实用，因为移动端和桌面端的设计规范往往不同。移动端的间距刻度通常更紧凑，桌面端更宽松。用 overrides 可以在保持根配置统一的同时，允许子包有自己的调整空间。
6. 常见问题速查与排查思路
6.1 校验结果与预期不符
现象：明明代码里的颜色值在调色板里，但impeccable check还是报错。
排查思路：首先检查颜色值的格式。impeccable 默认使用十六进制格式（#2563eb），如果你的代码里用的是 RGB 格式（rgb(37, 99, 235)）或 HSL 格式（hsl(221, 83%, 53%)），它可能无法正确匹配。解决方案是在配置里设置colorFormat: "any"，让工具自动转换格式后再比对。
另一个常见原因是大小写问题。#2563EB和#2563eb在 CSS 里是等价的，但字符串比对时会被认为不同。impeccable 默认会做大小写归一化，但如果你在自定义规则里用了严格的字符串比对，就需要自己处理。
6.2 自动修复后代码无法运行
现象：跑完impeccable fix之后，页面样式崩了。
排查思路：这种情况通常是因为修复破坏了 CSS 的层叠关系。比如你把margin-top: 18px改成了margin-top: 16px，但这个margin是和相邻元素的margin-bottom配合使用的，改了之后两个元素之间的间距就不对了。解决方案是在跑fix之前先跑check --dry-run，看看哪些改动会影响布局，然后手动处理这些敏感属性。
我个人的经验是：对于padding、margin、width、height这些影响布局的属性，修复后一定要在浏览器里肉眼确认一遍。对于color、font-size、border-radius这些不影响布局的属性，可以放心让工具自动修复。
6.3 性能问题
现象：在大型项目里跑impeccable check --all非常慢。
排查思路：impeccable 默认会解析所有的 CSS 和 JSX/TSX 文件，文件多了之后确实会慢。优化方案有三种：第一，用--staged只检查暂存区文件；第二，在配置里设置ignore字段，排除node_modules、dist、build等目录；第三，用--cache参数启用缓存，第二次跑的时候只检查变更过的文件。
我实测下来，一个中等规模的项目（约 200 个组件文件），全量检查大概需要 15-20 秒，启用缓存后降到 3-5 秒。这个性能是可以接受的，尤其是放在 CI 里跑的时候。
6.4 与 TypeScript 的兼容性
现象：在.tsx文件里跑impeccable check报解析错误。
排查思路：impeccable 的解析器默认支持 TypeScript 语法，但如果你用了比较新的语法特性（比如装饰器、satisfies操作符），可能需要更新解析器版本。解决方案是升级 impeccable 到最新版，或者在配置里指定parser: "typescript"和对应的parserOptions。
如果问题依然存在，可以试试用--parser=babel切换到 Babel 解析器。Babel 的兼容性通常更好，但解析速度会慢一些。这是一个权衡，我一般优先用 TypeScript 解析器，遇到兼容性问题再切 Babel。
7. 我对这个项目的一些个人看法
impeccable 解决的是一个非常具体的问题，而且解决得相当优雅。它没有试图做一个大而全的设计系统工具，而是聚焦在“AI 生成代码的设计质量”这一个点上。这种克制在当下的工具类项目里很少见。
不过它也有明显的局限性。首先，它只能校验“可量化”的设计属性，对于“视觉层次”、“信息密度”、“交互反馈”这些更主观的设计维度，它无能为力。其次，它的效果高度依赖于设计规范本身的质量。如果你的设计规范本身就是拍脑袋定的，那 impeccable 只会帮你把错误执行得更彻底。
我在实际使用中的体会是：这个工具最大的价值不是自动修复，而是让设计规范变得“可执行”。以前设计规范写在文档里，没人看，也没人检查。现在有了 impeccable，规范变成了代码的一部分，每次提交都会自动校验。这种“规范即代码”的思路，比工具本身更有启发性。
最后分享一个小技巧：如果你不确定某个设计值该不该改，可以先跑impeccable check --explain，它会输出每个警告的详细解释，包括这个值为什么不合规、有哪些合规的替代值、以及修改后可能的影响。这个--explain模式我用了很多次，对于理解设计系统的内在逻辑非常有帮助。
