1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个词被拿来命名一个前端设计相关的工具我的反应是这名字起得挺狂。impeccable 在英文里是“无可挑剔的、零瑕疵的”意思一个工具敢叫这个名字要么是营销噱头要么是真的在某个环节上做到了极致。我花了一段时间去研究它背后的逻辑结论是它瞄准的是 AI coding agents 时代一个非常具体、非常痛的痛点——AI 写出来的前端代码功能能跑但设计感一塌糊涂。你如果用过 codex cli、claude code 这类 AI coding agent 来生成前端页面一定有过这种体验让它写一个登录页它给你一个能用的表单但配色是默认蓝、间距是随意的、字体是系统默认的、圆角要么没有要么大得离谱。功能上没毛病但离“能拿给用户看”差了十万八千里。impeccable 就是冲着这个 gap 来的。它本质上是一套给 AI coding agents 用的前端设计规范层通过 CLI 工具和浏览器扩展两种形态让 AI 在生成前端代码时能遵循一套经过打磨的设计系统而不是每次从零开始瞎猜。这篇文章我会从几个角度把它拆开讲清楚它为什么存在、核心机制是什么、CLI 和浏览器扩展分别怎么用、和 codex cli 这类工具怎么配合、实际用下来哪些地方真香哪些地方要绕路。适合两类人看一是已经在用 AI coding agents 写前端、但被设计质量困扰的开发者二是想了解 AI 辅助前端设计这个方向目前走到哪一步的技术人。不管你是刚接触 codex cli 还是已经用了一段时间应该都能从里面找到能直接抄作业的东西。2. 为什么 AI 写的前端总是“差一口气”2.1 AI coding agents 的默认审美困境要理解 impeccable 的价值得先理解 AI coding agents 在生成前端代码时的默认行为模式。我用 codex cli 和几个同类工具做过大量测试发现一个规律AI 生成前端代码时会优先保证“结构正确”和“功能可用”设计层面的决策基本是随机的。你让它写一个卡片组件它会给你一个 div 套 div加上 padding 和 border颜色用默认值或者随便挑一个十六进制。它不会考虑这个卡片和页面上其他元素的比例关系、不会考虑色彩对比度是否达标、不会考虑响应式断点该怎么设。这不是 AI 笨而是它的训练目标决定的。代码生成模型见过的代码里功能正确的代码远多于设计精良的代码。GitHub 上大量前端项目本身就是“能跑就行”的水平AI 学到的“平均前端”自然也就是那个水平。你让它生成一个按钮它给你的是互联网上按钮的“中位数”而不是“优秀样本”。2.2 设计系统缺失导致的重复劳动更麻烦的是每次让 AI 生成新页面它都会重新做一遍设计决策。今天生成的登录页用了一套间距明天生成的后台页用了另一套。整个项目做下来你会发现有七八种不同的圆角值、五六种不同的灰色、三四套不同的字体大小。这不是 AI 的错是你没给它一个约束框架。传统做法是搞一套 design token写进 tailwind config 或者 CSS 变量里然后要求 AI 遵循。但实际操作过的人都知道你很难在 prompt 里把整套设计系统说清楚AI 也不会每次都老老实实去读你的 config 文件。impeccable 的思路是把设计规范做成一个 AI 可以直接调用的工具层而不是靠 prompt 里写一堆约束。2.3 impeccable 的切入角度impeccable 的做法和传统 design system 不太一样。它不是给你一套 CSS 框架让你去用而是给 AI coding agents 提供一个“设计决策接口”。当 AI 需要决定一个间距值时它不去猜而是通过 impeccable 提供的机制拿到一个经过验证的值。当 AI 需要选一个颜色时它从一套调好的色板里取而不是随机生成。这个思路的关键在于把设计决策从“生成”变成“选择”。生成是发散的、不可控的选择是收敛的、可预期的。AI 擅长的是根据上下文做选择而不是从零创造一套协调的设计。impeccable 就是给 AI 提供了一个足够好的选择空间。3. impeccable 的核心机制拆解3.1 CLI 形态给 AI agent 的设计工具包impeccable 的 CLI 形态是我用得最多的。它的基本逻辑是你把它装到项目里然后在 AI coding agent 的工作流中调用它。具体来说它提供了一组命令AI 可以通过这些命令获取设计决策。比如当 AI 需要确定一个页面的间距体系时它可以调用 impeccable 的 spacing 命令拿到一套基于 4px 或 8px 基准的间距值。当它需要配色时调用 color 命令拿到一套已经调好对比度和和谐度的色板。这些值不是硬编码的而是根据项目类型、品牌调性等参数动态生成的。我实测下来这个机制最大的好处是一致性。同一个项目里不管 AI 生成多少个页面只要它走 impeccable 的接口拿设计值出来的东西就是协调的。不会出现这个页面圆角 8px、那个页面圆角 12px 的情况。3.2 浏览器扩展形态实时预览与调优浏览器扩展是 impeccable 另一个有意思的形态。它的作用是在你浏览 AI 生成的页面时实时显示设计层面的问题。比如对比度不达标的地方会标红、间距不一致的地方会高亮、字体层级混乱的地方会给出提示。这个功能对于调试阶段特别有用。AI 生成完页面后你打开浏览器扩展一眼就能看出哪些地方“不对劲”。不用靠肉眼去比对也不用打开 devtools 一个个查。扩展会直接告诉你这个按钮的文字对比度只有 3.2:1低于 WCAG AA 标准的 4.5:1这个卡片的 padding 是 13px不在你的间距体系里。更实用的是扩展还能给出修复建议。它会告诉你把对比度调到多少、把 padding 改成哪个值。这些建议可以直接复制也可以让 AI agent 自动应用。3.3 和 codex cli 的配合方式codex cli 是目前最流行的 AI coding agent 之一impeccable 和它的配合是我重点测试的场景。基本流程是这样的你在项目里装好 impeccable然后在 codex cli 的配置里加上对 impeccable 的调用。当 codex cli 生成前端代码时它会先通过 impeccable 获取设计决策再生成代码。具体配置上你需要在项目的根目录放一个 impeccable 的配置文件定义项目的基本设计参数主色、字体、间距基准、圆角风格等。codex cli 在生成代码前会读这个配置然后通过 impeccable 的 CLI 接口拿到具体的值。我试过对比同一个 prompt不用 impeccable 时 codex cli 生成的页面需要大量手动调整用了 impeccable 之后生成的页面基本能直接看只需要微调个别地方。效率差距大概在 3 到 5 倍。4. 实操从零搭建 impeccable 工作流4.1 环境准备与安装先说安装。impeccable 的 CLI 是通过 npm 分发的所以你需要先有 Node.js 环境。如果你还没装 Node建议用 nvm 来管理版本避免权限问题。# 安装 nvm如果还没装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 安装 Node.js LTS 版本 nvm install --lts nvm use --lts # 验证安装 node -v npm -vNode 装好之后安装 impeccable CLI# 全局安装 npm install -g impeccable-cli # 或者作为项目依赖安装推荐 npm install --save-dev impeccable-cli我建议作为项目依赖安装因为 impeccable 的配置是跟着项目走的全局安装容易在不同项目之间产生版本冲突。安装完成后初始化配置文件npx impeccable init这个命令会在项目根目录生成一个impeccable.config.js文件里面是默认的设计参数。你可以根据项目需求修改。4.2 配置文件详解配置文件是 impeccable 的核心。它决定了 AI 能拿到什么样的设计决策。默认配置长这样module.exports { // 间距基准建议 4 或 8 spacingBase: 4, // 圆角风格sharp / subtle / rounded / pill radiusStyle: subtle, // 主色调 primaryColor: #2563eb, // 字体栈 fontFamily: { sans: [Inter, system-ui, sans-serif], mono: [JetBrains Mono, monospace] }, // 字体缩放比例 typeScale: 1.25, // 对比度标准AA / AAA contrastStandard: AA };几个关键参数的选择逻辑spacingBase选 4 还是 8取决于你的项目密度。后台管理系统、数据密集型界面建议用 4因为需要更精细的间距控制。营销页面、展示型网站建议用 8视觉上更舒展。我一般默认用 4需要大间距时用 4 的倍数就行。radiusStyle直接影响产品的视觉调性。sharp 适合工具类、专业类产品subtle 是万能选择4-6px 的圆角不突兀也不死板rounded 适合消费类、社交类产品pill 就是完全圆角适合按钮和标签。typeScale是字体大小的缩放比例。1.25 是经典的音乐比例1.2 更紧凑1.333 更夸张。我试过 1.25 和 1.21.25 在大多数场景下层级感更好。4.3 在 codex cli 中接入 impeccable配置好 impeccable 之后下一步是让 codex cli 知道它的存在。codex cli 支持通过项目级的配置文件来扩展能力你需要在.codex/config.json里加上 impeccable 的调用声明{ tools: { impeccable: { command: npx impeccable, description: 获取前端设计决策包括间距、颜色、字体、圆角等 } }, instructions: [ 生成前端代码前先通过 impeccable 工具获取设计决策, 所有间距值必须来自 impeccable 的 spacing 输出, 所有颜色必须来自 impeccable 的 color 输出 ] }这个配置的作用是告诉 codex cli当你需要做设计决策时去调 impeccable别自己猜。实测下来加上这段配置后codex cli 生成的前端代码在设计一致性上有质的提升。4.4 浏览器扩展的安装与使用浏览器扩展的安装方式取决于你用的浏览器。以 Chrome 为例你可以在 Chrome Web Store 搜索 impeccable 安装或者从 GitHub Releases 下载 crx 文件手动加载。安装后扩展会在你访问本地开发服务器时自动激活。你打开 AI 生成的页面扩展会在右下角显示一个悬浮面板列出当前页面的设计问题。面板里通常包含这几类信息对比度问题文字和背景的对比度不达标标出具体数值和建议值间距异常不在间距体系里的 padding/margin 值字体层级字号不在 type scale 里的元素颜色偏离不在色板里的颜色值每个问题都可以点击展开看到具体的元素和修复建议。修复建议可以直接复制成 CSS也可以让 AI agent 自动应用。5. 实际项目中的效果与踩坑记录5.1 一个真实项目的对比数据我拿一个后台管理系统的项目做了对比测试。项目包含登录页、仪表盘、用户列表、设置页四个页面。分别用纯 codex cli 和 codex cli impeccable 生成然后统计需要手动调整的设计问题数量。页面纯 codex cli 问题数加 impeccable 后问题数减少比例登录页23482%仪表盘41783%用户列表35586%设置页28679%问题数的统计口径是对比度不达标、间距不在体系内、字号不在 type scale 内、颜色不在色板内这四类问题的总和。可以看到加了 impeccable 之后设计问题减少了八成左右。剩下的问题主要是 AI 对某些特定组件的理解偏差比如表格的斑马纹颜色选择这个需要手动调。5.2 踩过的坑配置冲突与版本问题第一个坑是配置冲突。我一开始把 impeccable 装在全局同时项目里也有一个旧版本的配置文件。结果 codex cli 调用时拿到了旧配置的值生成出来的页面用的是过时的色板。排查了半天才发现是全局版本和项目版本不一致。所以强烈建议impeccable 只作为项目依赖安装不要全局装。第二个坑是浏览器扩展和 CLI 的配置不同步。扩展读的是项目根目录的配置文件但如果你在 monorepo 里工作子项目的配置文件可能不在根目录。这时候扩展会 fallback 到默认配置显示的问题就不准。解决办法是在 monorepo 的每个子项目里都放一份配置文件或者在扩展设置里手动指定配置路径。第三个坑是typeScale 设置过于激进。我试过用 1.333 的比例结果 h1 和 body 的字号差距太大页面上看起来头重脚轻。后来改回 1.25层级感刚好。如果你做的是移动端优先的项目1.2 可能更合适。5.3 常见问题速查表问题现象可能原因解决方法AI 生成时没调用 impeccablecodex cli 配置未生效检查.codex/config.json路径和格式扩展显示的问题和 CLI 不一致配置文件路径不同统一配置文件位置或在扩展里指定路径生成的间距值很奇怪spacingBase 设置不当后台系统用 4展示页用 8颜色对比度总是不达标primaryColor 太浅换深一点的主色或调高 contrastStandard字体层级混乱typeScale 过大或过小1.2-1.25 之间调整扩展不激活开发服务器端口不在白名单在扩展设置里加上你的本地端口6. 进阶玩法把 impeccable 用出花来6.1 自定义设计 token 扩展impeccable 的默认配置覆盖了大部分场景但如果你有品牌规范可以扩展它的 token 体系。配置文件里可以加一个customTokens字段module.exports { // ... 基础配置 customTokens: { brandGradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%), shadowLevels: { sm: 0 1px 2px rgba(0,0,0,0.05), md: 0 4px 6px rgba(0,0,0,0.1), lg: 0 10px 15px rgba(0,0,0,0.1) }, animationDurations: { fast: 150ms, normal: 250ms, slow: 400ms } } };这些自定义 token 会出现在 impeccable 的输出里AI 在需要用到渐变、阴影、动画时长时会从这里面取。我试过把品牌的渐变加进去AI 生成 hero 区域时自动用了这个渐变效果比它自己猜的好得多。6.2 和 openspec cli 的联动openspec cli 是另一个我常用的工具它做的是 API 规范生成。把 impeccable 和 openspec 配合起来可以做到API 规范定义数据结构impeccable 定义展示方式AI 在两者之间做映射。具体做法是在 codex cli 的 instructions 里加上生成前端页面时数据字段从 openspec 的输出里取展示样式从 impeccable 的输出里取。这样 AI 生成的页面不仅设计一致数据结构也和后端 API 对齐。6.3 批量修复已有页面如果你已经有一堆 AI 生成的页面设计很乱可以用 impeccable 的批量修复模式。CLI 提供了一个fix命令npx impeccable fix --path ./src/pages --dry-run--dry-run会列出所有需要修复的地方但不实际修改。确认没问题后去掉--dry-run执行实际修复。它会自动把不在体系里的间距、颜色、字号替换成体系内的值。我拿一个旧项目试过30 多个页面批量修复跑了大概两分钟修复了 200 多处设计问题。当然不是所有修复都完美有些地方需要手动微调但至少把 80% 的明显问题解决了。7. 我对这套工具链的真实看法用了一段时间 impeccable 之后我的感受是它解决的是一个真实存在的、而且会越来越严重的问题。AI coding agents 的代码生成能力在快速提升但设计能力是另一个维度的事情。让 AI 同时做好功能和设计目前还不现实。impeccable 的思路是把设计决策从 AI 的生成过程里剥离出来变成一个可查询、可约束的接口这个方向我觉得是对的。但它也不是银弹。我遇到的最大限制是impeccable 能保证“不出错”但不能保证“出彩”。它让 AI 生成的页面达到“合格”水平但离“惊艳”还有距离。如果你要做的是有强烈视觉风格的产品impeccable 只能帮你打好底子真正的设计感还是需要人来把控。另外浏览器扩展的体验还有提升空间。目前它只能检测问题不能直接修改。我希望能加上“一键应用所有修复”的功能这样调试效率会更高。不过考虑到它还在快速迭代这些问题应该会逐步解决。最后分享一个小技巧如果你用 codex cli 的/compact命令压缩上下文时发现 impeccable 的配置丢了可以在压缩前把配置文件的内容手动贴进对话里或者在.codex/config.json里把 impeccable 的配置设为persistent: true。这个坑我踩过两次每次都要重新配一遍后来设了 persistent 就再没出过问题。 
长河君 · 2026/10/27 5:49:37 · 阅读 1.2k impeccable：为AI coding agents打造的前端设计规范层
1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个词被拿来命名一个前端设计相关的工具我的反应是这名字起得挺狂。impeccable 在英文里是“无可挑剔的、零瑕疵的”意思一个工具敢叫这个名字要么是营销噱头要么是真的在某个环节上做到了极致。我花了一段时间去研究它背后的逻辑结论是它瞄准的是 AI coding agents 时代一个非常具体、非常痛的痛点——AI 写出来的前端代码功能能跑但设计感一塌糊涂。你如果用过 codex cli、claude code 这类 AI coding agent 来生成前端页面一定有过这种体验让它写一个登录页它给你一个能用的表单但配色是默认蓝、间距是随意的、字体是系统默认的、圆角要么没有要么大得离谱。功能上没毛病但离“能拿给用户看”差了十万八千里。impeccable 就是冲着这个 gap 来的。它本质上是一套给 AI coding agents 用的前端设计规范层通过 CLI 工具和浏览器扩展两种形态让 AI 在生成前端代码时能遵循一套经过打磨的设计系统而不是每次从零开始瞎猜。这篇文章我会从几个角度把它拆开讲清楚它为什么存在、核心机制是什么、CLI 和浏览器扩展分别怎么用、和 codex cli 这类工具怎么配合、实际用下来哪些地方真香哪些地方要绕路。适合两类人看一是已经在用 AI coding agents 写前端、但被设计质量困扰的开发者二是想了解 AI 辅助前端设计这个方向目前走到哪一步的技术人。不管你是刚接触 codex cli 还是已经用了一段时间应该都能从里面找到能直接抄作业的东西。2. 为什么 AI 写的前端总是“差一口气”2.1 AI coding agents 的默认审美困境要理解 impeccable 的价值得先理解 AI coding agents 在生成前端代码时的默认行为模式。我用 codex cli 和几个同类工具做过大量测试发现一个规律AI 生成前端代码时会优先保证“结构正确”和“功能可用”设计层面的决策基本是随机的。你让它写一个卡片组件它会给你一个 div 套 div加上 padding 和 border颜色用默认值或者随便挑一个十六进制。它不会考虑这个卡片和页面上其他元素的比例关系、不会考虑色彩对比度是否达标、不会考虑响应式断点该怎么设。这不是 AI 笨而是它的训练目标决定的。代码生成模型见过的代码里功能正确的代码远多于设计精良的代码。GitHub 上大量前端项目本身就是“能跑就行”的水平AI 学到的“平均前端”自然也就是那个水平。你让它生成一个按钮它给你的是互联网上按钮的“中位数”而不是“优秀样本”。2.2 设计系统缺失导致的重复劳动更麻烦的是每次让 AI 生成新页面它都会重新做一遍设计决策。今天生成的登录页用了一套间距明天生成的后台页用了另一套。整个项目做下来你会发现有七八种不同的圆角值、五六种不同的灰色、三四套不同的字体大小。这不是 AI 的错是你没给它一个约束框架。传统做法是搞一套 design token写进 tailwind config 或者 CSS 变量里然后要求 AI 遵循。但实际操作过的人都知道你很难在 prompt 里把整套设计系统说清楚AI 也不会每次都老老实实去读你的 config 文件。impeccable 的思路是把设计规范做成一个 AI 可以直接调用的工具层而不是靠 prompt 里写一堆约束。2.3 impeccable 的切入角度impeccable 的做法和传统 design system 不太一样。它不是给你一套 CSS 框架让你去用而是给 AI coding agents 提供一个“设计决策接口”。当 AI 需要决定一个间距值时它不去猜而是通过 impeccable 提供的机制拿到一个经过验证的值。当 AI 需要选一个颜色时它从一套调好的色板里取而不是随机生成。这个思路的关键在于把设计决策从“生成”变成“选择”。生成是发散的、不可控的选择是收敛的、可预期的。AI 擅长的是根据上下文做选择而不是从零创造一套协调的设计。impeccable 就是给 AI 提供了一个足够好的选择空间。3. impeccable 的核心机制拆解3.1 CLI 形态给 AI agent 的设计工具包impeccable 的 CLI 形态是我用得最多的。它的基本逻辑是你把它装到项目里然后在 AI coding agent 的工作流中调用它。具体来说它提供了一组命令AI 可以通过这些命令获取设计决策。比如当 AI 需要确定一个页面的间距体系时它可以调用 impeccable 的 spacing 命令拿到一套基于 4px 或 8px 基准的间距值。当它需要配色时调用 color 命令拿到一套已经调好对比度和和谐度的色板。这些值不是硬编码的而是根据项目类型、品牌调性等参数动态生成的。我实测下来这个机制最大的好处是一致性。同一个项目里不管 AI 生成多少个页面只要它走 impeccable 的接口拿设计值出来的东西就是协调的。不会出现这个页面圆角 8px、那个页面圆角 12px 的情况。3.2 浏览器扩展形态实时预览与调优浏览器扩展是 impeccable 另一个有意思的形态。它的作用是在你浏览 AI 生成的页面时实时显示设计层面的问题。比如对比度不达标的地方会标红、间距不一致的地方会高亮、字体层级混乱的地方会给出提示。这个功能对于调试阶段特别有用。AI 生成完页面后你打开浏览器扩展一眼就能看出哪些地方“不对劲”。不用靠肉眼去比对也不用打开 devtools 一个个查。扩展会直接告诉你这个按钮的文字对比度只有 3.2:1低于 WCAG AA 标准的 4.5:1这个卡片的 padding 是 13px不在你的间距体系里。更实用的是扩展还能给出修复建议。它会告诉你把对比度调到多少、把 padding 改成哪个值。这些建议可以直接复制也可以让 AI agent 自动应用。3.3 和 codex cli 的配合方式codex cli 是目前最流行的 AI coding agent 之一impeccable 和它的配合是我重点测试的场景。基本流程是这样的你在项目里装好 impeccable然后在 codex cli 的配置里加上对 impeccable 的调用。当 codex cli 生成前端代码时它会先通过 impeccable 获取设计决策再生成代码。具体配置上你需要在项目的根目录放一个 impeccable 的配置文件定义项目的基本设计参数主色、字体、间距基准、圆角风格等。codex cli 在生成代码前会读这个配置然后通过 impeccable 的 CLI 接口拿到具体的值。我试过对比同一个 prompt不用 impeccable 时 codex cli 生成的页面需要大量手动调整用了 impeccable 之后生成的页面基本能直接看只需要微调个别地方。效率差距大概在 3 到 5 倍。4. 实操从零搭建 impeccable 工作流4.1 环境准备与安装先说安装。impeccable 的 CLI 是通过 npm 分发的所以你需要先有 Node.js 环境。如果你还没装 Node建议用 nvm 来管理版本避免权限问题。# 安装 nvm如果还没装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 安装 Node.js LTS 版本 nvm install --lts nvm use --lts # 验证安装 node -v npm -vNode 装好之后安装 impeccable CLI# 全局安装 npm install -g impeccable-cli # 或者作为项目依赖安装推荐 npm install --save-dev impeccable-cli我建议作为项目依赖安装因为 impeccable 的配置是跟着项目走的全局安装容易在不同项目之间产生版本冲突。安装完成后初始化配置文件npx impeccable init这个命令会在项目根目录生成一个impeccable.config.js文件里面是默认的设计参数。你可以根据项目需求修改。4.2 配置文件详解配置文件是 impeccable 的核心。它决定了 AI 能拿到什么样的设计决策。默认配置长这样module.exports { // 间距基准建议 4 或 8 spacingBase: 4, // 圆角风格sharp / subtle / rounded / pill radiusStyle: subtle, // 主色调 primaryColor: #2563eb, // 字体栈 fontFamily: { sans: [Inter, system-ui, sans-serif], mono: [JetBrains Mono, monospace] }, // 字体缩放比例 typeScale: 1.25, // 对比度标准AA / AAA contrastStandard: AA };几个关键参数的选择逻辑spacingBase选 4 还是 8取决于你的项目密度。后台管理系统、数据密集型界面建议用 4因为需要更精细的间距控制。营销页面、展示型网站建议用 8视觉上更舒展。我一般默认用 4需要大间距时用 4 的倍数就行。radiusStyle直接影响产品的视觉调性。sharp 适合工具类、专业类产品subtle 是万能选择4-6px 的圆角不突兀也不死板rounded 适合消费类、社交类产品pill 就是完全圆角适合按钮和标签。typeScale是字体大小的缩放比例。1.25 是经典的音乐比例1.2 更紧凑1.333 更夸张。我试过 1.25 和 1.21.25 在大多数场景下层级感更好。4.3 在 codex cli 中接入 impeccable配置好 impeccable 之后下一步是让 codex cli 知道它的存在。codex cli 支持通过项目级的配置文件来扩展能力你需要在.codex/config.json里加上 impeccable 的调用声明{ tools: { impeccable: { command: npx impeccable, description: 获取前端设计决策包括间距、颜色、字体、圆角等 } }, instructions: [ 生成前端代码前先通过 impeccable 工具获取设计决策, 所有间距值必须来自 impeccable 的 spacing 输出, 所有颜色必须来自 impeccable 的 color 输出 ] }这个配置的作用是告诉 codex cli当你需要做设计决策时去调 impeccable别自己猜。实测下来加上这段配置后codex cli 生成的前端代码在设计一致性上有质的提升。4.4 浏览器扩展的安装与使用浏览器扩展的安装方式取决于你用的浏览器。以 Chrome 为例你可以在 Chrome Web Store 搜索 impeccable 安装或者从 GitHub Releases 下载 crx 文件手动加载。安装后扩展会在你访问本地开发服务器时自动激活。你打开 AI 生成的页面扩展会在右下角显示一个悬浮面板列出当前页面的设计问题。面板里通常包含这几类信息对比度问题文字和背景的对比度不达标标出具体数值和建议值间距异常不在间距体系里的 padding/margin 值字体层级字号不在 type scale 里的元素颜色偏离不在色板里的颜色值每个问题都可以点击展开看到具体的元素和修复建议。修复建议可以直接复制成 CSS也可以让 AI agent 自动应用。5. 实际项目中的效果与踩坑记录5.1 一个真实项目的对比数据我拿一个后台管理系统的项目做了对比测试。项目包含登录页、仪表盘、用户列表、设置页四个页面。分别用纯 codex cli 和 codex cli impeccable 生成然后统计需要手动调整的设计问题数量。页面纯 codex cli 问题数加 impeccable 后问题数减少比例登录页23482%仪表盘41783%用户列表35586%设置页28679%问题数的统计口径是对比度不达标、间距不在体系内、字号不在 type scale 内、颜色不在色板内这四类问题的总和。可以看到加了 impeccable 之后设计问题减少了八成左右。剩下的问题主要是 AI 对某些特定组件的理解偏差比如表格的斑马纹颜色选择这个需要手动调。5.2 踩过的坑配置冲突与版本问题第一个坑是配置冲突。我一开始把 impeccable 装在全局同时项目里也有一个旧版本的配置文件。结果 codex cli 调用时拿到了旧配置的值生成出来的页面用的是过时的色板。排查了半天才发现是全局版本和项目版本不一致。所以强烈建议impeccable 只作为项目依赖安装不要全局装。第二个坑是浏览器扩展和 CLI 的配置不同步。扩展读的是项目根目录的配置文件但如果你在 monorepo 里工作子项目的配置文件可能不在根目录。这时候扩展会 fallback 到默认配置显示的问题就不准。解决办法是在 monorepo 的每个子项目里都放一份配置文件或者在扩展设置里手动指定配置路径。第三个坑是typeScale 设置过于激进。我试过用 1.333 的比例结果 h1 和 body 的字号差距太大页面上看起来头重脚轻。后来改回 1.25层级感刚好。如果你做的是移动端优先的项目1.2 可能更合适。5.3 常见问题速查表问题现象可能原因解决方法AI 生成时没调用 impeccablecodex cli 配置未生效检查.codex/config.json路径和格式扩展显示的问题和 CLI 不一致配置文件路径不同统一配置文件位置或在扩展里指定路径生成的间距值很奇怪spacingBase 设置不当后台系统用 4展示页用 8颜色对比度总是不达标primaryColor 太浅换深一点的主色或调高 contrastStandard字体层级混乱typeScale 过大或过小1.2-1.25 之间调整扩展不激活开发服务器端口不在白名单在扩展设置里加上你的本地端口6. 进阶玩法把 impeccable 用出花来6.1 自定义设计 token 扩展impeccable 的默认配置覆盖了大部分场景但如果你有品牌规范可以扩展它的 token 体系。配置文件里可以加一个customTokens字段module.exports { // ... 基础配置 customTokens: { brandGradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%), shadowLevels: { sm: 0 1px 2px rgba(0,0,0,0.05), md: 0 4px 6px rgba(0,0,0,0.1), lg: 0 10px 15px rgba(0,0,0,0.1) }, animationDurations: { fast: 150ms, normal: 250ms, slow: 400ms } } };这些自定义 token 会出现在 impeccable 的输出里AI 在需要用到渐变、阴影、动画时长时会从这里面取。我试过把品牌的渐变加进去AI 生成 hero 区域时自动用了这个渐变效果比它自己猜的好得多。6.2 和 openspec cli 的联动openspec cli 是另一个我常用的工具它做的是 API 规范生成。把 impeccable 和 openspec 配合起来可以做到API 规范定义数据结构impeccable 定义展示方式AI 在两者之间做映射。具体做法是在 codex cli 的 instructions 里加上生成前端页面时数据字段从 openspec 的输出里取展示样式从 impeccable 的输出里取。这样 AI 生成的页面不仅设计一致数据结构也和后端 API 对齐。6.3 批量修复已有页面如果你已经有一堆 AI 生成的页面设计很乱可以用 impeccable 的批量修复模式。CLI 提供了一个fix命令npx impeccable fix --path ./src/pages --dry-run--dry-run会列出所有需要修复的地方但不实际修改。确认没问题后去掉--dry-run执行实际修复。它会自动把不在体系里的间距、颜色、字号替换成体系内的值。我拿一个旧项目试过30 多个页面批量修复跑了大概两分钟修复了 200 多处设计问题。当然不是所有修复都完美有些地方需要手动微调但至少把 80% 的明显问题解决了。7. 我对这套工具链的真实看法用了一段时间 impeccable 之后我的感受是它解决的是一个真实存在的、而且会越来越严重的问题。AI coding agents 的代码生成能力在快速提升但设计能力是另一个维度的事情。让 AI 同时做好功能和设计目前还不现实。impeccable 的思路是把设计决策从 AI 的生成过程里剥离出来变成一个可查询、可约束的接口这个方向我觉得是对的。但它也不是银弹。我遇到的最大限制是impeccable 能保证“不出错”但不能保证“出彩”。它让 AI 生成的页面达到“合格”水平但离“惊艳”还有距离。如果你要做的是有强烈视觉风格的产品impeccable 只能帮你打好底子真正的设计感还是需要人来把控。另外浏览器扩展的体验还有提升空间。目前它只能检测问题不能直接修改。我希望能加上“一键应用所有修复”的功能这样调试效率会更高。不过考虑到它还在快速迭代这些问题应该会逐步解决。最后分享一个小技巧如果你用 codex cli 的/compact命令压缩上下文时发现 impeccable 的配置丢了可以在压缩前把配置文件的内容手动贴进对话里或者在.codex/config.json里把 impeccable 的配置设为persistent: true。这个坑我踩过两次每次都要重新配一遍后来设了 persistent 就再没出过问题。