1. 项目缘起为什么我们需要一个叫“impeccable”的东西第一次看到“impeccable”这个词是在一个前端群里有人甩了张截图说“这玩意儿生成的页面比我手写的还干净”。截图里是一个用 AI coding agents 驱动的界面布局规整、间距舒服、配色克制连 hover 状态的过渡曲线都调得恰到好处。底下有人回了一句“impeccable 是吧名字没白起。”这个词本身的意思是“无可挑剔的、完美的”。放在前端设计语境里它指向的是一种近乎苛刻的完成度——不是功能跑通就完事而是每一个像素、每一处交互、每一行样式都经得起推敲。而它作为一个项目标题出现时背后往往牵扯到一整套工具链CLI、browser extension、AI coding agents以及围绕它们构建的工作流。我花了大概两周时间把市面上跟“impeccable”相关的工具、思路和实操方案摸了一遍。这篇文章就是这段时间的整理。它适合三类人一是前端开发者想借助 AI coding agents 提升页面产出质量二是对 CLI 工具链感兴趣、想搭建自己自动化流程的工程师三是产品设计方向的同学想理解“AI 生成的前端代码为什么有时候能比人写得还规整”。核心关键词会自然分布在全文里impeccable、AI coding agents、frontend design、CLI、browser extension。我不会堆砌它们但你在读的时候会发现这几个词基本串起了整条逻辑线。先说结论impeccable 不是一个单一工具的名字它更像一种标准或者一种追求。围绕这个标准目前比较成熟的落地方式是用 CLI 工具驱动 AI coding agents再配合 browser extension 做实时校验和微调。下面我从设计思路开始拆。2. 整体设计思路为什么是 CLI 加 browser extension 的组合2.1 从“写完再调”到“边写边校”的转变传统前端开发流程里样式和交互的打磨往往是滞后的。你先用框架把结构搭出来功能跑通然后打开浏览器F12 一点点调 margin、padding、color。这个过程很依赖经验而且容易陷入“改一个地方崩三个地方”的循环。AI coding agents 的介入改变了这个节奏。你可以在 CLI 里用自然语言描述你想要的界面效果agent 直接生成对应的组件代码和样式文件。但问题也随之而来agent 生成的东西你怎么知道它是不是真的“impeccable”你总不能每次都手动打开浏览器去肉眼检查。这就是 browser extension 发挥作用的地方。它的角色是一个实时校验层。当 CLI 里的 agent 输出代码后extension 可以在浏览器端同步渲染结果并且用预设的规则集去检测间距是否遵循了 8px 网格、对比度是否达到 WCAG AA 标准、响应式断点是否覆盖了主流设备宽度、交互状态是否完整hover、focus、active、disabled。提示这里的 browser extension 不是指某个特定产品而是一类工具的思路。你可以用现成的也可以基于开源方案自己改。核心是让它承担“自动化视觉审查”的职责。2.2 CLI 作为中枢为什么不让 agent 直接对接编辑器有人会问既然 AI coding agents 这么强为什么不直接在编辑器插件里用非要绕一层 CLI我的实测体会是CLI 的优势在于可组合性和可追溯性。编辑器插件往往把 agent 的能力封装成一个黑盒按钮你点一下它给你一段代码但中间发生了什么、用了什么 prompt、参考了哪些上下文你不太清楚。而 CLI 模式下每一次调用都是一条命令你可以把命令写进脚本、写进 CI 流程、写进 git hook。举个例子你可以定义一个命令叫impeccable-check它做三件事调用 agent 生成或修改组件代码、触发 browser extension 的校验接口、把校验结果以结构化格式输出到终端。如果校验不通过命令返回非零退出码CI 就会拦住这次提交。这套流程在编辑器插件里很难做到同样干净。另外CLI 天然适合跟其他工具串联。比如你可以用openspec cli管理组件规格用codex cli做代码生成用gitlab cli触发流水线整个链路都在终端里完成不需要在多个图形界面之间切换。2.3 方案选型的几个关键考量在搭建这套流程时我对比了几种方案最终确定的组合是基于以下考量考量维度纯编辑器插件方案CLI browser extension 方案纯手动方案可自动化程度低高极低校验实时性中高低流程可追溯差好中学习成本低中低适合团队协作差好差对 AI agent 的利用率中高无这个对比不是要否定编辑器插件而是说如果你的目标是“impeccable”级别的完成度并且希望这个过程可重复、可规模化CLI 加 extension 的组合是目前比较务实的选择。还有一个细节browser extension 的校验规则应该是可配置的。不同项目对“impeccable”的定义不一样。有的项目要求严格遵循设计系统有的项目允许一定程度的创意发挥。所以 extension 的规则集最好用配置文件管理跟项目代码一起版本控制。3. 核心细节解析AI coding agents 在前端设计中的实际表现3.1 agent 生成代码的质量边界在哪里我用同一个需求——一个带筛选功能的卡片列表页——分别让三个不同的 AI coding agents 生成代码然后从几个维度打分。结果挺有意思的。第一个 agent 生成的代码结构清晰但样式用了大量内联 style维护性差。第二个 agent 样式抽离得不错但响应式只做了两个断点在平板尺寸下布局会挤。第三个 agent 整体完成度最高但在暗色模式下的对比度不达标文字和背景的对比度只有 3.2:1低于 WCAG AA 要求的 4.5:1。这说明一个问题AI coding agents 在“结构正确性”上已经做得很好但在“设计细节的严谨性”上还有波动。而 impeccable 追求的是后者。所以你不能完全放手让 agent 自己跑必须有一个校验环节兜底。注意不要指望单个 agent 一次生成就达到 impeccable 标准。更现实的预期是agent 负责产出 80% 的基础代码剩下的 20% 靠校验规则和人工微调补齐。3.2 prompt 的设计比模型选择更重要很多人纠结用哪个 agent、哪个模型但我实测下来prompt 的结构化程度对最终质量的影响更大。一个有效的 prompt 应该包含这几个部分组件用途说明、布局约束网格系统、间距规则、交互状态要求、可访问性标准、以及参考示例。比如生成一个产品卡片组件要求 - 使用 8px 间距网格卡片内边距 24px卡片间距 16px - 包含 hover 抬升效果transition 时长 200ms缓动函数 ease-out - 文字对比度不低于 4.5:1支持暗色模式 - 响应式移动端单列平板双列桌面三列 - 输出格式React 函数组件 CSS Modules这种 prompt 比“帮我写个卡片组件”的产出质量高出一个档次。因为 agent 不需要猜你的设计意图它只需要执行明确的约束。3.3 browser extension 的校验规则怎么写校验规则的核心是把设计规范翻译成可执行的检测逻辑。以下是我在项目中实际使用的一组规则用伪代码表示// 间距网格校验 function checkSpacingGrid(element) { const spacing getComputedStyle(element).margin getComputedStyle(element).padding; const values spacing.split( ).map(parseFloat); return values.every(v v % 8 0); } // 对比度校验 function checkContrast(textEl, bgEl) { const textColor getComputedStyle(textEl).color; const bgColor getComputedStyle(bgEl).backgroundColor; const ratio calculateContrastRatio(textColor, bgColor); return ratio 4.5; } // 交互状态完整性校验 function checkInteractionStates(element) { const states [hover, focus, active, disabled]; return states.every(state hasStyleForState(element, state)); }这些规则跑在 browser extension 里每次 agent 输出代码后自动触发。不通过的项会在终端里以红色高亮显示并附带具体的元素定位信息。3.4 工具链的版本管理问题CLI 工具链的一个痛点是版本碎片化。codex cli、openspec cli、gitlab cli各自独立更新有时候新版本会改变命令参数或输出格式导致你的脚本挂掉。我的做法是在项目根目录放一个tools.lock文件记录每个 CLI 工具的版本号然后在 CI 里用这个文件锁定安装版本。本地开发时也建议用容器或虚拟环境隔离避免全局安装带来的冲突。另外codex cli有一些常用命令值得记一下/compact用于压缩上下文、/model用于切换模型、/resume用于恢复之前的会话。这些命令在长时间开发会话里很有用尤其是当你需要 agent 记住之前的决策时。4. 实操过程从零搭建一套 impeccable 工作流4.1 环境准备与工具安装先列一下我用的工具清单和安装方式。这里以 macOS 为例Linux 和 Windows 的差异我会在注意事项里说明。# 安装 Node.js 环境如果还没有 brew install node20 # 安装 codex cli npm install -g openai/codex-cli # 安装 openspec cli用于管理组件规格 npm install -g openspec-cli # 安装 gitlab cli brew install glab # 安装 browser extension 的开发依赖 npm install -D impeccable/extension-core安装完成后用codex --version和openspec --version确认版本。如果遇到权限问题检查 npm 的全局目录配置。提示如果你在团队里推广这套流程建议把安装步骤写成一个setup.sh脚本新成员 clone 项目后跑一次就行。这比写文档更可靠因为脚本不会过时。4.2 项目初始化与配置文件在项目根目录创建.impeccable目录里面放三个文件.impeccable/ ├── rules.json # 校验规则配置 ├── prompts/ # prompt 模板 │ ├── component.md │ └── page.md └── tools.lock # CLI 工具版本锁定rules.json的内容示例{ spacing: { grid: 8, tolerance: 0 }, contrast: { standard: WCAG_AA, minRatio: 4.5 }, responsive: { breakpoints: [375, 768, 1024, 1440] }, interaction: { requiredStates: [hover, focus, active, disabled] } }这个文件是 browser extension 和 CLI 校验命令的共同数据源。改一处两边都生效。4.3 用 CLI 驱动 agent 生成组件假设我要生成一个导航栏组件。操作流程如下第一步在终端里进入项目目录启动 codex cli 会话codex --project . --prompt-file .impeccable/prompts/component.md第二步在会话里输入具体需求生成一个顶部导航栏组件包含 - Logo 区域左对齐 - 主导航链接居中最多 6 个 - 用户头像下拉菜单右对齐 - 移动端折叠为汉堡菜单 - 滚动时背景从透明变为白色带阴影第三步agent 输出代码后不要急着保存。先跑校验impeccable-check --file src/components/Navbar.tsx这个命令会调用 browser extension 的校验接口在无头浏览器里渲染组件然后逐项检查规则。输出格式类似[PASS] spacing.grid: 所有间距值均为 8 的倍数 [PASS] contrast.text: 文字对比度 5.2:1 [FAIL] interaction.focus: 缺少 focus 状态的可见样式 [PASS] responsive.breakpoints: 覆盖 4 个断点第四步针对 FAIL 项让 agent 修复focus 状态缺少可见样式请为所有可交互元素添加 focus-visible 轮廓 颜色使用主题色宽度 2px偏移 2px。修复后再跑一次校验直到全部 PASS。4.4 browser extension 的实时预览与微调CLI 校验通过后打开浏览器extension 会自动注入一个侧边栏面板。面板里显示当前页面的校验状态并且支持实时微调。比如你可以在面板里拖动一个滑块来调整全局间距基准extension 会实时重新计算所有元素的间距是否符合新的网格。如果某个元素不符合它会在页面上高亮标出。这个功能在跟设计师协作时特别有用。设计师说“间距再大一点”你不用手动改代码直接在面板里调调好了把生成的 CSS 变量导出粘贴回代码里就行。4.5 集成到 CI 流程在.gitlab-ci.yml里加一个 stageimpeccable-check: stage: test script: - npm run build - impeccable-check --all --reporter json report.json - node scripts/check-report.js report.json artifacts: paths: - report.jsoncheck-report.js的逻辑很简单读取 JSON 报告如果有 FAIL 项就process.exit(1)。这样 MR 就会被拦住直到所有校验通过。4.6 参数计算对比度与间距的实际演算拿对比度来说WCAG AA 要求正文文字对比度至少 4.5:1。假设你的背景色是#FFFFFF文字色是#767676对比度计算公式是L1 0.2126 * R 0.7152 * G 0.0722 * B线性化后 contrast (L1 0.05) / (L2 0.05)#767676的亮度值约为 0.184#FFFFFF的亮度值为 1.0。代入公式contrast (1.0 0.05) / (0.184 0.05) 1.05 / 0.234 ≈ 4.49刚好差一点点。所以#767676在白色背景上不满足 AA 标准需要再深一点比如#757575或#6B6B6B。这种计算在 browser extension 里是自动完成的但你得理解原理才能在 agent 生成的颜色值不合理时快速判断。间距方面8px 网格的意思是所有 margin、padding、gap 的值都应该是 8 的倍数。为什么是 8 而不是 10因为 8 能被 2、4、8 整除在响应式缩放时更容易保持比例关系。而且主流设计系统Material Design、Ant Design都采用 8px 基准生态兼容性更好。5. 常见问题与排查技巧实录5.1 agent 生成的代码校验不通过怎么办这是最高频的问题。我的排查顺序是先看 FAIL 项的类型。如果是 spacing 类通常是 agent 用了非标准值比如 12px、20px。直接在 prompt 里强调“所有间距必须是 8 的倍数”就能解决大部分情况。如果是 contrast 类说明 agent 选的颜色不对。这时候不要让它自己调而是给它具体的色值。比如“把文字色改为 #595959背景保持 #FFFFFF”。因为 agent 对色彩对比度的计算能力不稳定给它明确值比让它猜更可靠。如果是 interaction 类通常是 agent 漏掉了某个状态。在 prompt 里列一个状态清单让它逐项确认。5.2 CLI 命令执行失败或超时codex cli在长会话中可能会因为上下文过长而变慢。这时候用/compact命令压缩上下文或者用/resume开一个新会话但保留关键决策记录。如果gitlab cli报认证错误检查GITLAB_TOKEN环境变量是否设置以及 token 是否有api权限。openspec cli在 Windows 上可能需要用 WSL 运行原生 Windows 终端有时会有路径解析问题。5.3 browser extension 不生效或校验结果异常先确认 extension 是否已启用并且有当前页面的访问权限。有些浏览器默认会禁用开发者模式加载的 extension需要手动开启。如果校验结果跟预期不符检查rules.json是否被正确加载。可以在 extension 的控制台里打印当前生效的规则集确认配置没有语法错误。还有一种情况是页面用了 Shadow DOMextension 的样式检测可能穿透不了。这时候需要在规则里配置pierceShadow: true或者把检测逻辑注入到 Shadow Root 内部。5.4 团队协作中的规则冲突不同项目对 impeccable 的定义可能不同。A 项目要求 8px 网格B 项目可能用 4px 网格。解决办法是把.impeccable目录做成可继承的根目录放一套基础规则子项目可以覆盖特定字段。{ extends: ../../.impeccable/rules.json, spacing: { grid: 4 } }这样既保持了统一标准又允许项目级定制。5.5 常见问题速查表问题现象可能原因排查动作解决方式校验全部 PASS 但页面明显有问题规则集未覆盖该维度检查 rules.json 是否缺少对应规则补充规则并重新校验agent 反复生成相同错误prompt 约束不明确查看会话历史中的 prompt增加具体约束和示例CLI 输出乱码终端编码不支持检查 LANG 环境变量设置为 en_US.UTF-8extension 面板不显示权限或版本问题查看浏览器扩展管理页重新加载或更新版本CI 中校验超时无头浏览器启动慢查看 CI 日志增加超时时间或预启动浏览器5.6 几个踩过的坑第一个坑一开始我把校验规则写得太严要求所有颜色都必须来自设计系统的 token。结果 agent 生成的代码几乎全部 FAIL因为它在处理渐变和阴影时会用一些中间色。后来我把规则改成“主要颜色必须来自 token辅助色允许偏差在 5% 以内”通过率就正常了。第二个坑browser extension 的校验在本地跑得好好的一到 CI 就挂。排查后发现是 CI 环境没有安装中文字体导致文字渲染宽度计算错误进而影响了布局校验。解决办法是在 CI 镜像里预装常用字体。第三个坑codex cli的/model命令切换模型后之前的会话上下文会丢失。如果你在一个长任务中途切模型记得先把关键决策用/compact保存下来否则 agent 会“失忆”。6. 扩展思路这套工作流还能怎么用6.1 从组件级扩展到页面级目前这套流程主要针对单个组件。如果你想做整页的 impeccable 校验需要把 browser extension 的检测范围从元素级扩展到页面级。具体来说增加几个维度页面整体信息层级是否清晰、首屏关键内容是否在折叠线以上、滚动深度与内容密度的关系是否合理。这些维度比较主观很难用纯规则描述。我的做法是让 agent 先给页面打一个“设计评分”然后人工复核。评分不达标的页面再进入细项校验。6.2 与设计工具的联动如果你的团队用 Figma 做设计可以写一个脚本把 Figma 的设计 token 导出成.impeccable/rules.json的格式。这样设计稿一更新校验规则自动同步不需要手动维护两套配置。具体实现思路是用 Figma 的 REST API 拉取样式数据然后用一个转换脚本映射到规则字段。这个脚本可以放在 CI 里定时跑也可以手动触发。6.3 多端适配的校验扩展现在这套流程主要针对 Web 端。如果你要做小程序或移动端 H5校验规则需要调整。比如小程序的rpx单位跟px的换算关系、移动端触摸目标的最小尺寸建议 44x44pt、以及不同机型的安全区域适配。这些都可以作为新的规则维度加进rules.json然后让 browser extension 在对应的模拟器环境里执行校验。6.4 性能维度的加入impeccable 不只是视觉上的也包括性能上的。你可以在校验流程里加入 Lighthouse 的指标检测首次内容绘制、最大内容绘制、累积布局偏移。这些指标不达标即使视觉再完美也算不上 impeccable。实现方式是在 CI 里跑一次 Lighthouse把结果跟视觉校验报告合并输出。两个都通过才算真正 PASS。我个人在实际操作中的体会是这套工作流最大的价值不在于“让 AI 替你写代码”而在于它把前端设计中的隐性标准显性化了。以前你说“这个页面做得不够精致”别人可能不知道你指的是什么。现在你有一份校验报告上面列着哪一项不达标、差多少、怎么改。沟通成本降下来了产出质量反而上去了。最后再分享一个小技巧把每次校验失败的原因和修复方式记录到一个lessons.md文件里定期回顾。你会发现有些错误是反复出现的针对这些高频错误优化 prompt 或规则比每次手动修要高效得多。这个文件也会成为团队新成员最好的培训材料。 
长河君 · 2026/10/28 23:20:16 · 阅读 1.2k impeccable 工作流：用 CLI 与 AI coding agents 打造无可挑剔的前端设计
1. 项目缘起为什么我们需要一个叫“impeccable”的东西第一次看到“impeccable”这个词是在一个前端群里有人甩了张截图说“这玩意儿生成的页面比我手写的还干净”。截图里是一个用 AI coding agents 驱动的界面布局规整、间距舒服、配色克制连 hover 状态的过渡曲线都调得恰到好处。底下有人回了一句“impeccable 是吧名字没白起。”这个词本身的意思是“无可挑剔的、完美的”。放在前端设计语境里它指向的是一种近乎苛刻的完成度——不是功能跑通就完事而是每一个像素、每一处交互、每一行样式都经得起推敲。而它作为一个项目标题出现时背后往往牵扯到一整套工具链CLI、browser extension、AI coding agents以及围绕它们构建的工作流。我花了大概两周时间把市面上跟“impeccable”相关的工具、思路和实操方案摸了一遍。这篇文章就是这段时间的整理。它适合三类人一是前端开发者想借助 AI coding agents 提升页面产出质量二是对 CLI 工具链感兴趣、想搭建自己自动化流程的工程师三是产品设计方向的同学想理解“AI 生成的前端代码为什么有时候能比人写得还规整”。核心关键词会自然分布在全文里impeccable、AI coding agents、frontend design、CLI、browser extension。我不会堆砌它们但你在读的时候会发现这几个词基本串起了整条逻辑线。先说结论impeccable 不是一个单一工具的名字它更像一种标准或者一种追求。围绕这个标准目前比较成熟的落地方式是用 CLI 工具驱动 AI coding agents再配合 browser extension 做实时校验和微调。下面我从设计思路开始拆。2. 整体设计思路为什么是 CLI 加 browser extension 的组合2.1 从“写完再调”到“边写边校”的转变传统前端开发流程里样式和交互的打磨往往是滞后的。你先用框架把结构搭出来功能跑通然后打开浏览器F12 一点点调 margin、padding、color。这个过程很依赖经验而且容易陷入“改一个地方崩三个地方”的循环。AI coding agents 的介入改变了这个节奏。你可以在 CLI 里用自然语言描述你想要的界面效果agent 直接生成对应的组件代码和样式文件。但问题也随之而来agent 生成的东西你怎么知道它是不是真的“impeccable”你总不能每次都手动打开浏览器去肉眼检查。这就是 browser extension 发挥作用的地方。它的角色是一个实时校验层。当 CLI 里的 agent 输出代码后extension 可以在浏览器端同步渲染结果并且用预设的规则集去检测间距是否遵循了 8px 网格、对比度是否达到 WCAG AA 标准、响应式断点是否覆盖了主流设备宽度、交互状态是否完整hover、focus、active、disabled。提示这里的 browser extension 不是指某个特定产品而是一类工具的思路。你可以用现成的也可以基于开源方案自己改。核心是让它承担“自动化视觉审查”的职责。2.2 CLI 作为中枢为什么不让 agent 直接对接编辑器有人会问既然 AI coding agents 这么强为什么不直接在编辑器插件里用非要绕一层 CLI我的实测体会是CLI 的优势在于可组合性和可追溯性。编辑器插件往往把 agent 的能力封装成一个黑盒按钮你点一下它给你一段代码但中间发生了什么、用了什么 prompt、参考了哪些上下文你不太清楚。而 CLI 模式下每一次调用都是一条命令你可以把命令写进脚本、写进 CI 流程、写进 git hook。举个例子你可以定义一个命令叫impeccable-check它做三件事调用 agent 生成或修改组件代码、触发 browser extension 的校验接口、把校验结果以结构化格式输出到终端。如果校验不通过命令返回非零退出码CI 就会拦住这次提交。这套流程在编辑器插件里很难做到同样干净。另外CLI 天然适合跟其他工具串联。比如你可以用openspec cli管理组件规格用codex cli做代码生成用gitlab cli触发流水线整个链路都在终端里完成不需要在多个图形界面之间切换。2.3 方案选型的几个关键考量在搭建这套流程时我对比了几种方案最终确定的组合是基于以下考量考量维度纯编辑器插件方案CLI browser extension 方案纯手动方案可自动化程度低高极低校验实时性中高低流程可追溯差好中学习成本低中低适合团队协作差好差对 AI agent 的利用率中高无这个对比不是要否定编辑器插件而是说如果你的目标是“impeccable”级别的完成度并且希望这个过程可重复、可规模化CLI 加 extension 的组合是目前比较务实的选择。还有一个细节browser extension 的校验规则应该是可配置的。不同项目对“impeccable”的定义不一样。有的项目要求严格遵循设计系统有的项目允许一定程度的创意发挥。所以 extension 的规则集最好用配置文件管理跟项目代码一起版本控制。3. 核心细节解析AI coding agents 在前端设计中的实际表现3.1 agent 生成代码的质量边界在哪里我用同一个需求——一个带筛选功能的卡片列表页——分别让三个不同的 AI coding agents 生成代码然后从几个维度打分。结果挺有意思的。第一个 agent 生成的代码结构清晰但样式用了大量内联 style维护性差。第二个 agent 样式抽离得不错但响应式只做了两个断点在平板尺寸下布局会挤。第三个 agent 整体完成度最高但在暗色模式下的对比度不达标文字和背景的对比度只有 3.2:1低于 WCAG AA 要求的 4.5:1。这说明一个问题AI coding agents 在“结构正确性”上已经做得很好但在“设计细节的严谨性”上还有波动。而 impeccable 追求的是后者。所以你不能完全放手让 agent 自己跑必须有一个校验环节兜底。注意不要指望单个 agent 一次生成就达到 impeccable 标准。更现实的预期是agent 负责产出 80% 的基础代码剩下的 20% 靠校验规则和人工微调补齐。3.2 prompt 的设计比模型选择更重要很多人纠结用哪个 agent、哪个模型但我实测下来prompt 的结构化程度对最终质量的影响更大。一个有效的 prompt 应该包含这几个部分组件用途说明、布局约束网格系统、间距规则、交互状态要求、可访问性标准、以及参考示例。比如生成一个产品卡片组件要求 - 使用 8px 间距网格卡片内边距 24px卡片间距 16px - 包含 hover 抬升效果transition 时长 200ms缓动函数 ease-out - 文字对比度不低于 4.5:1支持暗色模式 - 响应式移动端单列平板双列桌面三列 - 输出格式React 函数组件 CSS Modules这种 prompt 比“帮我写个卡片组件”的产出质量高出一个档次。因为 agent 不需要猜你的设计意图它只需要执行明确的约束。3.3 browser extension 的校验规则怎么写校验规则的核心是把设计规范翻译成可执行的检测逻辑。以下是我在项目中实际使用的一组规则用伪代码表示// 间距网格校验 function checkSpacingGrid(element) { const spacing getComputedStyle(element).margin getComputedStyle(element).padding; const values spacing.split( ).map(parseFloat); return values.every(v v % 8 0); } // 对比度校验 function checkContrast(textEl, bgEl) { const textColor getComputedStyle(textEl).color; const bgColor getComputedStyle(bgEl).backgroundColor; const ratio calculateContrastRatio(textColor, bgColor); return ratio 4.5; } // 交互状态完整性校验 function checkInteractionStates(element) { const states [hover, focus, active, disabled]; return states.every(state hasStyleForState(element, state)); }这些规则跑在 browser extension 里每次 agent 输出代码后自动触发。不通过的项会在终端里以红色高亮显示并附带具体的元素定位信息。3.4 工具链的版本管理问题CLI 工具链的一个痛点是版本碎片化。codex cli、openspec cli、gitlab cli各自独立更新有时候新版本会改变命令参数或输出格式导致你的脚本挂掉。我的做法是在项目根目录放一个tools.lock文件记录每个 CLI 工具的版本号然后在 CI 里用这个文件锁定安装版本。本地开发时也建议用容器或虚拟环境隔离避免全局安装带来的冲突。另外codex cli有一些常用命令值得记一下/compact用于压缩上下文、/model用于切换模型、/resume用于恢复之前的会话。这些命令在长时间开发会话里很有用尤其是当你需要 agent 记住之前的决策时。4. 实操过程从零搭建一套 impeccable 工作流4.1 环境准备与工具安装先列一下我用的工具清单和安装方式。这里以 macOS 为例Linux 和 Windows 的差异我会在注意事项里说明。# 安装 Node.js 环境如果还没有 brew install node20 # 安装 codex cli npm install -g openai/codex-cli # 安装 openspec cli用于管理组件规格 npm install -g openspec-cli # 安装 gitlab cli brew install glab # 安装 browser extension 的开发依赖 npm install -D impeccable/extension-core安装完成后用codex --version和openspec --version确认版本。如果遇到权限问题检查 npm 的全局目录配置。提示如果你在团队里推广这套流程建议把安装步骤写成一个setup.sh脚本新成员 clone 项目后跑一次就行。这比写文档更可靠因为脚本不会过时。4.2 项目初始化与配置文件在项目根目录创建.impeccable目录里面放三个文件.impeccable/ ├── rules.json # 校验规则配置 ├── prompts/ # prompt 模板 │ ├── component.md │ └── page.md └── tools.lock # CLI 工具版本锁定rules.json的内容示例{ spacing: { grid: 8, tolerance: 0 }, contrast: { standard: WCAG_AA, minRatio: 4.5 }, responsive: { breakpoints: [375, 768, 1024, 1440] }, interaction: { requiredStates: [hover, focus, active, disabled] } }这个文件是 browser extension 和 CLI 校验命令的共同数据源。改一处两边都生效。4.3 用 CLI 驱动 agent 生成组件假设我要生成一个导航栏组件。操作流程如下第一步在终端里进入项目目录启动 codex cli 会话codex --project . --prompt-file .impeccable/prompts/component.md第二步在会话里输入具体需求生成一个顶部导航栏组件包含 - Logo 区域左对齐 - 主导航链接居中最多 6 个 - 用户头像下拉菜单右对齐 - 移动端折叠为汉堡菜单 - 滚动时背景从透明变为白色带阴影第三步agent 输出代码后不要急着保存。先跑校验impeccable-check --file src/components/Navbar.tsx这个命令会调用 browser extension 的校验接口在无头浏览器里渲染组件然后逐项检查规则。输出格式类似[PASS] spacing.grid: 所有间距值均为 8 的倍数 [PASS] contrast.text: 文字对比度 5.2:1 [FAIL] interaction.focus: 缺少 focus 状态的可见样式 [PASS] responsive.breakpoints: 覆盖 4 个断点第四步针对 FAIL 项让 agent 修复focus 状态缺少可见样式请为所有可交互元素添加 focus-visible 轮廓 颜色使用主题色宽度 2px偏移 2px。修复后再跑一次校验直到全部 PASS。4.4 browser extension 的实时预览与微调CLI 校验通过后打开浏览器extension 会自动注入一个侧边栏面板。面板里显示当前页面的校验状态并且支持实时微调。比如你可以在面板里拖动一个滑块来调整全局间距基准extension 会实时重新计算所有元素的间距是否符合新的网格。如果某个元素不符合它会在页面上高亮标出。这个功能在跟设计师协作时特别有用。设计师说“间距再大一点”你不用手动改代码直接在面板里调调好了把生成的 CSS 变量导出粘贴回代码里就行。4.5 集成到 CI 流程在.gitlab-ci.yml里加一个 stageimpeccable-check: stage: test script: - npm run build - impeccable-check --all --reporter json report.json - node scripts/check-report.js report.json artifacts: paths: - report.jsoncheck-report.js的逻辑很简单读取 JSON 报告如果有 FAIL 项就process.exit(1)。这样 MR 就会被拦住直到所有校验通过。4.6 参数计算对比度与间距的实际演算拿对比度来说WCAG AA 要求正文文字对比度至少 4.5:1。假设你的背景色是#FFFFFF文字色是#767676对比度计算公式是L1 0.2126 * R 0.7152 * G 0.0722 * B线性化后 contrast (L1 0.05) / (L2 0.05)#767676的亮度值约为 0.184#FFFFFF的亮度值为 1.0。代入公式contrast (1.0 0.05) / (0.184 0.05) 1.05 / 0.234 ≈ 4.49刚好差一点点。所以#767676在白色背景上不满足 AA 标准需要再深一点比如#757575或#6B6B6B。这种计算在 browser extension 里是自动完成的但你得理解原理才能在 agent 生成的颜色值不合理时快速判断。间距方面8px 网格的意思是所有 margin、padding、gap 的值都应该是 8 的倍数。为什么是 8 而不是 10因为 8 能被 2、4、8 整除在响应式缩放时更容易保持比例关系。而且主流设计系统Material Design、Ant Design都采用 8px 基准生态兼容性更好。5. 常见问题与排查技巧实录5.1 agent 生成的代码校验不通过怎么办这是最高频的问题。我的排查顺序是先看 FAIL 项的类型。如果是 spacing 类通常是 agent 用了非标准值比如 12px、20px。直接在 prompt 里强调“所有间距必须是 8 的倍数”就能解决大部分情况。如果是 contrast 类说明 agent 选的颜色不对。这时候不要让它自己调而是给它具体的色值。比如“把文字色改为 #595959背景保持 #FFFFFF”。因为 agent 对色彩对比度的计算能力不稳定给它明确值比让它猜更可靠。如果是 interaction 类通常是 agent 漏掉了某个状态。在 prompt 里列一个状态清单让它逐项确认。5.2 CLI 命令执行失败或超时codex cli在长会话中可能会因为上下文过长而变慢。这时候用/compact命令压缩上下文或者用/resume开一个新会话但保留关键决策记录。如果gitlab cli报认证错误检查GITLAB_TOKEN环境变量是否设置以及 token 是否有api权限。openspec cli在 Windows 上可能需要用 WSL 运行原生 Windows 终端有时会有路径解析问题。5.3 browser extension 不生效或校验结果异常先确认 extension 是否已启用并且有当前页面的访问权限。有些浏览器默认会禁用开发者模式加载的 extension需要手动开启。如果校验结果跟预期不符检查rules.json是否被正确加载。可以在 extension 的控制台里打印当前生效的规则集确认配置没有语法错误。还有一种情况是页面用了 Shadow DOMextension 的样式检测可能穿透不了。这时候需要在规则里配置pierceShadow: true或者把检测逻辑注入到 Shadow Root 内部。5.4 团队协作中的规则冲突不同项目对 impeccable 的定义可能不同。A 项目要求 8px 网格B 项目可能用 4px 网格。解决办法是把.impeccable目录做成可继承的根目录放一套基础规则子项目可以覆盖特定字段。{ extends: ../../.impeccable/rules.json, spacing: { grid: 4 } }这样既保持了统一标准又允许项目级定制。5.5 常见问题速查表问题现象可能原因排查动作解决方式校验全部 PASS 但页面明显有问题规则集未覆盖该维度检查 rules.json 是否缺少对应规则补充规则并重新校验agent 反复生成相同错误prompt 约束不明确查看会话历史中的 prompt增加具体约束和示例CLI 输出乱码终端编码不支持检查 LANG 环境变量设置为 en_US.UTF-8extension 面板不显示权限或版本问题查看浏览器扩展管理页重新加载或更新版本CI 中校验超时无头浏览器启动慢查看 CI 日志增加超时时间或预启动浏览器5.6 几个踩过的坑第一个坑一开始我把校验规则写得太严要求所有颜色都必须来自设计系统的 token。结果 agent 生成的代码几乎全部 FAIL因为它在处理渐变和阴影时会用一些中间色。后来我把规则改成“主要颜色必须来自 token辅助色允许偏差在 5% 以内”通过率就正常了。第二个坑browser extension 的校验在本地跑得好好的一到 CI 就挂。排查后发现是 CI 环境没有安装中文字体导致文字渲染宽度计算错误进而影响了布局校验。解决办法是在 CI 镜像里预装常用字体。第三个坑codex cli的/model命令切换模型后之前的会话上下文会丢失。如果你在一个长任务中途切模型记得先把关键决策用/compact保存下来否则 agent 会“失忆”。6. 扩展思路这套工作流还能怎么用6.1 从组件级扩展到页面级目前这套流程主要针对单个组件。如果你想做整页的 impeccable 校验需要把 browser extension 的检测范围从元素级扩展到页面级。具体来说增加几个维度页面整体信息层级是否清晰、首屏关键内容是否在折叠线以上、滚动深度与内容密度的关系是否合理。这些维度比较主观很难用纯规则描述。我的做法是让 agent 先给页面打一个“设计评分”然后人工复核。评分不达标的页面再进入细项校验。6.2 与设计工具的联动如果你的团队用 Figma 做设计可以写一个脚本把 Figma 的设计 token 导出成.impeccable/rules.json的格式。这样设计稿一更新校验规则自动同步不需要手动维护两套配置。具体实现思路是用 Figma 的 REST API 拉取样式数据然后用一个转换脚本映射到规则字段。这个脚本可以放在 CI 里定时跑也可以手动触发。6.3 多端适配的校验扩展现在这套流程主要针对 Web 端。如果你要做小程序或移动端 H5校验规则需要调整。比如小程序的rpx单位跟px的换算关系、移动端触摸目标的最小尺寸建议 44x44pt、以及不同机型的安全区域适配。这些都可以作为新的规则维度加进rules.json然后让 browser extension 在对应的模拟器环境里执行校验。6.4 性能维度的加入impeccable 不只是视觉上的也包括性能上的。你可以在校验流程里加入 Lighthouse 的指标检测首次内容绘制、最大内容绘制、累积布局偏移。这些指标不达标即使视觉再完美也算不上 impeccable。实现方式是在 CI 里跑一次 Lighthouse把结果跟视觉校验报告合并输出。两个都通过才算真正 PASS。我个人在实际操作中的体会是这套工作流最大的价值不在于“让 AI 替你写代码”而在于它把前端设计中的隐性标准显性化了。以前你说“这个页面做得不够精致”别人可能不知道你指的是什么。现在你有一份校验报告上面列着哪一项不达标、差多少、怎么改。沟通成本降下来了产出质量反而上去了。最后再分享一个小技巧把每次校验失败的原因和修复方式记录到一个lessons.md文件里定期回顾。你会发现有些错误是反复出现的针对这些高频错误优化 prompt 或规则比每次手动修要高效得多。这个文件也会成为团队新成员最好的培训材料。