1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI 帮你写一段前端代码它给你吐出来一坨能跑但丑得离谱的东西——间距全靠猜、颜色像打翻的调色盘、响应式布局在手机上直接散架。你反复调 prompt它反复给你“差不多但就是不对”的结果。这个痛点凡是重度用过 AI coding agents 的人都懂。impeccable 这个词本身的意思是“无可挑剔的、完美的”放在前端设计语境里它指向的其实是一个非常明确的目标让 AI 生成的前端界面达到“无可挑剔”的视觉与交互水准。结合热搜词里的 AI coding agents、frontend design、CLI、browser extension可以基本判断出这个项目的定位——它是一套围绕 AI 编码代理的前端设计增强方案通过命令行工具和浏览器扩展两种形态把“设计品味”这件事注入到 AI 的代码生成流程里。说白了它想干的事是在你和 AI coding agent 之间插一层“设计规范翻译器”。你不需要成为设计师也不需要背一堆设计系统文档AI 也不需要凭空猜测什么叫“好看”。impeccable 把设计规则、间距体系、配色逻辑、组件规范这些东西结构化让 AI 能直接消费。这篇文章适合谁看三类人第一类是用 Cursor、Codex CLI、Claude Code 这类工具写前端但总被 UI 质量困扰的开发者第二类是想把 AI 生成界面纳入团队设计规范的前端负责人第三类是对 CLI 工具链和浏览器扩展协同工作方式感兴趣的技术玩家。不管你是刚接触 AI coding 的新手还是已经踩过一堆坑的老手下面这些内容应该都能让你少走点弯路。2. 核心设计思路拆解为什么是 CLI 加浏览器扩展这套组合2.1 为什么不是纯 prompt 方案很多人第一反应是我直接在 prompt 里写清楚设计规范不就行了我试过结论是——能解决 20% 的问题剩下 80% 会在规模化时崩掉。原因很简单。prompt 是线性的、一次性的上下文你每次让 AI 生成一个新组件都得把整套设计规范重新塞一遍。规范短了没用规范长了 token 爆炸而且 AI 对长上下文里的规则遵循度会随着对话轮次增加而衰减。更致命的是不同的人写 prompt 的方式不一样团队协作时根本没法保证一致性。impeccable 的思路是把设计规范从“对话上下文”里抽出来变成一个独立的、可版本管理的、机器可读的配置层。CLI 负责在本地项目里初始化、校验、同步这套配置浏览器扩展负责在可视化层面做实时预览和反馈。两者共享同一份设计 token 源。2.2 CLI 的角色把设计系统变成可执行文件CLI 在这个项目里承担的是“基础设施”角色。它做的事情包括初始化设计配置在你的项目根目录生成一份结构化的设计规范文件通常包含颜色、字体、间距、圆角、阴影、断点等 token。校验一致性扫描你现有的代码检查是否有硬编码的颜色值、不规范的间距、偏离设计系统的组件用法。为 AI agent 提供上下文生成一份 AI 可读的“设计上下文文件”当 AI coding agent 工作时自动引用这份文件而不是靠猜。我实测下来这个环节最关键的价值是把隐性的设计决策显性化。以前团队里“这个按钮用 8px 还是 12px 间距”靠口头约定现在变成配置文件里的一行AI 和人都得遵守。2.3 浏览器扩展的角色所见即所得的反馈闭环光有 CLI 还不够因为设计这件事本质上是视觉的。你在终端里看一堆 token 定义很难判断实际渲染出来好不好看。浏览器扩展补的就是这一环。它的典型工作方式是当你在本地开发环境跑起页面时扩展会注入一个轻量的检查层实时标注出哪些元素偏离了设计规范——比如某个卡片的 padding 不在允许的刻度上某个文字颜色对比度不达标某个组件的圆角值和设计系统不一致。你点一下就能看到建议的修正值甚至可以直接把修正指令回传给 AI agent。这套“CLI 定规则、扩展做反馈”的组合本质上是在 AI 编码流程里建立了一个设计质量的持续集成机制。不是生成完再人工 review而是在生成过程中就有约束和反馈。2.4 和主流 AI coding agents 的协作方式热搜词里出现了 codex cli、zcode cli 这些工具名说明 impeccable 的设计目标之一就是和这些主流 agent 无缝配合。它的协作模式通常是你在项目里用 impeccable CLI 初始化设计配置。CLI 生成一份 agent 可读的上下文文件比如.impeccable/context.md或类似的约定路径。当 codex cli 或同类工具工作时通过项目级配置自动加载这份上下文。AI 生成的代码天然遵循设计规范浏览器扩展做最终校验。这个流程的好处是对 AI agent 本身零侵入。你不需要改 agent 的源码也不需要写复杂的插件只需要让项目里存在 impeccable 的配置文件agent 读取项目上下文时自然会带上。3. 核心细节解析与实操要点3.1 设计 token 的粒度怎么定这是我在实际使用中踩的第一个坑。token 定得太粗AI 还是会乱来定得太细配置文件维护成本爆炸而且 AI 在生成时容易“选择困难”。我的经验是采用三层粒度层级示例用途基础层color-blue-500: #3B82F6原始值不直接用于组件语义层color-primary: {color-blue-500}组件引用的语义变量组件层button-primary-bg: {color-primary}具体组件的绑定基础层和语义层是必须的组件层可选。对于大多数项目语义层是 AI 消费的主要接口。你告诉 AI“主按钮背景用 color-primary”比告诉它“用 #3B82F6”要好得多因为前者在换主题时不用改代码。注意不要把所有 Figma 里的变量都搬进来。只保留 AI 生成代码时真正需要引用的那部分通常 30 到 50 个语义 token 就够了。超过 80 个AI 的遵循度会明显下降。3.2 间距体系的刻度设计间距是前端设计里最容易被 AI 搞砸的部分。AI 特别喜欢用 5px、7px、13px 这种“看起来差不多”的值导致整个界面节奏感全无。impeccable 的配置里间距通常采用基于基准值的倍数刻度。常见的有 4px 基准和 8px 基准两种。我的建议是移动端优先的项目用 4px 基准4, 8, 12, 16, 20, 24, 32, 40, 48, 64桌面端为主的项目用 8px 基准8, 16, 24, 32, 40, 48, 64, 80, 96关键点是刻度数量要克制。我见过有人定义了 20 个间距值结果 AI 每次都在相邻的两个值之间反复横跳。10 个以内的刻度AI 的选择准确率会高很多。3.3 颜色对比度的自动校验浏览器扩展里有一个我觉得非常实用的功能实时对比度检查。它会根据 WCAG 标准标注出文字和背景对比度不足的地方。这个功能的价值在于AI 生成配色时经常“看起来还行但实际不达标”。比如浅灰文字配白底视觉上能看清但对比度只有 2.5:1远低于 4.5:1 的 AA 标准。扩展会直接标红并给出建议的加深值。实操中我建议把对比度校验设为警告级别而非错误级别。因为有些设计场景比如禁用状态的按钮本来就不需要满足 AA 标准一刀切会误报太多。3.4 和现有项目的集成策略如果你是在一个已经有设计系统的项目里引入 impeccable不要一上来就全量替换。我的做法是渐进式集成先用 CLI 的扫描功能跑一遍现有代码生成一份“偏离报告”。从新开发的页面开始应用 impeccable 配置老页面不动。等新页面的流程跑顺了再逐步迁移老页面。这样做的原因是全量替换会一次性产生大量 diffreview 成本极高而且容易引入回归 bug。渐进式集成让团队有个适应过程也能在实践中调整配置。4. 实操过程与核心环节实现4.1 环境准备与 CLI 安装假设你用的是 Node.js 生态的项目CLI 的安装通常通过包管理器完成。以下是我实测的流程# 在项目根目录初始化 npx impeccable init # 或者全局安装 npm install -g impeccable-cli impeccable init初始化过程中CLI 会问你几个问题项目类型React/Vue/原生、设计基准4px 还是 8px、是否启用对比度检查、是否生成 AI 上下文文件。根据你的实际情况选就行。初始化完成后项目根目录会多出一个.impeccable/目录结构大致如下.impeccable/ tokens.json # 设计 token 定义 rules.json # 校验规则 context.md # 给 AI agent 读的上下文 config.json # 项目级配置4.2 设计 token 文件的编写tokens.json是整个体系的核心。我拿一个实际项目的片段举例{ color: { blue: { 500: #3B82F6, 600: #2563EB }, gray: { 100: #F3F4F6, 500: #6B7280, 900: #111827 } }, semantic: { primary: {color.blue.500}, primary-hover: {color.blue.600}, text-default: {color.gray.900}, text-muted: {color.gray.500}, bg-subtle: {color.gray.100} }, spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, 2xl: 48px }, radius: { sm: 4px, md: 8px, lg: 16px, full: 9999px } }这里有个细节值得说语义层用{color.blue.500}这种引用语法而不是直接写十六进制值。这样当你需要调整品牌色时只改基础层所有语义层自动跟着变。AI 在生成代码时引用的是语义层所以它不需要知道具体色值。4.3 生成 AI 上下文文件context.md是给 AI coding agent 读的。CLI 会根据tokens.json自动生成但你可以手动补充一些自然语言的说明。我的context.md大致长这样# 设计系统上下文 ## 颜色使用规则 - 主按钮背景使用 semantic.primaryhover 状态使用 semantic.primary-hover - 正文文字使用 semantic.text-default辅助文字使用 semantic.text-muted - 页面背景使用白色卡片背景使用 semantic.bg-subtle ## 间距规则 - 组件内部 padding 优先使用 spacing.sm 或 spacing.md - 组件之间的间距使用 spacing.md 或 spacing.lg - 页面级区块间距使用 spacing.xl 或 spacing.2xl ## 圆角规则 - 按钮和输入框使用 radius.md - 卡片使用 radius.lg - 头像和标签使用 radius.full ## 禁止事项 - 禁止硬编码颜色值 - 禁止使用不在 spacing 刻度中的间距值 - 禁止使用不在 radius 刻度中的圆角值这份文件的关键是用自然语言把规则说清楚而不是只丢一堆 JSON。AI 对自然语言规则的理解和遵循度明显高于纯结构化数据。4.4 浏览器扩展的安装与配置浏览器扩展的安装方式取决于你用的浏览器。以 Chromium 系为例通常是从扩展商店安装或者加载开发者模式下的本地包。安装完成后你需要在扩展的设置里填入本地开发服务器的地址通常是http://localhost:3000或类似。扩展会自动检测页面上的元素并根据.impeccable/tokens.json做校验。我实测下来扩展的校验延迟在 200ms 左右基本不影响开发体验。它会在页面上叠加一层半透明的标注偏离规范的元素会显示黄色或红色边框鼠标悬停能看到具体的偏离项和建议值。4.5 和 codex cli 的联动配置如果你用的是 codex cli 这类工具联动配置通常是在项目级配置文件里指定上下文路径。以常见的约定为例{ context: { files: [.impeccable/context.md], autoLoad: true } }配置好之后每次 codex cli 在这个项目里工作时会自动读取context.md生成的前端代码就会遵循设计规范。我实测过加了这份上下文之后AI 生成代码中硬编码颜色值的比例从 60% 降到了 5% 以下。4.6 校验与修复流程日常开发中我建议把 impeccable 的校验命令加到 pre-commit hook 里# 校验当前改动 impeccable check # 自动修复可修复的问题 impeccable fixcheck命令会扫描改动文件输出偏离报告。fix命令能自动替换硬编码值为 token 引用但不能自动修复布局和间距问题那些需要人工判断。我的习惯是提交前跑一次check如果有硬编码颜色或间距先跑fix剩下的手动处理。这样能保证进入代码库的代码至少在设计 token 层面是干净的。5. 常见问题与排查技巧实录5.1 AI 不遵循上下文文件怎么办这是最高频的问题。可能的原因和排查思路现象可能原因排查方法AI 完全忽略 context.md上下文文件未被加载检查 agent 配置里的 context 路径是否正确AI 部分遵循上下文太长规则被稀释精简 context.md只保留核心规则AI 遵循但生成结果仍不对token 定义有歧义检查语义 token 的命名是否清晰时好时坏对话轮次过多上下文衰减开新对话或把规则放在对话开头我的经验是context.md 控制在 500 字以内效果最好。超过 1000 字AI 的遵循度会明显下降。如果规则确实多拆成多个文件按需加载。5.2 浏览器扩展不显示标注排查顺序确认扩展已启用且当前页面在扩展的生效域名列表里。确认本地开发服务器正在运行且扩展配置的地址正确。打开浏览器开发者工具看 Console 里有没有扩展相关的报错。检查.impeccable/tokens.json是否是合法 JSON格式错误会导致扩展静默失败。我踩过的一个坑是项目用了 CSS-in-JS 方案样式是运行时注入的扩展在页面加载时扫描不到。解决办法是在扩展设置里开启“动态监听”模式它会用 MutationObserver 持续监控 DOM 变化。5.3 间距校验误报太多如果你发现扩展把大量正常元素标为间距违规通常是两个原因刻度太密相邻刻度值差距太小AI 和人都容易选错。建议刻度之间至少差 4px。容差太小扩展默认容差可能是 0px实际项目中允许 1-2px 的偏差。在配置里把容差调到 2px误报会大幅减少。5.4 和现有 CSS 框架冲突如果你的项目用了 Tailwind 这类原子化 CSS 框架impeccable 的 token 需要和框架的配置做映射。常见做法是在 Tailwind 配置里引用 impeccable 的 token// tailwind.config.js const tokens require(./.impeccable/tokens.json); module.exports { theme: { extend: { colors: tokens.semantic, spacing: tokens.spacing, borderRadius: tokens.radius } } };这样两边共享同一份 token 源不会出现“框架里一套值、impeccable 里另一套值”的混乱。5.5 团队协作时的配置同步多人协作时.impeccable/目录必须纳入版本控制。但config.json里可能有个人偏好设置比如是否开启声音提示这部分应该加到.gitignore里或者拆分成config.json团队共享和config.local.json个人覆盖。我建议的做法是tokens.json、rules.json、context.md纳入版本控制config.json只保留团队级配置个人配置走本地覆盖文件。6. 我个人的使用体会与几个实用建议用了一段时间之后我最大的感受是impeccable 解决的不是“AI 会不会写代码”的问题而是“AI 写出来的代码符不符合设计意图”的问题。这两个问题的解法完全不同。前者靠模型能力后者靠约束机制。几个我踩过坑之后总结的建议第一不要追求 100% 的自动遵循。设计这件事本身就有主观判断的成分AI 能遵循 80% 的硬性规则颜色、间距、圆角剩下 20% 的软性判断视觉层次、留白节奏还是需要人来把关。把 impeccable 当成“设计 lint 工具”而不是“设计自动驾驶”心态会好很多。第二token 命名要用人话。我见过有人用color-1、color-2这种命名AI 根本不知道什么时候该用哪个。改成color-primary、color-danger、color-success之后AI 的选择准确率明显提升。命名本身就是一种文档。第三定期回顾 context.md。项目演进过程中设计规范会变但 context.md 经常被遗忘。我现在的习惯是每个 sprint 结束时花 10 分钟过一遍 context.md把过时的规则删掉把新出现的模式加进去。这份文件的新鲜度直接决定了 AI 生成代码的质量。第四浏览器扩展的对比度检查别关。虽然有时候会误报但它确实帮我抓到了不少可访问性问题。尤其是做面向公众的产品时对比度不达标是实打实的用户体验问题早发现早修复。这个项目后续还可以往几个方向扩展比如把设计 token 和 Figma 变量做双向同步让设计师和开发者在同一套源上工作或者增加一个“设计回归测试”功能在 CI 里跑视觉 diff防止 AI 生成的代码在迭代中悄悄偏离设计规范。这些方向我自己也在摸索有进展了再分享。