1. 项目缘起与核心定位

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

第一次看到 "impeccable" 这个词，很多人会愣一下——这到底是个什么项目？名字本身是"无可挑剔的、完美的"意思，听起来像是个设计规范或者代码质量检查工具。实际上，它确实跟"质量"有关，但切入的角度非常具体：让 AI 编程助手在生成前端界面时，输出真正能看、能用的设计，而不是一堆勉强能跑的 div 堆砌。

这个项目的核心定位可以用一句话概括：它是一个面向 AI coding agents 的前端设计能力增强层。你平时用 Codex CLI、Claude Code 或者其他命令行 AI 编程工具写前端代码时，是不是经常遇到这种情况——功能逻辑没问题，但界面丑得没法看？间距忽大忽小、颜色搭配辣眼睛、响应式布局一塌糊涂。impeccable 就是来解决这个问题的。

它不是一个独立的编辑器，也不是一个完整的框架，而是一套设计约束规则集 + CLI 工具链 + 浏览器扩展的组合。通过这套东西，你可以让 AI 在生成前端代码时，自动遵循一套经过验证的设计系统，从而大幅提升输出质量。

1.2 谁最需要这个工具

我梳理了一下，以下几类人用 impeccable 的收益最明显：

• 独立开发者：一个人要搞定全栈，前端设计能力有限，但又不想每个项目都套同一个模板。impeccable 能让 AI 帮你补上设计这块短板。
• 全栈工程师转前端：后端逻辑写得飞起，一到 CSS 就头疼。这个工具相当于给你配了一个"设计副驾驶"。
• 技术团队的技术负责人：团队里没有专职设计师，但产品界面不能太寒碜。用 impeccable 可以统一团队的 AI 生成代码风格。
• AI 工具重度用户：已经在用 Codex CLI、Trae CLI 这类工具写代码，但总觉得生成的前端"差点意思"，想找个系统性的解决方案。

如果你属于以上任何一类，接下来的内容应该能帮你省下不少试错时间。

1.3 它到底解决了什么核心问题

要理解 impeccable 的价值，得先搞清楚 AI 写前端代码的根本痛点在哪里。

大语言模型在生成前端代码时，存在几个系统性的缺陷。第一，空间感知能力弱。模型不知道 16px 的 padding 和 24px 的 padding 在视觉上有什么区别，它只是根据训练数据里的统计规律在输出数值。第二，缺乏设计系统概念。你让它写一个按钮，它可能这次用蓝色，下次用绿色，因为没有全局的设计 token 约束。第三，响应式断点处理粗糙。很多 AI 生成的前端代码在移动端直接崩掉，因为模型没有真正理解不同屏幕尺寸下的布局逻辑。

impeccable 的思路是：既然模型本身不具备这些能力，那就通过外部约束来补足。它提供了一套设计规则描述文件，AI 在生成代码前会先读取这些规则，然后在规则的框架内进行创作。同时，配套的 CLI 工具可以帮你把规则注入到不同的 AI 编程环境中，浏览器扩展则用于实时预览和调试生成结果。

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

2.1 三层架构：规则层、工具层、验证层

impeccable 的架构设计并不复杂，但每一层都有明确的职责划分。

规则层是整个项目的基础。它包含了一系列 YAML 或 JSON 格式的设计规则文件，定义了颜色系统、间距系统、字体系统、组件规范等内容。这些规则不是凭空拍脑袋定的，而是参考了主流设计系统（如 Material Design、Ant Design、Tailwind 的默认配置）的最佳实践，经过裁剪和优化后形成的。规则文件的核心作用是给 AI 提供一个"设计上下文"，让它在生成代码时有据可依。

工具层是连接规则和 AI 编程环境的桥梁。它主要体现为一个 CLI 工具，你可以通过命令行把规则文件注入到不同的 AI coding agents 中。比如你用 Codex CLI 写代码，impeccable 的 CLI 可以把设计规则转换成 Codex 能理解的 prompt 前缀或者配置文件。如果你用的是浏览器扩展形态的 AI 编程工具，它也有对应的注入方式。

验证层负责检查 AI 生成的代码是否符合规则。它包含一个轻量级的 CSS 分析器，可以扫描生成的样式代码，找出偏离规则的地方，比如使用了未定义的色值、间距不在允许的刻度上、字体大小超出了规定范围等。验证层不是强制性的，但强烈建议开启，因为它能帮你快速定位问题。

2.2 为什么选择 CLI 作为主要交互方式

你可能会问：为什么不做成一个图形界面工具，非要搞 CLI？这不是增加使用门槛吗？

我实际用下来，CLI 的选择是合理的，原因有几个。首先，目标用户本身就是 CLI 的重度使用者。会用 Codex CLI、Trae CLI 的人，不会觉得多敲几行命令是什么负担。其次，CLI 更容易集成到现有工作流中。你可以在 package.json 的 scripts 里加一条命令，在构建前自动注入设计规则，整个过程无感。第三，CLI 的跨平台一致性更好。图形界面要考虑 Windows、macOS、Linux 的不同表现，CLI 基本不用操心这些。

当然，浏览器扩展的存在弥补了 CLI 在可视化方面的不足。扩展主要用于两个场景：一是实时预览 AI 生成的界面在不同设备上的表现，二是提供一个可视化的规则编辑器，让你不用手动改 YAML 文件就能调整设计参数。

2.3 与同类方案的差异化对比

市面上并不是没有类似的东西。Tailwind CSS 本身就有设计约束，一些 AI 编程工具也内置了前端生成的最佳实践。impeccable 的差异化在哪里？

从表格可以看出，impeccable 的定位非常明确：它不是给手写前端的人用的，而是给"用 AI 写前端"的人用的。这个定位决定了它的所有设计决策。

3. 核心细节解析与实操要点

3.1 设计规则文件的结构与关键参数

impeccable 的规则文件是整个工具的灵魂。我拿一个典型的规则文件来拆解，让你看看里面到底定义了什么。

# impeccable.config.yaml version: "1.0" design_tokens: colors: primary: base: "#2563EB" hover: "#1D4ED8" active: "#1E40AF" neutral: bg: "#FFFFFF" surface: "#F8FAFC" border: "#E2E8F0" text: "#0F172A" text_muted: "#64748B" spacing: scale: [4, 8, 12, 16, 24, 32, 48, 64] unit: "px" typography: font_family: "Inter, system-ui, sans-serif" sizes: xs: 12 sm: 14 base: 16 lg: 18 xl: 24 "2xl": 32 weights: [400, 500, 600, 700] radius: sm: 4 md: 8 lg: 12 full: 9999 shadows: sm: "0 1px 2px rgba(0,0,0,0.05)" md: "0 4px 6px rgba(0,0,0,0.07)" lg: "0 10px 15px rgba(0,0,0,0.1)"

这个文件里，spacing 的 scale 数组是最关键的参数之一。它定义了允许使用的间距值。AI 在生成 padding、margin、gap 时，只能从这个数组里取值。这就避免了"这次用 13px，下次用 17px"的混乱情况。我实测下来，把 scale 控制在 8 个值以内，AI 的遵守率最高。值太多，模型容易选错；值太少，又不够灵活。

colors 的分层结构也很有讲究。每个语义色（primary、neutral）下面分了 base、hover、active 等状态。这样 AI 在生成按钮、链接等交互元素时，就知道不同状态下该用什么颜色，而不是自己瞎猜。

注意：规则文件里的颜色值建议用十六进制，不要用 rgb() 或 hsl()。实测发现，部分 AI 模型对十六进制的识别准确率更高，生成的代码也更干净。

3.2 CLI 工具的安装与初始化

impeccable 的 CLI 安装方式很直接。如果你有 Node.js 环境（建议 18 以上），一条命令搞定：

npm install -g impeccable-cli

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

impeccable init

这个命令会做几件事：生成默认的impeccable.config.yaml文件、在当前目录创建.impeccable缓存文件夹、检测你正在使用的 AI 编程工具并给出集成建议。

初始化过程中，CLI 会问你几个问题，比如"你主要使用哪个 AI 编程工具"、"你的项目类型是什么"。这些问题不是随便问的，它们决定了后续规则注入的方式。比如你选了 Codex CLI，它就会在~/.codex/目录下生成对应的配置文件片段；如果你选了 Trae CLI，处理方式又不一样。

# 查看当前项目的 impeccable 状态 impeccable status # 输出示例 # Project: my-app # Config: impeccable.config.yaml (valid) # AI Tool: codex-cli (detected) # Rules injected: yes # Last sync: 2024-01-15 10:30:00

status命令是我用得最频繁的，它能快速告诉我规则有没有正确注入、配置文件有没有语法错误。特别是在切换 AI 工具或者修改规则后，跑一下这个命令能省很多排查时间。

3.3 规则注入的三种模式

impeccable 支持三种规则注入模式，分别适用于不同的使用场景。

模式一：Prompt 前缀注入。这是最轻量的方式。CLI 会把设计规则压缩成一段简短的 prompt，在你每次向 AI 提问时自动附加在前面。优点是无需修改 AI 工具的配置，缺点是每次请求都会消耗额外的 token。

模式二：配置文件注入。CLI 直接修改 AI 工具的配置文件，把设计规则写入系统提示词或者项目级配置中。优点是 token 消耗少，缺点是不同 AI 工具的配置文件格式不同，需要 impeccable 做适配。

模式三：项目文件注入。在项目根目录生成一个DESIGN_RULES.md文件，AI 工具在读取项目上下文时会自动加载。这种方式最通用，几乎支持所有 AI 编程工具，但依赖 AI 工具是否会自动读取项目文件。

我个人的建议是：优先用模式二，备选模式三，模式一作为临时方案。模式二的体验最无缝，模式三的兼容性最好。模式一虽然简单，但长期用下来 token 成本不低。

# 切换注入模式 impeccable inject --mode config impeccable inject --mode file impeccable inject --mode prompt

3.4 浏览器扩展的安装与核心功能

浏览器扩展是 impeccable 的可视化入口。目前支持 Chrome 和 Edge，Firefox 版本还在开发中。安装方式有两种：从商店直接安装，或者下载源码后以开发者模式加载。

扩展的核心功能有三个：

实时预览面板。当你在本地开发服务器上运行项目时，扩展会在页面侧边打开一个面板，展示当前页面使用的设计 token 统计。比如用了哪些颜色、间距值的分布情况、字体大小的范围等。这个面板能帮你快速发现"AI 又乱用颜色了"这类问题。

规则编辑器。不想手动改 YAML 文件的话，可以在扩展里可视化地调整设计参数。改完后点击"同步"，扩展会通过本地端口把变更写回impeccable.config.yaml。

偏离高亮。扩展会扫描页面上的元素，把不符合规则的样式用红色边框标出来。鼠标悬停可以看到具体的偏离信息，比如"使用了未定义的色值 #FF5733"。

提示：偏离高亮功能在开发阶段很有用，但建议在生产构建时关闭，避免影响性能。可以在扩展设置里配置"仅在 localhost 生效"。

4. 实操过程与核心环节实现

4.1 从零搭建一个 AI 前端项目的完整流程

我拿一个实际项目来演示完整流程。假设我们要用 Codex CLI 做一个简单的任务管理界面。

第一步：项目初始化。

mkdir task-manager && cd task-manager npm init -y npm install -D impeccable-cli npx impeccable init

初始化时选择"Codex CLI"作为目标工具，项目类型选"Web App"。CLI 会生成默认配置并自动注入规则。

第二步：调整设计规则。

默认规则不一定符合你的审美。打开impeccable.config.yaml，我通常会改这几个地方：把 primary 颜色改成品牌色、调整 spacing scale 让间距更紧凑、把字体换成项目实际使用的字体。

design_tokens: colors: primary: base: "#7C3AED" # 改成紫色 spacing: scale: [4, 8, 16, 24, 32, 48] # 精简刻度 typography: font_family: "Geist, system-ui, sans-serif"

改完后跑一下impeccable validate，确保配置文件没有语法错误。

第三步：验证规则注入。

impeccable status

确认输出里显示 "Rules injected: yes"。如果没有，手动执行impeccable inject --mode config。

第四步：用 AI 生成前端代码。

现在打开 Codex CLI，输入你的需求。比如：

创建一个任务列表页面，包含： - 顶部标题栏，显示"我的任务" - 任务列表，每个任务有复选框、标题、删除按钮 - 底部添加任务的输入框和按钮 - 整体使用卡片式布局，圆角，浅色背景

因为规则已经注入，Codex 生成的代码会自动使用你定义的颜色、间距和字体。我实测下来，生成结果的视觉一致性比不注入规则时提升非常明显。

第五步：验证生成结果。

impeccable scan ./src

这个命令会扫描源码中的样式，输出偏离报告：

Scan Report =========== Files scanned: 12 Deviations found: 3 1. src/components/TaskItem.css:15 - Color #FF6B6B not in design tokens - Suggested: use primary.base or define new token 2. src/components/Header.css:8 - Spacing value 20px not in scale - Suggested: use 16px or 24px 3. src/App.css:22 - Font size 15px not in typography.sizes - Suggested: use 14px (sm) or 16px (base)

根据报告逐条修复，或者把合理的偏离值补充到规则文件中。

4.2 参数计算：如何确定合适的间距刻度

间距刻度的设计不是拍脑袋决定的。我分享一个实际计算过程。

假设你的基础字号是 16px，那么一个舒适的阅读行高大约是 1.5 倍，即 24px。段落之间的间距通常是行高的 0.5 到 1 倍，即 12px 到 24px。组件内部的 padding 通常是 8px 到 16px。组件之间的间距通常是 16px 到 32px。

把这些值整理成一套刻度，我推荐用4px 基准的倍数，但不要所有倍数都用，而是选取几个关键值：

这套刻度覆盖了绝大多数场景，而且值之间的比例关系比较协调。AI 在使用时，选择范围有限，出错的概率就低。

4.3 浏览器扩展的调试技巧

浏览器扩展用得好，能省很多事。我分享几个实际使用中的技巧。

技巧一：用"仅显示偏离"模式快速定位问题。在扩展面板里开启这个模式后，页面上符合规则的元素会变淡，不符合的会高亮。这样一眼就能看出问题在哪里。

技巧二：利用 token 使用统计优化规则。扩展会统计每个 token 的使用频率。如果某个颜色或间距值从来没被用过，说明规则定义冗余了，可以删掉。如果某个值被频繁使用但不在规则里，说明规则需要补充。

技巧三：导出偏离报告给 AI 修复。扩展支持把偏离报告导出为 Markdown 格式。你可以直接把这份报告粘贴给 AI，让它根据报告修复代码。这比手动描述问题高效得多。

# 导出偏离报告 impeccable scan ./src --format markdown --output report.md

4.4 与不同 AI 编程工具的集成细节

impeccable 目前对主流 AI 编程工具的支持程度不一样，我整理了一个对照表：

对于 Codex CLI 用户，有一个细节需要注意：Codex 的配置文件在~/.codex/config.json，impeccable 会在这个文件里添加一个design_context字段。如果你之前手动改过这个文件，注入前最好备份一下。

对于 Trae CLI 用户，impeccable 会在项目根目录生成.trae/design-rules.md文件。你需要确保 Trae 的项目设置里开启了"读取项目文档"选项，否则规则不会被加载。

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

5.1 规则注入后 AI 不遵守怎么办

这是被问得最多的问题。我总结了几种可能的原因和对应的排查方法。

原因一：规则文件格式错误。YAML 对缩进非常敏感，一个空格不对就可能导致解析失败。跑impeccable validate可以快速检查。

原因二：注入模式不匹配。比如你用的是 Trae CLI，但注入模式设成了 config，而 Trae 的配置文件格式 impeccable 还没适配。这时候换成 file 模式通常能解决。

原因三：AI 工具的上下文窗口不够。设计规则本身会占用 token，如果规则文件太大，加上你的项目代码，可能超出了模型的上下文限制。解决办法是精简规则文件，只保留最核心的 token 定义。

原因四：Prompt 优先级问题。有些 AI 工具会把系统提示词的优先级设得很高，导致注入的设计规则被忽略。这种情况下，可以尝试把规则以"用户消息"的形式发送，而不是系统提示。

实操心得：我遇到过一次怎么都不生效的情况，最后发现是 Codex CLI 的版本太旧，不支持自定义配置字段。升级到最新版后问题消失。所以排查时先确认工具版本。

5.2 生成的界面在移动端错乱

AI 生成响应式布局时，最常见的错误是断点设置不合理。impeccable 的规则文件里可以定义断点：

breakpoints: sm: 640 md: 768 lg: 1024 xl: 1280

但光定义断点不够，还需要在规则里明确告诉 AI 每个断点下的布局行为。我通常会在规则文件里加一段自然语言描述：

responsive_rules: - "在 sm 断点以下，所有多列布局改为单列" - "在 md 断点以下，侧边栏隐藏，通过汉堡菜单访问" - "字体大小在移动端整体缩小一档"

这些描述会被转换成 prompt 的一部分，引导 AI 生成正确的响应式代码。

5.3 常见问题速查表

5.4 几个容易踩的坑

坑一：规则文件过度设计。一开始就想定义一套完美的设计系统，结果规则文件几百行，AI 反而无所适从。建议从最小可用规则开始，逐步迭代。

坑二：忽略 AI 工具的版本差异。不同版本的 Codex CLI 对配置文件的处理方式可能不同。升级工具后，记得重新跑一次impeccable inject。

坑三：把 impeccable 当成万能药。它解决的是"设计一致性"问题，不解决"设计创意"问题。如果你的需求是"做一个惊艳的 landing page"，impeccable 帮不了你太多。它的强项是让常规界面保持专业水准。

坑四：忘记同步规则变更。改了impeccable.config.yaml后，需要重新执行注入命令，否则 AI 用的还是旧规则。我建议在 package.json 里加一个 watch 脚本：

{ "scripts": { "design:watch": "impeccable watch" } }

这样规则文件一改，注入自动更新。

6. 进阶用法与扩展思路

6.1 多项目共享设计规则

如果你同时维护多个项目，希望它们共用一套设计规则，可以这样做：把impeccable.config.yaml放在一个公共目录，然后在各项目的配置文件里引用它。

# 项目级配置 extends: "../shared-design/impeccable.config.yaml" overrides: colors: primary: base: "#059669" # 项目特定覆盖

extends字段会先加载公共规则，然后overrides里的内容会覆盖对应字段。这样既保持了统一性，又允许项目差异化。

6.2 结合设计稿自动生成规则

如果你有 Figma 设计稿，可以导出设计 token 的 JSON 文件，然后写一个简单的转换脚本，把 Figma 的 token 格式转成 impeccable 的规则格式。这样设计稿一更新，规则文件也跟着更新，AI 生成的代码始终和设计稿保持一致。

// figma-to-impeccable.js const figmaTokens = require('./figma-tokens.json'); const impeccableConfig = { version: '1.0', design_tokens: { colors: {}, spacing: { scale: [], unit: 'px' }, typography: { sizes: {}, weights: [] } } }; // 转换颜色 Object.entries(figmaTokens.colors).forEach(([name, value]) => { impeccableConfig.design_tokens.colors[name] = { base: value.value }; }); // 转换间距 const spacingValues = Object.values(figmaTokens.spacing) .map(t => parseInt(t.value)) .sort((a, b) => a - b); impeccableConfig.design_tokens.spacing.scale = spacingValues; console.log(JSON.stringify(impeccableConfig, null, 2));

这个脚本的思路很简单：读取 Figma 导出的 token JSON，按照 impeccable 的格式重新组织，然后输出 YAML 或 JSON 文件。实际使用时，你可能需要根据 Figma 导出的具体结构调整字段映射。

6.3 在 CI 流程中加入设计规则检查

团队协作时，可以在 CI 流程里加一步 impeccable 扫描，防止有人提交偏离设计规则的代码。

# .github/workflows/design-check.yml name: Design Rule Check on: [pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g impeccable-cli - run: impeccable scan ./src --fail-on-deviation

--fail-on-deviation参数会让扫描在发现偏离时返回非零退出码，从而让 CI 步骤失败。这样偏离设计规则的代码就无法合并到主分支。

注意：这个检查建议只对新增或修改的文件生效，不要全量扫描，否则历史遗留问题会导致 CI 一直失败。impeccable 支持--diff-only参数，只扫描 Git diff 中的文件。

6.4 规则文件的版本管理策略

设计规则不是一成不变的。随着项目迭代，你可能需要调整颜色、增加间距值、修改字体。我建议把规则文件纳入 Git 管理，并且遵循语义化版本：

• 主版本号：不兼容的规则变更，比如删除了某个颜色 token
• 次版本号：新增规则，比如增加了新的间距值
• 修订号：微调，比如修改了某个颜色的具体色值

每次规则变更时，在 commit message 里写清楚变更内容和原因。这样当 AI 生成的代码出现问题时，可以快速回溯是不是规则变更导致的。

7. 个人实操体会与建议

用了几个月 impeccable，我最大的感受是：它把"AI 写前端"这件事从"能用"提升到了"能看"。以前用 Codex CLI 生成一个页面，功能对了但样式得自己调半天。现在生成出来基本就能用，只需要微调细节。

不过它也不是没有局限。规则文件的设计需要一定的设计基础，如果你完全不懂设计，可能连规则都写不明白。另外，它对 AI 工具的版本比较敏感，工具升级后偶尔需要重新适配。

我个人的建议是：先从默认规则用起，跑通整个流程后，再根据自己的审美逐步调整。不要一上来就追求完美规则，那样容易陷入"调规则"而不是"写代码"的陷阱。规则是为了服务开发效率的，不是反过来。

另外一个小技巧：如果你同时用多个 AI 编程工具，可以给每个工具单独建一个规则文件，放在不同的目录里。比如rules/codex.yaml、rules/trae.yaml，然后在项目里通过impeccable inject --config rules/codex.yaml指定使用哪个。这样切换工具时不用改来改去。

最后再分享一个我踩过的坑：不要在规则文件里写太抽象的描述。比如"使用现代感的设计"这种话，AI 理解不了。规则要具体到数值和明确的指令，比如"卡片圆角使用 12px"、"主色调使用 #2563EB"。越具体，AI 的执行越准确。