impeccable：AI生成前端代码的设计质量约束与校验工具

1. 从"impeccable"这个词说起：它到底想解决什么问题

第一次看到"impeccable"这个词被拿来命名一个开发工具，我其实愣了一下。这个词在英文里的意思是"无可挑剔的、完美的"，放在前端开发语境下，它指向的痛点非常明确——AI 写出来的前端代码，往往"能跑但不好看"。

我接触过不少用 AI coding agents 生成页面的场景：你给 Codex CLI 或者类似的命令行智能体丢一句"帮我做一个登录页"，它确实能吐出一堆 HTML、CSS 和 JS，浏览器打开也能显示。但问题在于，生成出来的东西经常是那种"一眼 AI 味"的产物——间距随意、配色撞车、圆角大小不统一、响应式断点乱设、按钮 hover 状态缺失。功能上没毛病，视觉上却让人皱眉。

impeccable 这个项目，本质上就是冲着这个"最后一公里"来的。它不是一个从零写页面的工具，而更像是一个前端设计质量的约束层和校验层，配合 CLI 和浏览器扩展两种形态，让 AI coding agents 产出的界面从"能用"提升到"耐看"。

它适合谁？我梳理了一下，大概三类人最需要它：

• 重度依赖 AI 生成前端代码的独立开发者：你一个人干全栈，UI 靠 AI 出，但你又没有设计师帮你兜底，impeccable 就是你的"审美护栏"。
• 用 Codex CLI、zcode CLI 这类命令行智能体做原型的团队：快速验证想法时，界面质量直接影响演示效果和投资人/客户的观感。
• 想系统学习前端设计规范的前端新人：通过它给出的约束和检查项，反过来理解"什么样的间距、配色、层级才算专业"。

关键词里出现的AI coding agents、frontend design、CLI、browser extension，其实已经把它的定位说得很清楚了：它是嵌在 AI 编码工作流里的一个前端设计质量工具，同时提供命令行和浏览器扩展两种入口。下面我会把它拆开，从设计思路、核心机制、实操流程到踩坑经验，一层层讲透。

2. 整体设计思路：为什么是"约束"而不是"重写"

2.1 前端 AI 生成的核心矛盾

要理解 impeccable 的设计哲学，得先搞清楚 AI 生成前端代码为什么会"丑"。我总结下来有三个根因：

第一，训练数据的平均化倾向。AI 模型见过海量的网页代码，它倾向于输出"最常见"的写法，而"最常见"往往等于"最平庸"。比如它默认给你border-radius: 4px、padding: 16px、#333文字色，这些值单独看没错，但组合起来就是没有设计感。

第二，缺乏全局一致性约束。AI 是逐段生成的，它写第一个卡片时用8px间距，写第二个卡片时可能就用12px了，因为它没有"设计系统"这个概念。人眼对不一致极其敏感，这种细微的错位就是"廉价感"的来源。

第三，缺少状态和边界处理。AI 生成的组件通常只考虑"正常态"，hover、focus、disabled、loading、空状态、错误态经常被忽略。一个按钮点下去没有任何反馈，用户立刻觉得这产品不专业。

impeccable 的思路不是让 AI 重新生成一遍，而是在生成之后施加一层设计约束和校验。这个选择很关键，我后面会讲为什么"约束"比"重写"更靠谱。

2.2 为什么选择 CLI + 浏览器扩展双形态

项目同时提供 CLI 和 browser extension，这个组合不是随便定的，而是对应了开发流程的两个不同阶段。

CLI 形态对应的是"生成时"和"提交前"。你在终端里跑 Codex CLI 或者 zcode CLI 生成代码，impeccable 的 CLI 可以作为一个后处理步骤或者校验步骤介入。它的优势是能进 CI/CD，能批量化，能对着一整个项目目录扫。

浏览器扩展形态对应的是"预览时"和"调试时"。代码跑起来了，你在浏览器里看效果，扩展可以实时标注出哪些元素违反了设计规范——间距不对、对比度不足、层级混乱。这种即时反馈是 CLI 给不了的。

提示：这两种形态不是二选一，而是配合使用。CLI 管"批量体检"，扩展管"实时盯梢"。

我个人的使用习惯是：生成阶段用 CLI 做一次全量校验，改完之后在浏览器里用扩展做最终确认。这个流程跑顺了，前端交付质量能稳定提升一个档次。

2.3 约束层的三个设计原则

impeccable 在约束设计上遵循了三个原则，我觉得这是它区别于普通 linter 的地方：

原则一：约束"关系"而非"绝对值"。它不会硬性规定你必须用16px间距，而是要求你的间距值来自一个统一的尺度体系（比如 4 的倍数）。这样既保证了节奏感，又给了设计自由度。

原则二：约束"完整性"而非"风格"。它不评判你用圆角还是直角，但会检查你的交互元素是否覆盖了必要的状态。风格是主观的，完整性是客观的。

原则三：约束"可访问性"作为底线。对比度、焦点可见性、语义标签这些，属于"不合格就是不合格"的硬指标，impeccable 会强制卡住。

理解了这三条，你就能明白为什么它叫"impeccable"——它追求的不是"惊艳"，而是"挑不出毛病"。这个定位非常务实，因为对绝大多数产品来说，"挑不出毛病"比"惊艳"更重要，也更容易达成。

3. 核心机制拆解：impeccable 到底检查什么

3.1 间距与尺度体系校验

这是 impeccable 最基础也最实用的一块。前端视觉的"高级感"，很大程度上来自间距的节奏统一。

它的做法是：扫描你所有的margin、padding、gap、width、height等尺寸属性，提取出所有数值，然后判断这些值是否落在一个统一的尺度体系上。常见的尺度体系有 4px 基准、8px 基准两种。

举个我实际遇到的例子。AI 生成的一段卡片代码是这样的：

.card { padding: 15px; margin-bottom: 18px; border-radius: 5px; } .card-title { margin-bottom: 11px; }

单看每个值都"差不多"，但 15、18、5、11 这四个数放在一起，就是没有节奏。impeccable 会把这些值标出来，提示你它们不在统一的尺度上。改成 16、16、8、8 之后，视觉上立刻规整了。

注意：尺度体系不是越严格越好。我建议主尺度用 4 的倍数，但允许少量"光学修正"值存在，比如图标对齐用的 1px 或 2px 微调。impeccable 一般会给你一个容忍区间，别死磕。

3.2 颜色与对比度检查

颜色这块，impeccable 主要盯两件事：调色板收敛和对比度达标。

调色板收敛的意思是，一个页面里出现的颜色种类应该可控。AI 生成代码时经常"随手"用颜色，一会儿#3b82f6，一会儿#2563eb，一会儿#1d4ed8，其实都是蓝色系，但用了三个不同的值。人眼看着就是"花"。impeccable 会统计你页面里所有颜色值，如果同类色出现过多变体，就会提示收敛。

对比度检查则是硬指标。正文文字和背景的对比度至少要达到 4.5:1，大号文字至少 3:1。这个标准来自可访问性规范，impeccable 会逐个元素计算对比度，不达标的直接标红。

我实测下来，AI 生成的浅色系界面里，灰色文字配白色背景是最容易翻车的组合。比如#999的文字放在#fff背景上，对比度只有 2.8:1 左右，远不达标。impeccable 一抓一个准。

3.3 交互状态完整性

这块是我认为 impeccable 最有价值的部分。它会检查你的交互元素（按钮、链接、输入框、卡片等）是否定义了完整的状态。

一个合格的按钮，至少要有这些状态：

AI 生成的按钮，十有八九只有默认态和一点点 hover。你想想，一个用户用键盘 Tab 键导航，焦点跑到按钮上却没有任何视觉提示，他根本不知道自己现在在哪。这就是可访问性事故。

impeccable 会把这些缺失的状态列出来，你可以按图索骥地补全。补全之后，界面的"专业度"提升是肉眼可见的。

3.4 层级与语义结构

最后一块是 DOM 层级和语义标签。AI 生成代码时特别喜欢用div堆砌，一个页面里几十个div，语义标签header、nav、main、section、article、footer一个不用。

impeccable 会检查你的结构语义是否合理，标题层级（h1 到 h6）是否跳级，交互元素是否用了正确的标签（按钮用button而不是div加onclick）。

这块的检查看起来"虚"，但影响很实在：语义结构好的页面，屏幕阅读器能正确朗读，搜索引擎能更好理解，键盘导航也更顺畅。这是"挑不出毛病"的重要组成部分。

4. 实操流程：从安装到跑通完整链路

4.1 环境准备与 CLI 安装

impeccable 的 CLI 安装，走的是标准的包管理流程。我以最常见的 Node 生态为例说明，这也是它主流的接入方式。

# 全局安装，方便在任何项目目录调用 npm install -g impeccable-cli # 验证安装是否成功 impeccable --version

如果你不想全局装，也可以在项目里作为开发依赖安装：

npm install --save-dev impeccable-cli # 然后用 npx 调用 npx impeccable --version

提示：全局装和项目内装的区别在于版本管理。团队协作时我强烈建议项目内装，把版本锁在package.json里，避免"我这儿能跑你那儿报错"的经典问题。

安装完之后，第一次运行建议先跑一个impeccable init（如果该版本提供的话），它会在项目根目录生成一个配置文件，通常是impeccable.config.json或类似名字。这个文件里定义了你的尺度体系、颜色规范、检查严格程度等。

4.2 配置文件的关键参数

配置文件是 impeccable 的灵魂，配好了事半功倍。我把自己常用的一套配置拆解给你看：

{ "spacing": { "base": 4, "allowedMultiples": [1, 2, 3, 4, 6, 8, 12, 16], "tolerance": 1 }, "colors": { "maxPaletteSize": 12, "contrastStandard": "AA", "checkLargeText": true }, "states": { "required": ["hover", "focus", "active", "disabled"], "interactiveSelectors": ["button", "a", "input", "select", "textarea"] }, "structure": { "checkHeadingOrder": true, "requireSemanticTags": true, "maxDivDepth": 8 } }

逐个解释一下这些参数背后的考量：

spacing.base设为 4，意味着所有间距都应该是 4 的倍数。allowedMultiples是我允许的倍数集合，注意我没有把 5、7 这种放进去，因为 4 的倍数体系里 20、28 已经能覆盖大部分需求了。tolerance设为 1，是给光学修正留的口子，允许 1px 的偏差。

colors.maxPaletteSize设为 12，是我个人经验值。一个页面的主色、辅助色、中性色加起来，12 种基本够用，超过这个数通常意味着有冗余。contrastStandard用AA是通用标准，如果你的产品面向政府或医疗等对可访问性要求高的场景，可以提到AAA。

states.required里我列了四个必备状态，loading 我没放进去是因为不是所有按钮都需要 loading，但如果你做的是表单提交类按钮，建议手动加上。

structure.maxDivDepth设为 8，是防止嵌套过深。超过 8 层的 div 嵌套，维护起来就是噩梦，而且往往意味着结构设计有问题。

4.3 跑一次完整校验

配置好之后，跑校验的命令通常是这样：

# 校验整个 src 目录 impeccable check ./src # 只校验特定文件 impeccable check ./src/components/Button.tsx # 输出详细报告 impeccable check ./src --verbose # 只显示错误，不显示警告 impeccable check ./src --level error

跑完之后，它会输出一份报告。我拿一个真实项目的输出给你看（做了脱敏）：

impeccable check report ======================== Files scanned: 47 Issues found: 23 [ERROR] src/components/Card.tsx:12 Spacing value 15px is not on the 4px scale. Suggestion: use 16px [ERROR] src/components/Button.tsx:8 Missing focus state for interactive element. Suggestion: add :focus-visible style [WARN] src/pages/Home.tsx:34 Color palette has 15 distinct values, exceeds limit of 12. Suggestion: consolidate similar colors [WARN] src/components/Modal.tsx:56 Heading order jumps from h2 to h4. Suggestion: use h3 or restructure

这份报告的价值在于，它把"感觉哪里不对"变成了"具体哪一行哪个值不对"。你可以直接照着改，改完再跑一遍，直到报告干净。

4.4 浏览器扩展的实时校验

CLI 管的是静态代码，浏览器扩展管的是运行时效果。安装扩展之后，你打开本地开发服务器上的页面，扩展会在页面上叠加一层标注。

它的工作方式我实测下来是这样的：扩展会注入一段脚本，实时扫描 DOM 计算样式，然后把有问题的元素用彩色边框标出来。红色代表错误，黄色代表警告。鼠标悬停在标注上，会弹出具体的说明。

这个实时反馈对调试特别有用。比如你在调一个响应式布局，改完 CSS 刷新页面，扩展立刻告诉你新改的间距是不是又跑偏了。这种"改一下看一眼"的循环，比跑 CLI 再读报告快得多。

注意：浏览器扩展只在你本地开发环境用，别装到生产环境的浏览器里，它注入的脚本会影响页面性能。

5. 和 AI coding agents 的配合：让生成即合规

5.1 把 impeccable 接进 Codex CLI 工作流

这是关键词里codex cli、zcode cli出现的原因——impeccable 真正的价值，是嵌进 AI 编码工作流里。

我的做法是在 Codex CLI 生成代码之后，自动触发一次 impeccable 校验。具体来说，我会写一个简单的 shell 脚本：

#!/bin/bash # generate-and-check.sh # 第一步：用 AI agent 生成组件 codex generate "创建一个用户资料卡片组件" --output ./src/components/ProfileCard.tsx # 第二步：立刻校验 impeccable check ./src/components/ProfileCard.tsx --level error # 第三步：如果有错误，把报告喂回给 AI 让它修 if [ $? -ne 0 ]; then impeccable check ./src/components/ProfileCard.tsx --format json > /tmp/issues.json codex fix --input ./src/components/ProfileCard.tsx --issues /tmp/issues.json fi

这个"生成-校验-修复"的闭环，是我用下来效率最高的模式。AI 负责出初稿，impeccable 负责挑毛病，AI 再根据毛病修。跑两三轮，出来的代码质量比单次生成高一大截。

5.2 把规范写进 AI 的提示词

更进阶的玩法，是把 impeccable 的规范直接写进给 AI 的提示词里，让它"生成时就合规"，减少后期返工。

我常用的提示词模板是这样的：

你是一个前端开发专家。生成组件时请严格遵守以下规范： 1. 所有间距值必须是 4 的倍数（4, 8, 12, 16, 24, 32...） 2. 所有交互元素必须包含 hover、focus-visible、active、disabled 状态 3. 颜色使用不超过 12 种，正文对比度不低于 4.5:1 4. 使用语义化标签，标题层级不跳级 5. div 嵌套不超过 8 层 现在请生成一个用户资料卡片组件。

把规范前置到提示词里，AI 生成的第一版就八九不离十了。impeccable 这时候的角色就从"纠错"变成了"兜底确认"。

5.3 两种模式的取舍

这里有个经验之谈：提示词前置和工具后置，要配合用，不能偏废。

只靠提示词前置，AI 有时候会"阳奉阴违"，嘴上说遵守了，实际生成的还是有偏差，你需要 impeccable 来验证。只靠工具后置，每次都要返工修复，效率低。两者结合，前置减少大部分问题，后置抓住漏网之鱼，这才是最优解。

我实测下来，纯后置模式下，一个中等复杂度的组件平均要修 3 到 4 轮；加上提示词前置之后，平均 1 到 2 轮就干净了。这个效率差异在项目规模大了之后非常明显。

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

6.1 校验报告太多，不知道从哪改起

这是新手最容易遇到的问题。第一次跑 impeccable，报告可能几百条，看着就头大。

我的建议是分级处理，先错误后警告。用--level error先只看错误，把硬伤修完，再放开看警告。错误通常是间距、对比度、状态缺失这类硬指标，警告是调色板、嵌套深度这类软指标。先硬后软，压力小很多。

另外，可以按文件处理，一个文件一个文件地清。别想着一次性全清完，那样容易崩溃。

6.2 尺度体系和我现有的设计系统冲突

有些团队已经有自己的设计系统了，间距用的不是 4 的倍数，可能是 5 或者 6。这时候硬套 impeccable 的默认配置就会到处报错。

解决办法是改配置，把spacing.base改成你团队实际用的基准。impeccable 的尺度体系是可配置的，不是写死的。我见过用 6px 基准的团队，配置改一下照样跑得很顺。

提示：如果你的设计系统本身就是"混乱"的，那正好借 impeccable 这次机会梳理一遍。工具报错多，有时候不是工具的问题，是设计系统本身该重构了。

6.3 浏览器扩展标注不消失

有时候你明明改了代码，扩展的标注还在。这通常是缓存问题。

排查顺序：先硬刷新页面（Ctrl+Shift+R），不行就重启扩展，再不行就检查扩展版本和 CLI 版本是否匹配。我遇到过扩展版本比 CLI 版本旧，导致规则不一致的情况，更新一下就好了。

6.4 常见问题速查表

6.5 几个我踩过的坑

坑一：别在 CI 里把警告当错误。我一开始图省事，CI 里配了"有任何警告就失败"，结果团队天天被卡。后来改成"错误失败，警告只报告"，顺畅多了。警告是改进方向，不是阻断条件。

坑二：对比度检查要考虑动态背景。如果你的文字放在图片或渐变上，impeccable 的静态计算可能不准。这种情况我一般手动确认，必要时在配置里加白名单跳过。

坑三：别追求 100% 干净。有些"违规"是有意为之的设计决策，比如刻意的非标准间距做视觉强调。工具是辅助，不是圣旨。该跳过就跳过，配置里留个白名单机制。

7. 我对这套工具链的真实体会

用 impeccable 这套东西大半年下来，我最大的感受是：它改变的不是代码，是我的工作习惯。

以前我用 AI 生成前端，生成完看一眼"能跑"就过了，细节全靠后面慢慢磨。现在有了这层校验，我在生成阶段就会下意识地把规范带上，因为我知道后面会被查。这种"前置的自觉"，比事后修复有价值得多。

另外一个体会是，工具的价值在于把隐性知识显性化。间距节奏、状态完整性、对比度这些，老前端是凭感觉做的，新人根本不知道有这回事。impeccable 把这些"感觉"变成了具体的检查项和数值，新人照着改几轮，审美和规范意识就建立起来了。这比看十篇设计规范文章都管用。

最后分享一个小技巧：如果你团队里有人对"AI 味"的界面特别敏感，让他来当 impeccable 报告的"验收人"。他挑出来的问题，往往就是工具报出来的问题。用工具把他的直觉固化下来，整个团队的交付质量就稳了。