1. 从impeccable这个词说起为什么前端设计需要AI代理来兜底第一次看到impeccable被拿来命名一个跟AI coding agents相关的项目我脑子里蹦出来的第一个念头是这词选得挺狂。impeccable无瑕的、挑不出毛病的。做前端的人都懂这个词在真实项目里几乎是个诅咒——你永远会在某个断点、某个浏览器、某个边缘状态下发现一个像素的偏差然后花两小时去修它。但恰恰是这个狂点出了当前AI coding agents在前端设计领域最尴尬的处境。过去一年多我陆陆续续试过市面上主流的几类AI编程代理有跑在终端里的CLI工具有挂在编辑器里的插件也有直接做成浏览器扩展的形态。它们在写后端逻辑、写脚本、写数据处理代码的时候表现相当能打可一旦进入前端设计这个领域输出质量就开始飘。飘在哪飘在它们能跑和好看之间那道巨大的鸿沟。一个AI代理可以给你生成一个能正常渲染的React组件按钮能点、表单能提交、路由能跳转功能上挑不出错。但你把它丢给设计师看一眼对方大概率会皱眉间距不对、层级混乱、颜色对比度不够、hover状态生硬、移动端直接塌掉。这就是functional but not impeccable——能用但离无瑕差得远。所以当我看到impeccable这个标题配上AI coding agents、frontend design、CLI、browser extension这几个热搜词我基本能判断出它想解决的是什么问题让AI代理在前端设计这个环节从能生成进化到生成得挑不出毛病。这不是一个单纯的技术问题而是一个工作流问题——它需要CLI负责工程侧的自动化需要browser extension负责视觉侧的实时校验需要AI agent在中间做决策和修正。这篇文章我想聊的就是这套思路。不管你是刚接触AI coding agents的新手还是已经在用codex cli、zcode cli这类工具做日常开发的老手只要你的工作里涉及前端设计这套逻辑都值得你花时间理解。我会把impeccable背后的核心思路拆开讲清楚它为什么这么设计、每一步怎么落地、哪些坑我踩过、哪些参数和配置可以直接抄。2. 拆解impeccable的核心思路AI代理如何理解无瑕2.1 前端设计的无瑕到底由什么构成在动手之前得先把impeccable这个目标量化否则AI代理根本不知道自己要往哪个方向优化。我自己的经验是前端设计的无瑕可以拆成四个可验证的维度这四个维度也是后面配置AI代理时的检查清单。第一个维度是视觉一致性。同一套设计系统里按钮的圆角、卡片的阴影、标题的字重必须保持统一。AI代理最容易犯的错就是每个组件单独看都还行放一起就打架。原因很简单它在生成每个组件时是独立推理的没有全局的设计token约束。第二个维度是响应式完整性。桌面端好看不代表移动端能用。断点切换时布局的塌陷方式、字号的缩放比例、触摸目标的最小尺寸这些都需要显式定义。很多AI代理默认只考虑一个视口宽度生成出来的东西在窄屏上直接溢出。第三个维度是交互状态覆盖。一个按钮至少有default、hover、active、focus、disabled五种状态一个输入框至少有default、focus、error、success四种。AI代理经常只生成default状态剩下的靠浏览器默认样式兜底结果就是交互体验割裂。第四个维度是可访问性基线。颜色对比度、语义化标签、键盘导航、屏幕阅读器友好度这些不是锦上添花而是无瑕的硬门槛。一个对比度只有2:1的灰色文字视觉上再高级也是不合格的。把这四个维度列出来之后你会发现impeccable其实是一个可拆解、可检查、可自动化的目标。这正是AI代理能介入的前提——如果目标本身模糊代理就无从下手。2.2 为什么是CLI加浏览器扩展的组合拳热搜词里同时出现了CLI和browser extension这不是巧合。我一开始也疑惑为什么不做成一个纯CLI工具或者纯浏览器插件非要两个形态并存。后来自己搭了一套类似的流程才明白这两个形态解决的是完全不同的问题。CLI解决的是工程侧的自动化。它跑在你的项目目录里能读文件、能改代码、能跑构建、能调lint。当你让AI代理去修一个组件的间距问题时它需要通过CLI去定位文件、修改样式、重新构建、验证结果。这一整套动作必须在工程环境里完成浏览器扩展做不到。浏览器扩展解决的是视觉侧的实时校验。代码改完了构建通过了但页面到底长什么样间距是不是真的对了对比度是不是真的达标了这些必须在一个真实渲染的浏览器环境里才能验证。扩展能拿到computed style、能截图、能跑可访问性扫描这些是CLI拿不到的。所以impeccable的核心思路是CLI负责改扩展负责看AI代理负责在两者之间做决策。改完看一眼不对再改直到视觉校验通过。这个闭环听起来简单但落地时有很多细节。提示如果你现在只用CLI工具做前端开发强烈建议补上一个浏览器侧的校验环节。我见过太多构建通过但页面崩了的案例纯CLI流程根本发现不了。2.3 AI代理在这个闭环里扮演什么角色很多人对AI coding agents的理解还停留在你描述需求它生成代码。但在impeccable这套思路里代理的角色更像一个有审美的工程助手它要做三件事。第一件是翻译。把这个卡片看起来有点挤这种模糊的人类反馈翻译成具体的CSS改动比如padding从12px调到16px、gap从8px调到12px。这个翻译能力是代理的核心价值也是它区别于普通代码生成器的地方。第二件是验证。改完之后它要主动去检查改动是否真的解决了问题而不是改完就交差。这需要它调用浏览器扩展的校验能力拿到视觉反馈后再判断。第三件是收敛。前端调整往往牵一发动全身改了间距可能影响布局改了颜色可能影响对比度。代理要能识别这些连锁反应避免按下葫芦浮起瓢。理解了这三个角色你就明白为什么单纯的代码生成工具做不好前端设计——它们只做了第一件事缺了验证和收敛。3. 核心细节解析让AI代理真正看懂前端3.1 设计token的注入方式与参数选择AI代理要生成一致的前端前提是它知道你的设计系统长什么样。最直接的办法是把设计token显式注入到它的上下文里。我试过几种注入方式效果差异很大。最粗糙的方式是在prompt里写一段自然语言描述比如主色是蓝色圆角是8px。这种方式代理理解得很模糊生成出来的东西经常跑偏。稍微好一点的是给它一个JSON格式的token文件让它读取。但即便如此代理在生成具体组件时也未必会严格遵守。我实测下来最稳的方式是把token同时注入到三个地方一是作为CSS变量写进全局样式文件二是作为配置文件放在项目根目录供代理读取三是在prompt里明确要求所有颜色和间距必须引用token禁止硬编码。三重约束下代理的遵守率能到90%以上。具体到参数选择间距系统我建议用4px或8px的倍数作为基准。为什么是4和8因为这两个数字能被大多数常见尺寸整除缩放时不容易出现半像素。字号系统建议用1.25或1.333的模数递增这是排版学里验证过的比例视觉上最舒服。颜色系统至少要定义primary、secondary、neutral、success、warning、error六组每组给出50到900的色阶。{ spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, radius: { sm: 4px, md: 8px, lg: 16px, full: 9999px }, fontScale: 1.25 }这份配置可以直接抄改改数值就能用。关键是让代理在每次生成前都读到它。3.2 浏览器扩展如何做视觉校验浏览器扩展做视觉校验核心是拿到渲染后的真实数据。这里有几个技术点值得展开。首先是computed style的读取。扩展可以通过getComputedStyle拿到元素最终生效的样式这比读CSS源码靠谱得多因为源码里可能有层叠、继承、媒体查询的影响。代理拿到computed style后就能判断实际间距是不是符合token定义。其次是对比度计算。可访问性标准里正文文字的对比度至少要4.5:1大号文字至少3:1。扩展可以自动计算每个文本元素的对比度把不达标的标出来。这个计算不复杂但手动做很费时间交给扩展自动化非常划算。第三是多视口截图。扩展可以模拟不同的视口宽度分别截图然后让代理对比。我一般会设三个断点375px手机、768px平板、1440px桌面。代理对比三张截图就能发现响应式问题。第四是DOM结构检查。语义化标签用得对不对、有没有缺失alt属性、heading层级是不是跳级这些都能通过扩展扫描DOM发现。注意视觉校验不要只看截图。截图能发现布局问题但发现不了对比度、语义、键盘导航这些问题。一定要结合computed style和DOM检查一起做。3.3 代理的上下文管理别让它忘事用AI coding agents做前端一个特别容易被忽视的问题是上下文管理。前端项目文件多、依赖多、样式层级深代理的上下文窗口很容易被塞满然后它就开始忘事——忘了你的设计token、忘了之前的修改、忘了你强调过的约束。我的做法是分层管理上下文。第一层是常驻上下文放设计token、项目规范、核心约束这部分永远不清理。第二层是任务上下文放当前正在改的组件相关文件任务完成后清理。第三层是临时上下文放截图、报错信息这些一次性内容用完即弃。codex cli这类工具一般有/compact命令来压缩上下文我建议在每完成一个组件的修改后就手动compact一次把临时内容清掉保留常驻部分。这样能显著降低代理失忆的概率。另外把设计规范写成一份独立的markdown文件放在项目里让代理每次任务开始时先读一遍也是个好习惯。这份文件不用长一两页就够但能省下大量反复强调的功夫。4. 实操过程从零搭一套impeccable工作流4.1 环境准备与工具选型先说工具选型。CLI侧我目前主要用codex cli它的/model、/resume、/compact这几个命令对前端这种需要反复迭代的场景很友好。安装方式各平台略有差异核心就是把它加到PATH里然后在项目目录下初始化。浏览器扩展侧我建议自己写一个轻量的或者用现成的可访问性检查扩展做基础再补上截图和computed style导出的能力。自己写的好处是能定制输出格式直接喂给代理。项目侧的准备包括一份设计token文件、一份项目规范markdown、一个能跑起来的开发服务器。开发服务器很关键因为扩展需要访问真实渲染的页面。# 项目初始化的大致流程 mkdir impeccable-demo cd impeccable-demo # 初始化前端项目以vite为例 npm create vitelatest . -- --template react npm install # 启动开发服务器 npm run dev启动后记下本地地址扩展需要配置这个地址才能注入校验脚本。4.2 让代理完成第一个组件的无瑕化我拿一个最典型的场景来演示一个卡片组件初始版本功能正常但视觉粗糙。流程是这样的。第一步把卡片组件的现状描述给代理同时附上设计token和规范文件。描述要具体比如卡片内边距是12px但token里md是16px需要统一。第二步代理通过CLI读取组件文件定位到样式部分做修改。这一步它会给出diff你要看一眼确认改动方向对不对。第三步改完后代理触发浏览器扩展做校验。扩展返回computed style、对比度报告、三视口截图。第四步代理根据校验结果判断是否达标。如果对比度不够它会调整颜色如果移动端溢出它会调整布局。第五步重复第三、四步直到校验通过。这个循环我实测下来一个中等复杂度的组件大概需要2到4轮。第一轮通常能解决80%的问题剩下的20%是边缘情况比如focus状态的outline、disabled状态的透明度。4.3 参数计算间距和对比度的具体算法这里展开讲两个最常需要计算的参数因为代理虽然能算但你得知道它算得对不对。间距的倍数校验。假设基准是8px那么所有间距应该是8的倍数。代理改完之后你可以让它输出所有间距值然后检查是否能被8整除。不能整除的要么是漏改要么是有特殊原因。这个检查很简单但能抓出大量不一致。对比度的计算。对比度公式是(L1 0.05) / (L2 0.05)其中L是相对亮度。相对亮度的计算要先做sRGB到线性的转换如果通道值小于等于0.03928除以12.92否则用((值 0.055) / 1.055) ^ 2.4。三个通道分别算完再按0.2126、0.7152、0.0722的权重加权。举个例子纯黑#000000的相对亮度是0纯白#FFFFFF是1对比度就是(1 0.05) / (0 0.05) 21。这就是理论最大值。常见的灰色文字#767676配白底对比度大约是4.54刚好过4.5的线。再浅一点就不达标了。代理做这个计算时你要留意它有没有正确处理透明度。带alpha的颜色要先和背景混合再算直接拿alpha值算会出错。4.4 把校验结果反馈给代理的正确姿势校验结果怎么反馈给代理直接影响它下一轮的修改质量。我踩过的坑是直接把原始JSON丢给它它经常抓不住重点改了一堆无关的东西。后来我改成结构化反馈把问题按严重程度分级每个问题给出元素定位、当前值、期望值、建议方向。比如严重按钮文字对比度2.8低于4.5建议加深文字颜色或提亮背景。这样代理拿到的是明确的待办清单而不是一堆需要自己解读的数据。修改效率明显提升。另外反馈里要包含上下文。比如某个间距不对要告诉代理这个间距在哪个组件、哪个断点下生效否则它可能改错地方。5. 常见问题与排查技巧实录5.1 代理改完代码但页面没变化这是最高频的问题。原因通常有三个一是开发服务器的热更新没生效二是代理改的文件不是实际生效的文件比如改了源码但页面用的是构建产物三是浏览器缓存。排查顺序先手动刷新页面看有没有变化没变化就检查代理改的文件路径对不对再检查开发服务器有没有报错。我遇到过代理改了一个同名但不同目录的组件文件改了半天页面纹丝不动最后发现是路径问题。提示让代理在每次修改前先确认目标文件的绝对路径能避免大部分这类问题。5.2 对比度达标了但视觉上还是别扭对比度是硬指标但视觉舒适度是软指标。有时候对比度刚好4.5文字看起来还是发灰。这种情况通常是字重太细或者字号太小导致的。我的经验是正文文字对比度最好做到7:1以上4.5只是底线。大号标题可以放宽到3:1但字重不能低于500。代理如果只盯着4.5的线生成的东西会显得及格但不好看。解决办法是在规范里把对比度要求提高比如正文要求7:1让代理有更大的优化空间。5.3 响应式断点处布局塌陷断点塌陷的典型表现是桌面端三列布局到平板变成两列时中间出现空隙到手机变成一列时元素溢出。根因通常是用了固定宽度而不是弹性布局。排查时重点看有没有写死的width值。代理生成布局时容易图省事写固定宽度这在响应式场景下是灾难。规范里应该明确要求用flex、grid、minmax、clamp这些弹性方案。我一般会让代理在生成布局后主动检查所有width属性把固定值改成弹性值。这个检查能提前拦下大部分塌陷问题。5.4 代理反复改同一个问题改不好这种情况说明代理陷入了局部最优。它可能一直在微调某个值但问题的根因在别处。比如它一直在调padding但实际问题是父容器的box-sizing不对。遇到这种情况我会中断当前循环让代理重新描述一遍问题从更高层面分析。有时候换个角度描述它就能跳出死循环。另一个办法是给它一个退一步的指令让它先回滚到上一个稳定版本再重新分析。codex cli的/resume命令在这里很有用能回到之前的会话状态。5.5 常见问题速查表问题现象可能原因排查方向解决思路改完无变化热更新失效/路径错误/缓存手动刷新、检查路径、清缓存确认目标文件绝对路径对比度达标但难看字重太细/字号太小检查font-weight和font-size提高对比度要求到7:1断点处塌陷固定宽度/缺少弹性搜索width属性改用flex/grid/clamp反复改不好陷入局部最优重新描述问题回滚后重新分析代理失忆上下文溢出检查上下文长度分层管理定期compact6. 工具选型与工作流优化的经验之谈6.1 CLI工具的选择与配置要点市面上CLI形态的AI编程工具不少选型时我主要看三点上下文管理能力、文件操作精度、以及是否支持会话恢复。上下文管理能力决定了代理能记住多少东西。前端项目上下文消耗大管理能力弱的工具很快就撑不住。文件操作精度决定了它改代码时会不会误伤无关文件。会话恢复能力决定了你中断后能不能接着干这对需要反复迭代的前端工作很重要。配置上我建议把常用命令做成别名减少重复输入。比如把启动、compact、resume这几个高频操作设成短命令。另外把项目规范文件路径写进工具的默认配置让它每次启动自动读取。6.2 浏览器扩展的定制方向现成的可访问性扩展能用但定制过的更顺手。我建议至少定制三个功能一是把校验结果导出成结构化JSON方便喂给代理二是支持多视口批量截图三是能高亮显示不达标元素方便人工复核。定制扩展不需要很深的浏览器开发功底核心就是content script注入、消息通信、以及调用一些浏览器API。网上有不少开源模板可以参考。6.3 工作流的节奏控制最后聊聊节奏。用AI代理做前端最忌讳的是一口气让它改完所有组件。前端组件之间有耦合一次性改太多出了问题很难定位。我的节奏是单组件闭环一个组件从生成到校验通过走完整个循环再进入下一个。这样每个组件都是稳定的后续组件可以基于稳定版本开发。另外每完成一批组件做一次全局校验检查跨组件的一致性。这一步能抓出单个组件校验发现不了的问题比如不同组件的按钮样式不统一。这套流程跑顺之后我做前端的速度大概提升了三到四倍而且质量比手写更稳定因为校验是自动化的不会因为疲劳而漏掉细节。踩过的坑主要集中在前期的配置和规范梳理上这部分投入一次后面长期受益。如果你也在用AI代理做前端建议从一个小项目开始把这套CLI加扩展加代理的闭环跑通再逐步扩展到正式项目。规范文件越早写越好它是整个流程的地基。