1. 项目缘起与核心定位

1.1 一个被名字耽误的效率工具

第一次看到 "impeccable" 这个词，很多人会愣一下——这到底是个什么项目？名字本身是"无可挑剔的、完美的"意思，听起来像是一个设计规范库或者代码质量检测工具。实际上，它瞄准的是一个更具体的痛点：AI coding agents 生成的前端界面，往往能用但不好看。

你让 AI 帮你写一个登录页、一个数据看板、一个设置面板，代码逻辑没问题，功能也跑得通，但出来的东西总有一股"AI 味"——间距随意、配色生硬、层级混乱、响应式一塌糊涂。impeccable 就是冲着这个问题来的。它是一套面向 AI coding agents 的前端设计约束层，通过 CLI 和浏览器扩展两种形态，把"设计品味"这件事变成可执行、可校验、可复现的规则。

说白了，它解决的不是"能不能生成"的问题，而是"生成得好不好看"的问题。适合谁用？三类人：一是天天用 AI 写前端但审美没跟上的独立开发者；二是团队里负责把 AI 产出落地的前端工程师；三是想给自家 AI 工具链加一道"设计质检"环节的技术负责人。

1.2 为什么是 CLI 加浏览器扩展的组合

这个项目的形态选择很有意思。它没有做成一个纯 npm 包，也没有只做一个 Figma 插件，而是 CLI 加浏览器扩展双线并行。背后的逻辑我琢磨了一下，其实是覆盖了 AI 辅助开发的两个关键节点。

CLI 负责的是生成前和生成后的静态校验。你在终端里跑一条命令，它扫描你的组件代码、样式文件，按照内置的设计规则给出评分和修改建议。这一步发生在代码进入浏览器之前，属于"预防性"的。

浏览器扩展负责的是运行时的视觉审查。页面渲染出来之后，扩展直接在真实 DOM 上做标注——哪个元素间距不对、哪个颜色对比度不够、哪个断点布局塌了，全部可视化标出来。这一步是"诊断性"的。

两者配合，形成了一条从代码到视觉的完整质检链路。这个设计思路比单纯做一个 lint 规则集要聪明得多，因为它承认了一个事实：前端设计的很多问题，光看代码是看不出来的，必须看渲染结果。

2. 核心机制拆解：它到底怎么判断"好看"

2.1 设计规则的可执行化

impeccable 的核心资产是一套设计规则库。但注意，它不是那种"建议使用 8px 网格"的软性指南，而是把规则写成了可执行的检查项。我拆过它的规则结构，大致分四类：

• 空间规则：间距是否落在统一的尺度体系上，比如 4/8/12/16/24/32 这种递进，而不是 7px、13px、19px 这种随手写的值。
• 色彩规则：对比度是否达到 WCAG 标准，色相是否在合理范围内，语义色（成功/警告/错误）是否一致。
• 排版规则：字号层级是否清晰，行高是否与字号匹配，字重使用是否克制。
• 布局规则：对齐方式是否统一，响应式断点是否有明确策略，溢出和换行是否处理妥当。

每一类规则都有对应的检测逻辑和严重等级。这个分级很重要，因为不是所有问题都值得立刻修——有些是"必须改"，有些是"建议改"，有些只是"提一嘴"。

2.2 与 AI coding agents 的协作方式

这里要讲清楚一个关键点：impeccable 不是替代 AI coding agents，而是给它们套上一层"设计护栏"。实际工作流是这样的：

1. 你用 codex cli 或者类似的 AI 编码工具生成一个组件。
2. 在提交之前，跑一遍 impeccable 的 CLI 检查。
3. CLI 输出一份问题清单，附带具体的修改建议。
4. 你把这份清单喂回给 AI agent，让它按建议修正。
5. 修正后再跑一遍，直到通过。
6. 最后用浏览器扩展做一次视觉确认。

这个闭环的价值在于，它把"设计品味"这个很虚的东西，变成了 AI 能理解的、结构化的反馈信号。AI 不怕规则多，怕的是规则模糊。impeccable 做的就是把模糊变清晰。

提示：不要指望一次就通过。实测下来，第一轮通常能暴露 15 到 30 个问题，第二轮降到个位数，第三轮基本干净。这个收敛速度是可以接受的。

2.3 规则的可配置性

不同项目对设计的容忍度不一样。一个内部工具后台和一个面向消费者的落地页，标准肯定不同。impeccable 允许你通过配置文件调整规则的严格程度，甚至可以关闭某些规则。

配置文件通常是一个 JSON 或 YAML 文件，放在项目根目录。你可以针对不同目录设置不同规则——比如components/ui/下严格执行，pages/experimental/下宽松处理。这个粒度控制在实际项目里非常必要，否则要么规则太松没效果，要么太严导致大量误报。

3. 实操落地：从安装到跑通第一条检查

3.1 环境准备与安装

impeccable 的 CLI 是基于 Node.js 的，所以第一步是确认你的 Node 环境。建议用 Node 18 或以上版本，低版本可能会遇到依赖兼容问题。

node -v npm -v

如果版本没问题，直接全局安装或者用 npx 临时调用：

npm install -g impeccable-cli

或者不安装，直接用：

npx impeccable-cli init

这里有个经验：如果你所在网络环境下载 npm 包比较慢，可以配置国内镜像源。但注意，镜像源的选择要看你实际能访问哪个，不要盲目抄别人的配置。

安装完成后，在项目根目录跑初始化命令：

impeccable init

这个命令会生成一个默认配置文件impeccable.config.json，里面包含规则集、忽略路径、严重等级阈值等。我建议第一次先不要改，用默认配置跑一遍看看基线情况。

3.2 第一次扫描与结果解读

初始化之后，直接对目标目录做扫描：

impeccable scan ./src/components

输出结果通常是一个表格，列出文件路径、问题类型、严重等级、具体位置和建议修改。我拿一个真实的登录表单组件举例，第一次扫描出来的典型问题包括：

这份清单的价值在于，它把"感觉哪里不对"变成了"具体哪里不对、怎么改"。你拿着这份清单去改代码，或者直接丢给 AI agent 让它改，效率比反复描述"再好看一点"高太多了。

3.3 浏览器扩展的安装与使用

CLI 管代码层面，浏览器扩展管视觉层面。扩展的安装方式取决于你用的浏览器，通常是在扩展商店搜索安装，或者加载开发者模式下的解压包。

装好之后，打开你的开发页面，点击扩展图标，它会自动扫描当前页面的渲染结果。扫描完成后，页面上会叠加一层标注：

• 红色框：严重问题，必须修。
• 黄色框：中等问题，建议修。
• 蓝色框：轻微问题，可选修。

点击任意标注，会弹出详细信息，包括当前值、建议值、以及为什么这么建议。这个"为什么"很重要，它让你在修改的同时理解设计原则，而不是机械地照做。

注意：扩展扫描的是运行时 DOM，所以如果你的页面有动态内容或者懒加载，建议等页面完全稳定后再扫描，否则可能扫到中间状态导致误报。

4. 与主流 AI 编码工具链的配合

4.1 在 codex cli 工作流中嵌入检查

codex cli 这类工具的特点是可以在终端里直接完成代码生成、修改、运行。把 impeccable 嵌进去的方式很简单，就是在生成步骤之后加一条检查命令。

我自己的习惯是写一个简单的 shell 脚本：

#!/bin/bash # generate-and-check.sh codex generate --prompt "$1" --output ./src/components impeccable scan ./src/components --format json > /tmp/impeccable-report.json if [ $? -ne 0 ]; then echo "发现问题，正在生成修正建议..." impeccable suggest --input /tmp/impeccable-report.json fi

这个脚本跑完，你会得到一份修正建议，可以直接复制回 codex cli 让它继续改。实测下来，两到三轮就能收敛到一个可接受的状态。

4.2 与 openspec cli 的规范协同

openspec cli 这类工具管的是"功能规格"，impeccable 管的是"设计规格"。两者其实是互补的。你可以在 openspec 的规格文件里引用 impeccable 的规则集，让功能验收和设计验收在同一个流程里完成。

具体做法是在规格文件的验收标准部分加一条：

设计验收：所有 UI 组件必须通过 impeccable scan，严重等级为高的问题数量为 0。

这样就把设计质量变成了一个可量化的验收指标，而不是靠人肉 review 拍脑袋。

4.3 处理 AI 生成代码的常见设计债

AI coding agents 生成的前端代码，有几个高频设计债，impeccable 基本都能抓到：

• 魔法数字泛滥：padding: 13px、margin: 7px 这种，AI 很喜欢随手写。规则会强制你归到统一尺度。
• 颜色硬编码：到处写 #3b82f6，而不是用设计 token。规则会提示你提取变量。
• 响应式缺失：只写了一套桌面布局，没有断点处理。规则会标记缺少媒体查询的组件。
• 状态样式不全：只写了默认态，hover、focus、disabled、loading 全没有。规则会检查交互状态覆盖度。

这些债如果不在生成阶段就还掉，后期累积起来改起来非常痛苦。impeccable 的价值就是在源头做拦截。

5. 常见问题与排查实录

5.1 扫描结果误报太多怎么办

这是新手最容易遇到的问题。一跑扫描，几百个问题，看着就头大。原因通常有两个：一是规则太严，二是忽略路径没配好。

解决办法分三步：第一，先看严重等级为高的有多少，只处理这部分；第二，把第三方组件库、自动生成的代码、测试文件加到忽略列表；第三，根据项目实际情况调整规则阈值，比如内部工具可以把对比度要求从 AAA 降到 AA。

配置文件里调整忽略路径的写法：

{ "ignore": [ "**/node_modules/**", "**/*.test.*", "**/vendor/**", "src/legacy/**" ], "severityThreshold": "high" }

5.2 浏览器扩展扫不到内容

常见原因有三个：页面在 iframe 里、扩展没有当前页面的权限、页面用了 Shadow DOM 导致选择器穿透失败。

排查顺序：先确认扩展图标是否是激活状态，再看浏览器控制台有没有扩展报错，最后检查页面结构是否用了 Shadow DOM。如果是 Shadow DOM，目前多数扩展的支持有限，可以先用 CLI 做代码层面的检查，视觉层面手动确认。

5.3 与现有 lint 工具冲突

impeccable 和 ESLint、Stylelint 这类工具在职责上有重叠，但侧重点不同。ESLint 管代码质量，Stylelint 管 CSS 语法，impeccable 管设计一致性。三者可以共存，但要注意规则不要互相打架。

比如 Stylelint 可能要求属性排序，impeccable 可能要求间距统一，这两个不冲突。但如果 Stylelint 配置了某个颜色规则，impeccable 也配了颜色规则，就可能出现一个让改一个不让改的情况。解决办法是明确分工：语法层面交给 Stylelint，设计层面交给 impeccable。

5.4 问题速查表

提示：每次调整配置后，建议先在一个小目录上试跑，确认效果再全量应用。全量跑一次大项目可能要几十秒到几分钟，反复试错很浪费时间。

6. 我踩过的坑与实操心得

6.1 不要追求一次清零

刚开始用的时候，我有强迫症，非要把所有问题都修完。结果一个下午就耗在一个组件上，效率极低。后来想明白了：严重等级为高的问题必须清零，中的看情况，低的可以攒着批量处理。设计质量是迭代出来的，不是一次到位。

6.2 规则要跟着项目走

默认规则集是通用型的，但每个项目都有自己的设计语言。用了一段时间后，我把项目实际使用的间距尺度、颜色 token、字号层级提取出来，写进了自定义规则。这样扫描结果更贴合项目实际，误报率大幅下降。

6.3 把检查嵌进 CI

人是有惰性的，靠自觉跑检查不现实。后来我把 impeccable scan 加进了 CI 流程，严重等级为高的问题数量超过阈值就直接 fail。这样一来，设计质量变成了硬性门槛，而不是可选项。团队里的 AI 生成代码质量肉眼可见地提升了。

6.4 浏览器扩展别一直开着

扩展在扫描时会遍历 DOM，对复杂页面有性能影响。我的习惯是开发阶段按需开启，确认完就关掉。长期开着可能导致页面卡顿，尤其是那种组件数量上千的后台系统。

6.5 修正建议要理解后再用

impeccable 给出的建议是基于通用设计原则的，但你的项目可能有特殊场景。比如它建议某个文字对比度提到 4.5:1，但你的品牌色就是达不到，这时候要么调整品牌色，要么接受这个偏差并记录原因。不要无脑照做，理解背后的逻辑更重要。

7. 后续可以怎么扩展

这套工具链跑通之后，能扩展的方向不少。一个是把规则集做成团队共享的 preset，新项目直接继承，不用每次重新配。另一个是把扫描报告做成可视化看板，追踪设计质量随时间的变化趋势。再进一步，可以把 impeccable 的规则输出接入 AI agent 的反馈循环，让它自动修正而不是人工中转。

我个人最看好的方向是设计 token 的自动提取与同步。现在很多项目的设计 token 散落在 Figma、代码、文档三个地方，经常对不上。如果 impeccable 能在扫描的同时反向生成一份 token 清单，那对设计系统的维护会非常有帮助。这个我还在摸索，等跑通了再单独写一篇。