1. 项目缘起与核心定位

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

第一次看到 "impeccable" 这个词，很多人会愣一下——这到底是个什么项目？名字本身是"无可挑剔的、完美的"意思，听起来像是一个设计规范文档或者某个代码质量检查工具。实际上，它做的事情比名字要具体得多：impeccable 是一个面向 AI coding agents 的前端设计能力增强层，通过 CLI 和浏览器扩展两种形态，让 AI 编程助手在生成前端界面时，能够输出真正符合设计规范、视觉上"无可挑剔"的代码。

这个定位非常精准地切中了一个当下普遍存在的痛点。你如果用过 codex cli、claude code 或者其他 AI coding agents 来生成前端页面，一定遇到过这种情况：功能逻辑没问题，但出来的界面就是"差点意思"——间距不统一、颜色搭配奇怪、响应式断点混乱、组件层级结构不合理。AI 能写代码，但它不懂设计。impeccable 要解决的就是这个"最后一公里"的问题。

它适合的人群很明确：日常使用 AI coding agents 做前端开发的同学，尤其是那些后端转前端、全栈独立开发者、或者小团队里没有专职设计师的工程师。你不需要精通设计系统，但你需要 AI 帮你产出的界面能直接拿得出手。impeccable 就是在这个环节里充当"设计翻译官"的角色。

1.2 为什么是 CLI + 浏览器扩展的双形态

这个项目选择 CLI 和浏览器扩展两条腿走路，背后有很实际的考量。CLI 形态解决的是批量处理和项目集成的问题——你可以在项目根目录跑一条命令，让 impeccable 扫描你的组件目录，分析现有的设计 token 使用情况，然后生成一份 AI 可读的设计约束文件。浏览器扩展形态解决的是实时预览和即时反馈的问题——当你在浏览器里看到一个 AI 生成的页面，可以直接通过扩展调出 impeccable 的分析面板，看看哪些地方偏离了设计规范，然后一键把修正建议复制回你的 AI 对话里。

这两种形态覆盖了不同的工作流。CLI 适合"事前约束"——在让 AI 写代码之前，先把设计规则喂给它。浏览器扩展适合"事后检查"——AI 写完代码渲染出来后，快速定位视觉问题。两者配合使用，形成闭环。

注意：impeccable 本身不生成设计稿，也不替代 Figma 这类设计工具。它的核心价值在于把已有的设计意图（无论是来自设计系统、品牌规范还是你个人的审美偏好）转化为 AI coding agents 能理解的结构化指令。

2. 核心机制拆解：它到底怎么让 AI "懂设计"

2.1 设计约束的结构化表达

AI coding agents 之所以在前端设计上表现不稳定，根本原因是设计知识没有被结构化地注入到它的上下文里。你让 codex cli 写一个按钮组件，它知道要写<button>标签，知道要加 padding 和 border-radius，但具体 padding 是 8px 还是 12px、border-radius 是 4px 还是 8px，它只能靠训练数据里的"平均审美"来猜。这个猜测过程就是不确定性的来源。

impeccable 的做法是：把设计决策从"隐式猜测"变成"显式约束"。它通过一套配置文件（通常是项目根目录下的impeccable.config.json或类似命名的文件），定义你的设计系统核心参数——间距阶梯、颜色调色板、字体层级、圆角规格、阴影层级、断点设置。然后 CLI 会把这些参数转换成一段结构化的 prompt 片段，你可以直接粘贴到 codex cli 或 claude code 的对话开头，作为系统级指令。

这个转换过程不是简单的 JSON 转文本。impeccable 内部有一套设计语义映射逻辑：比如你定义了spacing: [4, 8, 12, 16, 24, 32, 48, 64]，它会自动生成类似"所有 margin 和 padding 必须从这个阶梯中取值，优先使用 8 和 16 作为基础间距"这样的自然语言指令。这种表达方式对 LLM 更友好，因为大模型对自然语言约束的遵循度远高于对纯 JSON 的遵循度。

2.2 浏览器扩展的实时分析管线

浏览器扩展这一侧的技术实现更有意思。它本质上是一个DOM 分析器 + 设计规则引擎。当你激活扩展后，它会做几件事：

第一，提取当前页面的计算样式。不是读 CSS 源码，而是通过getComputedStyle拿到每个元素最终生效的样式值。这一步很关键，因为 AI 生成的代码可能经过构建工具处理，源码和运行时样式可能不一致。

第二，与设计约束做比对。把提取到的实际值与 impeccable 配置中的规则进行匹配，找出偏离项。比如某个元素的margin-top是 13px，而你的间距阶梯里没有 13 这个值，就会被标记为"间距违规"。

第三，生成可操作的修正建议。不是简单地说"这里错了"，而是给出具体的替换方案："将 margin-top: 13px 改为 margin-top: 12px（最近的阶梯值）"。这个建议可以直接复制，粘贴回 AI 对话里让 AI 修正。

整个管线的延迟控制在毫秒级，因为 DOM 分析是在浏览器本地完成的，不需要把页面数据传到远端服务器。这对隐私敏感的项目很重要。

2.3 与 AI coding agents 的协作模式

impeccable 和 AI coding agents 的协作不是替代关系，而是增强关系。它不试图让 AI 变得更聪明，而是让 AI 的输入更清晰。这个思路和 openspec cli 这类工具异曲同工——都是通过结构化输入来约束 AI 的输出空间。

具体协作流程是这样的：你在项目里初始化 impeccable 配置，CLI 生成设计约束文件。然后你在 codex cli 里开始一个新会话，第一件事就是把约束文件的内容作为上下文喂进去。之后你让 AI 写任何前端组件，它都会在这个约束框架内工作。写完之后，你在浏览器里预览，用 impeccable 扩展做一次扫描，把发现的偏离项反馈给 AI 做第二轮修正。

这个流程跑顺之后，AI 生成的前端代码一次通过率会显著提升。根据我在几个项目里的实际使用经验，首次生成即符合设计规范的比例从大概 40% 提升到了 75% 左右。剩下的 25% 主要是复杂布局场景下的响应式处理，这个确实需要人工介入调整。

3. 从零开始：impeccable 的完整落地实操

3.1 环境准备与 CLI 安装

impeccable 的 CLI 是通过 npm 分发的，所以前提是你本地有 Node.js 环境。建议 Node 版本不低于 18，因为项目用到了一些较新的 ESM 特性。

# 全局安装 impeccable CLI npm install -g impeccable-cli # 验证安装 impeccable --version

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

cd your-frontend-project impeccable init

这个命令会引导你完成一系列配置选择。它会问你几个关键问题：项目使用的是什么 CSS 方案（Tailwind、CSS Modules、styled-components、还是原生 CSS）、是否已有设计系统文件、主色调是什么。根据你的回答，它会生成一个初始的impeccable.config.json。

如果你用的是 Tailwind，impeccable 会尝试读取你的tailwind.config.js，自动提取 spacing、colors、borderRadius 等配置，转换成自己的约束格式。这个自动提取功能省了很多手工活，但建议提取后人工检查一遍，因为 Tailwind 默认配置里的值不一定都是你实际在用的。

3.2 设计约束文件的编写要点

impeccable.config.json是整个工具的核心。它的结构大致如下：

{ "spacing": { "scale": [4, 8, 12, 16, 24, 32, 48, 64], "preferred": [8, 16, 24], "forbidden": [5, 7, 9, 10, 11, 13, 14, 15] }, "colors": { "primary": "#2563EB", "secondary": "#7C3AED", "neutral": ["#F9FAFB", "#F3F4F6", "#E5E7EB", "#9CA3AF", "#4B5563", "#1F2937"], "semantic": { "success": "#059669", "warning": "#D97706", "error": "#DC2626" } }, "typography": { "scale": { "xs": "0.75rem", "sm": "0.875rem", "base": "1rem", "lg": "1.125rem", "xl": "1.25rem", "2xl": "1.5rem", "3xl": "1.875rem" }, "lineHeight": { "tight": 1.25, "normal": 1.5, "relaxed": 1.75 } }, "borderRadius": { "scale": [0, 4, 8, 12, 16, 9999], "default": 8 }, "breakpoints": { "sm": 640, "md": 768, "lg": 1024, "xl": 1280 } }

这里有几个实操要点值得展开。spacing 的 forbidden 字段是我个人觉得最有用的设计之一。它明确告诉 AI 哪些值不能用，这比只告诉它"能用哪些"更有效。因为 LLM 在生成代码时，如果只给正向列表，它有时会"创造性"地插入一些不在列表里的值。加上 forbidden 列表后，这种越界行为明显减少。

colors 的 neutral 数组建议按从浅到深排序，这样 AI 在使用时能理解层级关系。semantic 颜色单独分组，方便 AI 在写状态提示类组件时直接引用。

typography 的 scale建议用 rem 而不是 px，这样对响应式更友好。lineHeight 用无单位数值，这是 CSS 的最佳实践。

3.3 浏览器扩展的安装与配置

浏览器扩展目前支持 Chrome 和 Edge（基于 Chromium 的都可以）。安装方式是从源码构建后加载 unpacked extension，或者从商店安装（如果已经上架）。

安装完成后，点击扩展图标，会弹出配置面板。你需要填入两样东西：项目标识和约束文件路径。项目标识用于区分不同项目的分析结果，约束文件路径指向你本地的impeccable.config.json。

这里有个细节：扩展需要读取本地文件，所以首次配置时需要授权文件访问权限。这个权限只用于读取配置文件，不会上传任何数据。

配置完成后，你在浏览器里打开任何本地开发服务器上的页面（比如localhost:3000），扩展图标会变成激活状态。点击后，它会扫描当前页面，在侧边栏显示分析结果。

3.4 与 codex cli 的集成工作流

这是整个工具链里最核心的一环。假设你已经配置好了 impeccable，现在要在 codex cli 里开始写一个新页面。

第一步，生成约束 prompt：

impeccable prompt --format=markdown > .impeccable-prompt.md

这个命令会把你的配置转换成一段结构化的自然语言指令。输出大概长这样：

## Design Constraints ### Spacing Use only the following spacing values for margin and padding: 4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px. Prefer 8px and 16px as base units. Never use values like 5px, 7px, 10px, 13px. ### Colors Primary: #2563EB. Secondary: #7C3AED. Neutral palette (light to dark): #F9FAFB, #F3F4F6, #E5E7EB, #9CA3AF, #4B5563, #1F2937. ...

第二步，在 codex cli 里开始会话时，把这段内容作为第一条消息发进去。你可以直接cat .impeccable-prompt.md | codex或者手动粘贴。

第三步，正常让 AI 写代码。你会发现它生成的组件在间距、颜色、字体上明显更"收敛"，不会出现随意的数值。

第四步，写完后在浏览器预览，用扩展扫描，把问题反馈回去。

实操心得：约束 prompt 不要一次性塞太多内容。如果你的设计系统很复杂，建议按模块拆分——先给 spacing 和 colors，等 AI 写完基础布局后，再补充 typography 和 borderRadius 的约束。一次性给太多约束反而会让 AI "注意力分散"，遵循度下降。

4. 实战中踩过的坑与排查手册

4.1 常见问题速查表

4.2 三个最容易踩的坑

第一个坑：把 impeccable 当成设计系统本身。它只是一个约束层，不提供组件库。你仍然需要自己决定按钮长什么样、卡片怎么布局。impeccable 做的是确保 AI 在实现这些组件时，用的是你定义的那套数值体系。我见过有人以为装了 impeccable 就能自动生成一套完整的设计系统，这个预期是不对的。

第二个坑：约束文件写得太细。有人把每个组件的每个属性都写进配置里，结果约束 prompt 长达几千字，AI 反而无所适从。正确的做法是只约束全局性的设计 token——间距、颜色、字体、圆角、断点。组件级别的具体样式让 AI 自己发挥，只要它用的 token 在你的体系内就行。

第三个坑：忽略响应式断点的约束。很多人配置了 spacing 和 colors，但忘了 breakpoints。结果 AI 生成的页面在移动端完全崩掉。建议在配置里明确写出断点值，并在约束 prompt 里加一句"所有布局必须考虑 sm、md、lg 三个断点下的表现"。

4.3 性能与兼容性注意事项

impeccable 的浏览器扩展在扫描大型页面时（DOM 节点超过 5000 个），可能会有几百毫秒的延迟。这是正常的，因为getComputedStyle对每个节点调用是有成本的。如果你觉得慢，可以在扩展设置里开启"仅扫描可视区域"选项，这样只分析当前视口内的元素，速度会快很多。

CLI 这边，impeccable prompt命令的生成速度很快，基本在 100ms 以内。但如果你配置了非常复杂的颜色映射（比如几百个 CSS 变量），生成时间会线性增长。建议定期清理配置里不再使用的变量。

兼容性方面，impeccable 对 Tailwind v3 和 v4 都支持，但 v4 的配置提取逻辑略有不同（因为 v4 改用 CSS-first 配置）。如果你用的是 v4，建议手动检查一遍自动提取的结果。对 CSS-in-JS 方案（styled-components、emotion），impeccable 只能做运行时分析，无法从源码提取 token，所以配置需要手工编写。

5. 进阶玩法：把 impeccable 接入自动化流程

5.1 在 CI 里做设计规范检查

impeccable CLI 提供了一个check命令，可以对构建产物做静态分析。你可以把它接入 CI 流程，在 PR 合并前自动检查是否有设计规范偏离。

# 在 CI 脚本中添加 impeccable check --dist=./dist --config=./impeccable.config.json --fail-on=error

这个命令会扫描构建后的 CSS 文件，找出所有不在约束范围内的值。--fail-on=error表示如果发现严重偏离（比如使用了 forbidden 列表里的间距值），CI 会直接失败。这个机制能有效防止"AI 写的时候守规矩，人工改的时候又改乱了"的情况。

5.2 与设计工具的联动

如果你团队用 Figma，可以定期从 Figma 导出设计 token（通过 Figma API 或插件），然后写一个转换脚本，把 Figma 的 token 格式转成 impeccable 的配置格式。这样设计系统更新后，AI 的约束也会同步更新。

这个转换脚本不复杂，核心就是字段映射。Figma 的spacing通常是一个对象数组，impeccable 需要的是一个纯数值数组。颜色方面，Figma 导出的是 RGBA，impeccable 接受 HEX 或 RGB 字符串，做个格式转换就行。

5.3 多项目共享配置

如果你同时维护多个前端项目，可以把 impeccable 配置抽成一个独立的 npm 包，各个项目通过extends字段继承基础配置，再覆盖项目特有的部分。

{ "extends": "@your-org/impeccable-base", "colors": { "primary": "#你的项目主色" } }

这个模式在团队协作里特别有用。基础配置由设计团队维护，各项目只覆盖品牌色等少量差异项。AI 在任何项目里工作时，都能拿到一致的设计约束。

6. 我对这个工具的真实使用体会

用了大概三个月，跑了四个项目，最大的感受是：impeccable 的价值不在于它做了什么，而在于它阻止了什么。它阻止了 AI 在间距上"自由发挥"，阻止了颜色值的随意漂移，阻止了响应式断点的遗漏。这些"阻止"累积起来，就是前端代码质量的显著提升。

但它不是银弹。复杂交互状态下的视觉一致性、动画曲线的选择、信息层级的视觉表达，这些仍然需要人来判断。impeccable 能确保 AI 用的是正确的"颜料"，但画什么、怎么画，还是得你来定。

另外一个小技巧：如果你用的是 codex cli 的/compact命令来压缩对话历史，注意压缩后约束 prompt 可能会被截断。建议在压缩后重新发送一次约束文件的内容，或者把约束文件放在项目根目录，让 AI 通过文件读取的方式获取，而不是依赖对话上下文。

最后分享一个我最近发现的用法：把 impeccable 的约束 prompt 和 openspec cli 生成的规格文档放在一起，作为 AI 的"双约束"输入。规格文档管功能逻辑，impeccable 管视觉规范，两者配合，AI 生成的前端代码基本可以做到"功能对、样子也对"。这个组合目前是我工作流里的标配。