impeccable：面向AI coding agents的前端设计约束系统

1. 从"impeccable"说起：一个被低估的前端设计关键词

第一次看到"impeccable"这个词被拿来命名一个前端设计相关的项目，我的反应是——这名字起得挺狂。"无可挑剔"，口气不小。但仔细琢磨一下，这个词精准地戳中了当下前端开发的一个核心痛点：AI coding agents 能帮你写逻辑、写接口、写测试，但写出来的界面往往"能用但不好看"。

这就是"impeccable"这个项目要解决的问题。它不是一个框架，不是一个组件库，而是一套面向 AI coding agents 的前端设计约束系统。简单说，它做的事情是：让 AI 在生成前端代码时，遵循一套经过精心设计的视觉规范，从而产出"无可挑剔"的界面。

你可能会问，这跟直接用 Tailwind、用 shadcn/ui 有什么区别？区别在于，那些工具是给人用的，而 impeccable 是给 AI 用的。它的核心交付物包括一套 CLI 工具、一个浏览器扩展，以及一套嵌入到 AI agent 工作流中的设计规则集。你可以在终端里通过 CLI 快速初始化项目、校验设计规范的合规性，也可以在浏览器里通过扩展实时预览 AI 生成的界面效果，甚至直接把设计反馈回传给 agent。

适合谁来关注这个项目？三类人：一是正在用 AI coding agents（比如各种 CLI 形态的编码助手）做前端开发的工程师；二是对前端设计有要求但不想手动调 CSS 的全栈开发者；三是想把自己团队的设计规范"喂"给 AI 的技术负责人。不管你是哪种，impeccable 的思路都值得了解——它代表了一种新的前端工程范式：设计规范不再只是给人看的文档，而是可以直接被 AI 消费和执行的代码级约束。

2. 核心设计思路拆解：为什么是"约束"而不是"生成"

2.1 AI 写前端的根本问题不在"能不能写"，而在"写得对不对"

我用过不少 AI coding agents 来生成前端页面，踩过的坑基本可以归为三类。第一类是间距混乱：AI 生成的组件，padding 一会儿是 12px，一会儿是 16px，一会儿又变成 1rem，完全没有节奏感。第二类是颜色失控：主色、辅助色、语义色混着用，hover 状态和 active 状态的颜色差异微乎其微，用户根本感知不到反馈。第三类是层级缺失：标题和正文的字号差距不够，卡片的阴影和背景对比度太低，整个页面看起来"平"得像一张纸。

这些问题的根源不是 AI 不够聪明，而是AI 没有被赋予一套明确的、可执行的视觉约束。你给它的 prompt 里写"做一个好看的登录页"，它只能根据训练数据里的"平均审美"来猜。但如果你告诉它"间距只能用 4px 的倍数，主色只能从这三个色值里选，标题和正文的字号比不得低于 1.5"，它就能稳定地产出符合预期的结果。

impeccable 的核心设计思路就是围绕这个洞察展开的：与其让 AI 自由发挥，不如给它一套精心设计的约束框架。

2.2 三层架构：CLI + 浏览器扩展 + Agent 规则集

impeccable 的架构可以拆成三层来理解。

最底层是设计规则集，这是一组用结构化格式（通常是 JSON 或 YAML）定义的设计 token 和约束条件。它规定了间距的粒度、颜色的取值范围、字号的阶梯、圆角的档位、阴影的层级等等。这层是整个系统的"宪法"，所有其他层都围绕它运转。

中间层是CLI 工具。它的作用是把设计规则集注入到你的项目里，并且在开发过程中提供校验能力。比如你可以在项目根目录跑一条命令，它会扫描你的 CSS 文件或者组件代码，检查是否有违反设计规范的地方，然后给出具体的修改建议。这层的价值在于把设计规范的执行从"靠人自觉"变成"靠工具强制"。

最上层是浏览器扩展。它做的事情更直观：在你本地开发的时候，实时在浏览器里标注出哪些元素的样式偏离了设计规范。比如某个按钮的 padding 不在允许的档位里，扩展会直接在那个元素上画一个高亮框，旁边显示"期望值：16px，实际值：14px"。这层的价值在于把抽象的规范变成可视化的反馈，大大降低了理解和修正的成本。

这三层配合起来，形成了一个闭环：规则集定义标准，CLI 在代码层面校验，浏览器扩展在视觉层面校验，而 AI agent 在整个过程中根据这些反馈不断调整自己的输出。

2.3 为什么不做成"一键生成完美 UI"的工具

这里有一个关键的设计取舍值得说清楚。impeccable 完全有能力做成一个"你描述需求，它直接生成完美页面"的工具，但它没有这么做。为什么？

因为前端设计的本质是权衡，而权衡需要上下文。一个电商详情页和一个 SaaS 仪表盘，对信息密度的要求完全不同；一个面向年轻人的社交产品和一个面向企业的管理后台，对色彩饱和度的容忍度也天差地别。如果 impeccable 试图用一个"万能模板"来覆盖所有场景，结果一定是每个场景都做得不够好。

所以它选择了另一条路：提供约束框架，让 AI 在框架内根据具体场景做决策。这就像给一个厨师一套精选的食材和调料，而不是直接给他一份做好的菜。厨师可以根据客人的口味、当天的食材状态、甚至天气来调整做法，但无论如何调整，用的都是那套经过筛选的原料。这种"约束下的自由"才是 AI 前端设计的正确打开方式。

3. 核心细节解析：设计规则集到底长什么样

3.1 间距系统：4px 基准网格不是随便定的

impeccable 默认的间距系统基于4px 基准网格。这个数字不是拍脑袋来的。在 1x 屏幕密度下，4px 是一个足够小的粒度，可以表达出细微的间距差异；同时它又足够大，不会因为过于精细而导致样式表膨胀。更重要的是，4px 的倍数（4、8、12、16、24、32、48、64）在视觉上形成了自然的节奏感，人眼能感知到这些间距之间的"比例关系"。

在实际配置中，间距 token 通常这样定义：

{ "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px", "2xl": "48px", "3xl": "64px" } }

注意这里用的是语义化命名而不是直接的数字。为什么？因为当 AI 看到spacing.md的时候，它能理解这是一个"中等间距"，适合用在卡片内部、表单元素之间；而看到16px的时候，它只知道这是一个数值，不知道什么时候该用。语义化命名给了 AI 更多的上下文信息，让它能做出更合理的决策。

注意：如果你团队已经有自己的间距体系，不要直接照搬 impeccable 的默认值。先把你们现有的间距值整理出来，看看是否能归纳到一个基准网格上。如果不能，说明你们的间距系统本身就有问题，正好借这个机会统一一下。

3.2 颜色系统：语义层比色值层更重要

impeccable 的颜色系统分两层：原始色板层和语义层。原始色板层定义了一组具体的色值，比如blue-500: #3B82F6、gray-100: #F3F4F6。语义层则定义了这些色值在不同场景下的用途，比如color-primary: blue-500、color-background-subtle: gray-100。

这种分层的好处是，当你想换主题色的时候，只需要改语义层的映射关系，不需要去每个组件里替换色值。对于 AI 来说，它只需要知道"这个按钮应该用color-primary"，而不需要关心color-primary具体是什么颜色。这大大降低了 AI 做出错误颜色决策的概率。

在实际项目中，语义层的定义通常包括以下几类：

这张表看起来简单，但它是整个颜色系统的核心。AI 在生成代码时，只要按照这张表来选择 token，就不会出现"这个按钮用了蓝色，那个按钮用了紫色"的混乱情况。

3.3 字号阶梯：1.25 倍比例背后的视觉逻辑

impeccable 默认的字号阶梯采用1.25 倍比例（也叫 Major Third）。基础字号是 16px，那么各级字号分别是：16、20、25、31、39、49。实际使用时会取整到常用值：16、20、24、32、40、48。

为什么是 1.25 倍而不是 1.5 倍或者 1.2 倍？1.5 倍的比例太激进，相邻两级之间的差距过大，会导致页面上的文字层级过于分明，看起来"跳跃感"太强。1.2 倍的比例又太保守，相邻两级之间的差距不够明显，用户很难一眼分辨出哪个是标题哪个是正文。1.25 倍是一个经过大量实践验证的"甜点区"，既能形成清晰的层级，又不会显得突兀。

对于 AI 来说，字号阶梯的意义在于：它不需要"猜"某个文字应该用多大字号，只需要根据内容的层级从阶梯里选一个。页面主标题用font-size-3xl（32px），卡片标题用font-size-lg（20px），正文用font-size-base（16px），辅助说明用font-size-sm（14px）。每个层级都有明确的对应关系，AI 只需要做选择题，不需要做填空题。

3.4 圆角和阴影：克制是最高级的设计

impeccable 在圆角和阴影上的态度非常克制。圆角只提供三档：radius-sm: 4px、radius-md: 8px、radius-lg: 16px。阴影只提供三档：shadow-sm、shadow-md、shadow-lg，分别对应"轻微浮起"、"明显浮起"、"强烈浮起"三种视觉层级。

这种克制是有意为之的。我见过太多项目，圆角从 2px 到 24px 有七八种不同的值，阴影更是五花八门，每个组件都有一套自己的阴影参数。结果就是整个页面看起来"碎"，缺乏统一感。AI 在这种环境下生成代码，只会加剧混乱——它可能会给一个按钮加上 12px 的圆角，给另一个按钮加上 10px 的圆角，因为它觉得"差不多"。

实操心得：圆角和阴影的档位越少，AI 做出正确选择的概率越高。如果你觉得三档不够用，先问问自己是不是在过度设计。大多数情况下，三档足够了。

4. CLI 工具实操：从初始化到校验的完整流程

4.1 安装与初始化：一条命令搞定

impeccable 的 CLI 工具安装方式很直接。如果你用的是 npm 生态，全局安装即可：

npm install -g impeccable-cli

安装完成后，在你的项目根目录执行初始化命令：

impeccable init

这条命令会做几件事：在项目根目录创建一个impeccable.config.json文件，里面包含默认的设计规则集；在你的 CSS 入口文件里注入必要的 CSS 变量定义；如果检测到你在用 Tailwind，它还会自动生成对应的tailwind.config.js扩展配置。

初始化完成后，你会看到项目里多了一个design-tokens目录，里面按类别存放了间距、颜色、字号等 token 的定义文件。这些文件是后续所有校验和生成的依据，不要手动修改它们，如果需要调整规范，应该通过impeccable config命令来修改。

4.2 校验命令：找出所有偏离规范的地方

初始化完成后，你可以随时运行校验命令：

impeccable lint

这条命令会扫描你项目里所有的 CSS、SCSS、Less 文件，以及组件文件里的内联样式，检查是否有违反设计规范的地方。输出结果类似这样：

src/components/Button.css 12:5 warning padding value 14px is not in spacing scale [impeccable/spacing] 18:3 warning color #3B82F6 should use token color-primary [impeccable/color] 24:1 error border-radius 10px is not in radius scale [impeccable/radius] 3 problems (1 error, 2 warnings)

每条问题都标注了文件路径、行号、严重程度、问题描述和对应的规则名称。warning级别的可以暂时忽略，但error级别的必须修复，否则在 CI 流程中会阻断构建。

如果你只想检查某个特定目录，可以加上路径参数：

impeccable lint src/components/

如果你想自动修复那些可以自动修复的问题（比如把#3B82F6替换成var(--color-primary)），可以加上--fix参数：

impeccable lint --fix

注意：--fix只会修复那些"语义明确"的问题，比如色值替换。对于间距和圆角这类需要判断意图的问题，它不会自动修改，只会给出警告。这是为了避免自动修复引入意料之外的视觉变化。

4.3 与 AI Agent 的集成：让 agent 自己检查自己的输出

这是 impeccable 最有价值的部分。它提供了一个专门给 AI agent 调用的命令：

impeccable check --format=json

这条命令会输出结构化的 JSON 结果，包含所有违规项的位置、类型和建议的修复值。你可以在 AI agent 的工作流里配置一个"生成后检查"的步骤：agent 生成完代码后，自动运行这条命令，如果发现有违规项，就把 JSON 结果回传给 agent，让它根据建议重新生成。

在实际配置中，你可以在 agent 的 prompt 里加入这样一段指令：

在生成任何前端代码后，必须运行 `impeccable check --format=json` 命令。 如果输出结果中包含 error 级别的违规项，根据返回的 suggestedFix 字段修正代码， 然后重新运行检查，直到没有 error 级别的违规项为止。

这段指令看起来简单，但它把 impeccable 从一个"事后检查工具"变成了"实时约束系统"。AI agent 不再是生成完就完事，而是会主动检查自己的输出是否符合规范，不符合就改，直到符合为止。

4.4 自定义规则：把你的团队规范写进去

impeccable 的默认规则集是一个起点，不是终点。每个团队都有自己的设计偏好，你可以通过修改impeccable.config.json来定制规则。比如你们团队规定所有卡片的圆角必须是 12px，不允许用其他值：

{ "rules": { "radius": { "scale": ["0", "12px", "9999px"], "strict": true } } }

strict: true表示只允许使用 scale 里列出的值，任何不在列表里的圆角值都会被视为 error。这种严格模式适合那些设计规范已经非常成熟的团队，可以强制 AI 和开发者都遵守统一的标准。

如果你还在探索阶段，可以把strict设为false，这样不在 scale 里的值只会被标记为 warning，不会阻断构建。等规范稳定了再切换到严格模式。

5. 浏览器扩展：所见即所得的规范校验

5.1 安装与启用：开发者工具里的新面板

impeccable 的浏览器扩展安装后，会在 Chrome DevTools 里增加一个名为 "Impeccable" 的面板。打开你的本地开发页面，按 F12 打开 DevTools，切换到 Impeccable 面板，你会看到一个类似审计工具的界面。

面板顶部有一个"开始检测"按钮，点击后扩展会扫描当前页面上所有可见元素的样式，然后按类别列出所有偏离规范的地方。检测结果分为三个视图：按元素查看、按规则查看、按严重程度查看。你可以根据自己的习惯切换。

5.2 实时标注：页面上直接画框

这是浏览器扩展最直观的功能。当你开启"实时标注"模式后，页面上所有违反规范的元素都会被画上一个彩色边框。红色边框表示 error 级别的问题，黄色边框表示 warning 级别的问题。鼠标悬停在边框上，会弹出一个提示框，显示具体的问题描述和建议的修复值。

比如你有一个按钮的 padding 是 14px，而规范里只允许 12px 或 16px，扩展会在这个按钮上画一个黄色边框，提示框里显示："padding: 14px 不在间距规范内，建议改为 12px 或 16px"。

这种可视化的反馈方式，比在控制台里看一堆文字输出要高效得多。特别是当你需要快速定位问题时，直接在页面上扫一眼就能找到所有违规元素。

5.3 与 CLI 的联动：浏览器里发现问题，终端里修复

浏览器扩展和 CLI 工具之间有一个联动机制。当你在浏览器里发现某个元素有问题时，可以点击提示框里的"复制修复命令"按钮，扩展会把对应的修复命令复制到剪贴板。你切换到终端，粘贴命令，CLI 会自动定位到对应的文件和行号，并给出修复建议。

这个联动看起来只是省了几次复制粘贴的操作，但在实际开发中，它大大缩短了"发现问题→定位问题→修复问题"的循环。特别是当页面上有几十个违规元素时，你可以逐个点击、逐个修复，不需要手动去代码里搜索。

实操心得：我通常会在开发过程中一直开着实时标注模式，这样每写一个组件就能立刻看到它是否符合规范。等到提交代码前再跑一次impeccable lint做最终检查。这种"实时+最终"的双重校验，基本可以保证不会把违规代码提交到仓库。

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

6.1 为什么 CLI 报的错和浏览器扩展报的不一样

这是最常见的问题。原因通常是 CLI 扫描的是源代码，而浏览器扩展扫描的是渲染后的样式。有些样式是通过 CSS-in-JS 动态生成的，CLI 可能无法解析；有些样式是通过 JavaScript 在运行时计算的，浏览器扩展能看到但 CLI 看不到。

解决方法是：以 CLI 的结果为准来修复代码，以浏览器扩展的结果为准来验证效果。如果 CLI 没报错但浏览器扩展报了，说明问题出在运行时逻辑上，需要检查你的 JavaScript 代码里是否有硬编码的样式值。

6.2 第三方组件的样式被误报怎么办

如果你用了第三方 UI 库（比如 Ant Design、Element Plus），它们的组件样式很可能不符合 impeccable 的规范，导致大量误报。解决方法是在配置文件里把第三方组件的样式路径加入忽略列表：

{ "ignore": [ "node_modules/**", "src/styles/vendor/**" ] }

如果你只想忽略特定的规则，可以在 ignore 里指定规则名称：

{ "ignore": [ { "path": "src/components/ThirdParty/**", "rules": ["impeccable/spacing", "impeccable/radius"] } ] }

6.3 AI agent 不遵守规范怎么办

有时候你配置好了所有规则，但 AI agent 生成代码时还是我行我素。这通常是因为 agent 的 prompt 里没有明确引用 impeccable 的规则。你需要在 prompt 里显式地告诉 agent：

本项目使用 impeccable 设计规范。所有前端代码必须通过 `impeccable check` 校验。 在生成代码前，先阅读 `design-tokens/` 目录下的所有 token 定义文件。 生成代码后，必须运行 `impeccable check --format=json` 并修复所有 error 级别的问题。

另外，确保你的 agent 有权限读取design-tokens/目录和运行 CLI 命令。有些 agent 默认只能读写特定目录，需要手动配置权限。

6.4 规范太严格导致开发效率下降

这是一个需要平衡的问题。我的建议是分阶段推进：第一阶段只启用颜色和字号的校验，这两个对视觉影响最大且最容易统一；第二阶段加入间距和圆角；第三阶段再加入阴影和其他细节。每个阶段间隔一到两周，让团队和 AI 都有时间适应。

另外，对于正在快速迭代的项目，可以把strict设为false，让违规项只产生 warning 而不阻断构建。等到项目进入稳定期再切换到严格模式。

6.5 常见问题速查表

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

用了几个月 impeccable 之后，最大的感受是：它改变了我对"设计规范"这件事的认知。以前我觉得设计规范就是一份 Figma 文档或者一个 Storybook 页面，是给人看的参考。但 impeccable 让我意识到，规范应该是可执行的代码，是能被工具校验、被 AI 消费的约束条件。

当然，它也不是银弹。如果你的项目本身就没有明确的设计规范，impeccable 帮不了你——它只能执行规范，不能替你制定规范。如果你的团队对设计的要求是"差不多就行"，那这套工具可能会显得过于繁琐。但如果你和我一样，受够了 AI 生成的那些"能用但不好看"的界面，想找到一个系统性的解决方案，那 impeccable 的思路值得你花时间研究。

最后分享一个我在实际配置中的小技巧：把impeccable.config.json纳入版本控制，并且在 PR 模板里加一条检查项"是否通过了 impeccable lint"。这样每次代码审查时，reviewer 不需要手动检查样式规范，CI 会自动跑校验，不通过就阻断合并。坚持一段时间后，团队里所有人（包括 AI agent）都会形成肌肉记忆，生成符合规范的代码变成了一种默认行为，而不是需要刻意注意的事情。