impeccable：为AI编程助手注入设计约束的前端工作流工具

1. 项目缘起与核心定位

1.1 一个被名字耽误的实用工具

第一次看到 "impeccable" 这个词，很多人会愣一下——这到底是个什么项目？名字本身是"无可挑剔的、完美的"意思，听起来像是一个设计规范文档或者某个高冷的前端框架。但实际上，它是一套围绕AI coding agents构建的前端设计工作流工具，核心形态是一个CLI加上一个browser extension。说白了，它解决的是一个非常具体的问题：当你用 AI 编程助手写前端代码时，怎么让产出的界面不像是"AI 随手糊出来的"，而是真正达到可交付水准。

我自己用 AI 写前端有大半年了，踩过的坑基本能写一本书。最典型的就是：你让 AI 生成一个登录页，它给你一个能跑的页面，但配色是默认蓝、间距是随缘的、响应式是碰运气的。你反复调 prompt，它反复给你差不多的东西。impeccable 这个项目就是冲着这个痛点来的——它不试图替代 AI coding agent，而是给 agent 套上一层"设计约束层"，让输出结果在视觉和结构上更接近一个靠谱前端工程师的手笔。

适合谁来用？三类人最受益：一是独立开发者，没有专职设计师但需要拿得出手的界面；二是前端工程师，想用 AI 提效但不想每次都手动擦屁股；三是产品经理或创业者，需要快速验证想法但不想在 UI 上丢分。如果你完全不用 AI 写代码，这个项目的价值会打折扣，但它的设计约束思路仍然值得借鉴。

1.2 它到底解决了什么问题

要理解 impeccable 的价值，得先理解 AI 写前端的三个"原罪"。

第一个是设计系统缺失。AI agent 每次生成代码都是"从零开始"，它不知道你的项目用的是什么间距体系、什么色板、什么圆角规范。结果就是同一个项目里，这个页面 padding 是 16px，那个页面是 20px，按钮圆角一会儿 4px 一会儿 8px。人眼能感觉到"不对劲"，但说不出哪里不对。

第二个是响应式靠猜。AI 生成的布局在桌面端看着还行，一到移动端就崩。因为它没有真正的断点意识，只是机械地加几个 media query，断点值还经常是拍脑袋定的。

第三个是可访问性被忽略。对比度不够、焦点状态缺失、语义化标签乱用，这些问题 AI 基本不会主动处理，除非你明确要求。

impeccable 的思路是：把这些"隐性规范"显性化，通过 CLI 注入到 AI agent 的工作流里，再通过 browser extension 做实时校验。它不是一个大而全的框架，而是一个"约束层"和"检查层"的组合。这个定位很聪明——它不跟 AI agent 竞争，而是做 agent 的"设计副驾驶"。

2. 核心架构与设计思路拆解

2.1 CLI 与 Browser Extension 的分工逻辑

impeccable 把功能拆成 CLI 和 browser extension 两块，这个拆分不是随意的，背后有明确的分工逻辑。

CLI 负责"事前约束"。在你让 AI agent 生成代码之前，CLI 会做几件事：读取项目里已有的设计 token（比如从 tailwind config 或者 CSS 变量里提取）、生成一份"设计上下文"文件、把这个上下文注入到 agent 的 prompt 里。这样 agent 在生成代码时，就已经知道你的项目用的是什么规范，而不是凭空发挥。

Browser extension 负责"事后校验"。代码生成完了、页面跑起来了，extension 会在浏览器里实时检查：间距是否落在你的体系内、颜色是否用了色板里的值、对比度是否达标、焦点状态是否存在。它把这些检查结果以可视化的方式叠加在页面上，让你一眼看出哪里"跑偏"了。

这个"事前+事后"的组合，比单纯做一个 lint 工具要实用得多。因为前端设计的问题，很多是"生成时就已经错了"，事后 lint 只能告诉你错了，不能防止错误发生。impeccable 把约束前置，从源头上减少返工。

2.2 为什么选择 CLI 作为主要交互形态

现在很多工具都往 GUI 走，impeccable 却坚持 CLI 优先，这个选择值得说道说道。

CLI 的核心优势是可组合性。你可以把 impeccable 的命令嵌到 npm scripts 里、嵌到 CI 流程里、嵌到 git hooks 里。比如你可以在 pre-commit 钩子里跑一次设计规范检查，不达标就不让提交。这种"融入现有工作流"的能力，GUI 工具很难做到。

另一个优势是对 AI agent 友好。现在的 AI coding agent，无论是哪家的，本质上都是在终端里工作的。它们读文件、跑命令、看输出。CLI 工具天然就是 agent 的"母语"。impeccable 把自己做成 CLI，等于让 agent 可以直接调用它、读取它的输出、根据输出调整自己的行为。这是一个很聪明的"借力"策略。

当然 CLI 也有代价——学习曲线。你得记命令、记参数。但 impeccable 的命令设计还算克制，核心命令就那么几个，用几次就熟了。而且它提供了--help和交互式引导，新手不至于卡在第一步。

2.3 设计 token 的提取与注入机制

这是 impeccable 最核心的技术点，也是最值得细说的部分。

设计 token 是什么？简单说就是你的项目里那些"可复用的设计决策"——颜色、间距、字号、圆角、阴影等等。一个规范的项目，这些值应该是集中管理的，而不是散落在各个 CSS 文件里。

impeccable 的 CLI 会扫描你的项目，从几个常见来源提取 token：Tailwind 配置文件、CSS 自定义属性（--color-primary这种）、SCSS 变量文件、甚至 Figma 导出的 token JSON。提取完之后，它会生成一份结构化的"设计上下文"，格式大概是这样的：

{ "spacing": { "scale": [4, 8, 12, 16, 24, 32, 48, 64], "base": 4 }, "colors": { "primary": "#2563eb", "surface": "#ffffff", "text": "#1f2937" }, "radius": { "sm": 4, "md": 8, "lg": 16 } }

这份上下文会被注入到 AI agent 的 prompt 里。注入的方式有两种：一种是直接拼接到 system prompt 里，另一种是生成一个.impeccable/context.md文件，让 agent 自己去读。后者更灵活，因为 agent 可以按需读取，不占用宝贵的 context window。

提示：token 提取的准确性直接决定了后续所有环节的效果。如果你的项目 token 管理很乱，建议先花半小时整理一下，再跑 impeccable。磨刀不误砍柴工。

3. 实操流程与关键环节实现

3.1 环境准备与安装

impeccable 的安装本身不复杂，但有几个前置条件需要注意。

首先你需要 Node.js 环境，建议 18 以上版本。如果你用的是比较老的 Node，可能会遇到依赖安装失败的问题。检查版本：

node -v npm -v

然后安装 impeccable CLI。它发布在 npm 上，直接全局安装：

npm install -g impeccable-cli

安装完成后验证一下：

impeccable --version

如果这一步报错，大概率是权限问题。在 macOS 或 Linux 上，可能需要加sudo，但更好的做法是配置 npm 的全局目录，避免用 sudo。Windows 用户如果遇到路径问题，检查一下 npm 的 prefix 配置。

Browser extension 的安装走各自浏览器的扩展商店，搜索 "impeccable" 即可。安装后在扩展栏能看到图标，点击可以开关校验功能。

注意：CLI 和 extension 需要配合使用，但它们是独立安装的。只装 CLI 不装 extension，你就只能做"事前约束"，没法做"事后校验"。建议两个都装上。

3.2 初始化项目与 token 提取

进入你的项目根目录，跑初始化命令：

impeccable init

这个命令会做几件事：创建.impeccable/目录、扫描项目提取 token、生成默认配置文件。扫描过程大概几秒钟，取决于项目大小。

初始化完成后，你会看到.impeccable/目录下有几个文件：

• config.json：主配置文件，控制各种行为
• context.md：提取出的设计上下文，给 AI agent 读的
• tokens.json：结构化的 token 数据

打开tokens.json检查一下提取结果。如果发现某些 token 没被识别，可以手动补充。比如你的项目用了自定义的 CSS 变量命名，impeccable 可能认不出来，这时候在config.json里加一条映射规则就行。

{ "tokenSources": [ { "type": "css-vars", "pattern": "--ds-*" }, { "type": "tailwind", "path": "./tailwind.config.js" } ] }

这里的pattern是 glob 风格的通配符，--ds-*表示匹配所有以--ds-开头的 CSS 变量。这个灵活性很重要，因为不同项目的命名习惯差异很大。

3.3 与 AI coding agent 的对接

这是整个流程里最需要"手感"的一步。impeccable 本身不绑定任何特定的 AI agent，它通过生成上下文文件来影响 agent 的行为。你需要做的是：在给 agent 的指令里，明确让它参考.impeccable/context.md。

比如你用的是某个终端里的 AI coding agent，可以这样下指令：

请参考 .impeccable/context.md 中的设计规范， 为我的项目生成一个用户设置页面。 使用 context 中定义的间距体系和色板， 不要引入新的颜色值。

关键在于"不要引入新的颜色值"这句话。AI agent 有个坏习惯，就是喜欢"发挥创意"，给你加一些它觉得好看的颜色。明确禁止之后，它就会老老实实用你的色板。

如果你用的 agent 支持 system prompt 或者项目级指令文件（比如某些 agent 会读AGENTS.md或类似文件），可以把 impeccable 的上下文直接写进去，这样就不用每次都在 prompt 里重复了。

实测下来，加了这层约束之后，AI 生成的前端代码"返工率"能降一半以上。以前生成一个页面要来回改五六轮，现在两三轮就能定稿。

3.4 Browser Extension 的实时校验

代码生成完、页面跑起来之后，打开 browser extension 的校验开关。它会在页面上叠加一层可视化标记：

• 间距不在体系内的元素，会被标上橙色边框
• 颜色不在色板内的元素，会被标上红色边框
• 对比度不达标的文字，会被标上黄色高亮
• 缺少焦点状态的交互元素，会被标上虚线框

这些标记是实时的，你改代码、页面热更新，标记会跟着变。这个反馈循环非常快，比手动检查效率高太多。

Extension 还有一个"快照"功能，可以把当前页面的所有问题导出成一份报告。这份报告可以直接丢给 AI agent，让它按报告修复。这就形成了一个闭环：生成 → 校验 → 修复 → 再校验。

提示：不要追求"零标记"。有些标记是误报，有些是业务上可以接受的偏差。把精力放在那些真正影响体验的问题上，比如对比度不足、焦点状态缺失，这些是硬伤。

4. 常见问题与排查技巧实录

4.1 安装与初始化阶段的坑

问题一：impeccable init卡住不动。这通常是因为项目太大，扫描 token 时遍历了node_modules。解决办法是在config.json里配置忽略目录：

{ "ignore": ["node_modules", "dist", ".next", "coverage"] }

问题二：token 提取结果为空。检查你的项目是不是用了非标准的设计 token 管理方式。比如有些项目把颜色写在 JS 对象里，impeccable 默认不认。这时候需要自定义提取规则，或者手动维护tokens.json。

问题三：extension 装了但页面上没反应。先确认扩展是否在当前页面启用了（有些扩展默认只在特定域名下工作）。然后检查页面是否有 CSP（内容安全策略）限制，某些严格的 CSP 会阻止扩展注入脚本。

4.2 与 AI agent 配合时的典型问题

问题：agent 无视上下文，还是乱用颜色。这通常是因为上下文注入的位置不对。如果你把上下文放在 prompt 末尾，agent 可能会"忘记"。建议放在开头，或者用 agent 支持的项目级指令文件。另外，指令要具体，不要说"遵循设计规范"，要说"所有颜色必须从 context.md 的 colors 字段中选取"。

问题：agent 生成的代码结构对了，但视觉上还是"AI 味"。这往往是因为上下文里缺少"布局模式"的信息。impeccable 默认只提取 token，不提取布局习惯。你可以在context.md里手动补充一些布局约定，比如"卡片间距统一用 24px"、"表单标签在输入框上方"。

问题：不同 agent 表现差异大。这是正常的。不同 agent 对上下文的理解能力不同，有的 agent 更"听话"，有的更"自主"。建议固定用一个 agent，摸清它的脾气，再针对性调整上下文。

4.3 校验阶段的误报处理

Browser extension 的校验规则是通用的，不一定完全贴合你的项目。比如你的品牌色对比度就是偏低，但这是设计决策，不是 bug。这时候可以在config.json里配置例外：

{ "rules": { "contrast": { "exclude": [".brand-text", ".hero-title"] } } }

排除规则要慎用，别把真正的问题也排除了。我的经验是：先看一遍所有标记，把确认是误报的加进排除列表，剩下的老老实实修。

4.4 常见问题速查表

5. 进阶用法与个人实践心得

5.1 把 impeccable 嵌进 CI 流程

如果你有 CI 流程，可以在里面加一步设计规范检查。思路是：用 impeccable 的 CLI 跑一次校验，把结果输出成 JSON，然后写个脚本判断是否有"严重问题"。有的话就让 CI 失败。

impeccable check --format json --output report.json

然后写个简单的 Node 脚本解析report.json，统计严重问题的数量。这个做法适合团队协作场景，能防止有人提交明显违反设计规范的代码。

不过要注意，CI 检查应该是"兜底"，不是"主力"。主力还是开发时的实时校验。CI 检查太严格会拖慢流程，太宽松又没意义。建议只拦截"硬伤"级别的问题。

5.2 多项目共享设计上下文

如果你同时维护多个项目，且它们共享同一套设计系统，可以把 impeccable 的上下文抽出来做成一个共享包。做法是：把context.md和tokens.json放到一个独立的 npm 包里，各个项目安装这个包，然后在config.json里指向它。

这样设计系统更新时，只需要更新共享包，所有项目都能同步。这个模式适合中大型团队，小项目没必要搞这么复杂。

5.3 我踩过的几个坑

第一个坑是过度依赖自动提取。一开始我完全信任 impeccable 的 token 提取，结果它把我项目里一些"历史遗留"的乱七八糟的颜色也提取进去了，导致上下文里色板特别大，agent 反而不知道该用哪个。后来我手动精简了色板，只保留真正在用的颜色，效果立刻好了。

第二个坑是校验规则开太满。刚开始我把所有校验规则都打开，页面上密密麻麻全是标记，看得人焦虑。后来我只保留对比度和焦点状态两个核心规则，其他都关了。少即是多。

第三个坑是指望它解决所有问题。impeccable 能解决"规范一致性"问题，但解决不了"设计品味"问题。如果你的设计本身就不行，它只能保证你"一致地不行"。工具是放大器，不是替代品。

5.4 后续可以怎么扩展

这个项目本身还在演进，我关注到几个有意思的方向。一是与设计工具的联动，比如从 Figma 直接同步 token，省去手动维护。二是更智能的布局建议，不只是校验 token，还能根据内容类型推荐布局模式。三是多 agent 协同，一个 agent 生成、一个 agent 校验、一个 agent 修复，形成流水线。

如果你现在就想动手扩展，我建议从"自定义校验规则"入手。impeccable 的规则系统是开放的，你可以写自己的规则插件。比如加一条"所有按钮必须有 hover 状态"的规则，这对提升交互质量很有帮助。

最后分享一个小技巧：把 impeccable 的上下文文件和你的项目 README 放在一起，新加入的开发者（或者新的 AI agent）一进来就能看到设计规范。这个习惯能省下大量沟通成本。