1. 拆解 impeccable一个面向 AI 编码代理的前端设计约束层第一次看到 “impeccable” 这个词是在几个 AI coding agents 的讨论串里。它被反复提及的方式很特别——不是作为一个独立工具被介绍而是作为“让 AI 写出来的前端不那么丑”的一个关键环节。这个词本身的意思是“无可挑剔的、完美的”放在前端设计语境下它指向的其实是一个很具体的痛点AI 编码代理能生成功能正确的代码但生成的前端界面往往缺乏设计感间距随意、配色突兀、层级混乱。impeccable 要解决的问题就在这个缝隙里。它不是一个 UI 组件库也不是一个设计系统而更像是一层“设计约束”——通过 CLI 或浏览器扩展的形式把一套经过打磨的设计规则注入到 AI 编码代理的工作流中让代理在生成前端代码时自动遵循这些规则。你可以把它理解成给 AI 代理戴上了一副“设计眼镜”让它看到的不是裸的 HTML 和 CSS而是一套有审美标准的输出目标。这个内容适合谁如果你正在用 Codex CLI、Claude Code 这类 AI 编码代理做前端开发并且被生成结果的视觉质量困扰过那 impeccable 的思路值得你花时间研究。如果你只是偶尔用 AI 补全几行 CSS可能感受不深但如果你让代理独立完成整个页面甚至整个前端项目设计约束层的价值就会立刻显现。下面我会从设计思路、核心机制、实操流程和踩坑经验四个维度把这个东西拆开讲清楚。2. 为什么 AI 编码代理需要一层设计约束2.1 AI 生成前端的“功能正确、视觉崩塌”现象用过 Codex CLI 或类似工具生成前端代码的人大概率见过这样的场景你让代理做一个登录页它确实给出了完整的 HTML、CSS 和 JavaScript表单能提交、按钮能点击、响应式断点也写了。但打开浏览器一看输入框和按钮之间的间距是 8px标题和副标题之间是 32px整个卡片贴在页面左上角配色是默认的蓝色链接色加灰色边框。功能上没毛病视觉上像 2005 年的网页。这不是代理“不会写 CSS”而是它在生成时没有稳定的设计决策依据。大语言模型在训练数据里见过无数种设计风格每次生成时它都在这些风格之间随机游走。同一个提示词第一次生成可能用了 16px 圆角第二次变成 4px第三次干脆没有圆角。这种不一致性在单个组件里不明显但放到整个页面甚至整个项目里就会产生强烈的“拼凑感”。2.2 设计约束层的核心思路把审美变成可执行的规则impeccable 的思路不是让 AI“学会设计”而是把设计决策从 AI 的自由发挥中剥离出来变成一套外部的、可执行的规则。这有点像 ESLint 之于 JavaScript——你不是让开发者记住所有代码规范而是用工具在提交前自动检查和修正。具体来说这层约束通常包含几个维度。间距系统定义一套间距刻度比如 4px 基准的 4/8/12/16/24/32/48/64代理生成时必须从这个刻度里取值不能随意写 13px 或 27px。色彩系统提供一组经过对比度校验的颜色变量代理只能引用变量而不能直接写十六进制值。排版层级规定标题、正文、辅助文字的字号和字重组合避免出现 15px 和 16px 混用这种模糊层级。组件模式对按钮、输入框、卡片等常见元素给出标准结构和样式代理在此基础上做变体而不是从零发明。这些规则单独看都很简单但组合起来就形成了一张“设计安全网”。代理在生成时不需要做审美判断只需要在规则允许的范围内选择输出的视觉质量就有了下限保证。2.3 与组件库方案的本质区别有人可能会问那直接用 Tailwind UI 或者 Ant Design 不就行了让代理用现成的组件库不也能保证视觉质量吗区别在于控制粒度和灵活性。组件库提供的是成品组件代理用的时候是在“组装”但组装方式仍然可能出错——比如把两个不同层级的按钮放在一起或者在不该用卡片的地方用了卡片。而且组件库的样式覆盖往往需要写额外的 CSS代理在覆盖时又可能引入新的不一致。impeccable 这类设计约束层提供的是“规则”而不是“成品”。代理仍然在写原生 CSS 或 Tailwind 类名但它写的每一个值都来自受控的集合。这带来的好处是输出更轻量没有组件库的冗余样式、更一致所有值都来自同一套刻度、更容易定制改规则比改组件库简单。代价是代理需要理解规则并主动遵守而不是直接调用现成组件。3. impeccable 的核心机制与工具形态3.1 CLI 形态把设计规则注入代理的工作流impeccable 以 CLI 形式出现时它的角色是在代理生成代码之前或之后介入。常见的工作流有两种。前置注入在代理开始生成前CLI 把设计规则以配置文件或提示词片段的形式写入代理的上下文让代理在生成时就知道有哪些约束。后置校验代理生成完代码后CLI 扫描输出文件检查是否有违反规则的值比如不在间距刻度里的 margin并自动修正或报告。前置注入的关键在于“提示词工程”。设计规则不能以生硬的 JSON 配置直接丢给代理因为代理对结构化配置的理解不如对自然语言描述的理解。好的做法是把规则翻译成一段简洁的、带示例的说明比如“所有间距使用 4 的倍数常用值为 8、16、24、32标题使用 24px/600 字重正文使用 16px/400 字重”。这段说明会作为系统提示的一部分在每次生成时生效。后置校验则更像传统的 lint 工具。它需要解析 CSS 或扫描类名提取出所有间距、颜色、字号值然后与规则集比对。对于不符合的值可以选择自动替换为最接近的合规值或者标记出来让开发者决定。自动替换的风险是可能改变布局意图所以更稳妥的做法是先报告再手动确认。3.2 浏览器扩展形态实时反馈与可视化校验浏览器扩展形态的 impeccable 解决的是另一个问题代理生成的代码在浏览器里渲染出来后如何快速发现视觉问题。CLI 校验的是代码里的值但代码合规不等于视觉效果好——比如两个合规的间距值放在一起可能仍然显得拥挤或松散。扩展的做法通常是在页面上叠加一层“设计审查”视图。它会高亮所有使用了非标准间距的元素用不同颜色标注不同的间距值让开发者一眼看出哪些地方的间距是“野生”的。它还可能显示色彩对比度检查结果标记出低于 WCAG 标准的文字颜色组合。对于排版它可以画出基线网格检查文字是否对齐到网格上。这种可视化反馈的价值在于“所见即所得”。你不需要去读 CSS 代码直接在页面上就能看到哪里出了问题。对于和 AI 代理协作的场景你可以把扩展的截图或报告反馈给代理让它针对性地修正而不是用自然语言描述“左边那个卡片再往右一点”这种模糊指令。3.3 与 Codex CLI 等代理的集成方式impeccable 本身不是一个代理它需要和 Codex CLI、Claude Code 这类工具配合使用。集成方式取决于代理是否支持自定义系统提示或插件机制。对于支持系统提示的代理最直接的方式是把设计规则写进系统提示。Codex CLI 允许通过配置文件或命令行参数指定额外的提示内容你可以把 impeccable 生成的规则摘要放进去。对于支持插件或钩子的代理可以在生成前后自动调用 impeccable 的 CLI 命令实现规则的自动注入和校验。如果代理既不支持系统提示也不支持插件退而求其次的方式是“手动注入”在每次对话开始时把规则摘要作为第一条消息发给代理并明确要求它遵守。这种方式不够自动化但对于轻量使用场景已经够用。实测下来只要规则摘要足够简洁清晰代理在后续生成中遵守的概率很高。4. 实操从零搭建一套 AI 前端设计约束4.1 定义你的设计刻度间距、色彩、排版搭建约束的第一步是定义刻度。这不是让你从零发明一套设计系统而是从成熟的设计系统里“抄”一套经过验证的刻度然后根据项目需要微调。间距刻度建议以 4px 为基准取 4、8、12、16、24、32、48、64、96 这几个值。4px 基准的好处是兼容大多数屏幕的像素密度而且 4 的倍数在视觉上容易形成节奏感。如果你做的是移动端优先的项目可以把基准改成 8px取 8、16、24、32、48、64减少小间距的使用频率。色彩刻度至少需要定义主色品牌色、主色深色变体用于 hover、主色浅色变体用于背景、中性色 5-7 个层级从接近黑到接近白、语义色成功、警告、错误。每个颜色都要检查对比度正文文字与背景的对比度不低于 4.5:1大号文字不低于 3:1。可以用在线对比度检查工具验证或者用 impeccable 扩展自带的检查功能。排版刻度定义 5-6 个层级就够了页面标题28-32px/700、区块标题20-24px/600、卡片标题16-18px/600、正文14-16px/400、辅助文字12-13px/400、微型标签11-12px/500。行高方面标题用 1.2-1.3正文用 1.5-1.6。字重不要超过三种否则页面会显得杂乱。4.2 把规则翻译成代理能理解的提示词定义好刻度后下一步是把它翻译成代理能理解的提示词。这里的关键是“示例优于描述”。不要只写“间距使用 4 的倍数”而要写“卡片内边距用 16px 或 24px卡片之间间距用 16px区块之间间距用 32px 或 48px”。代理对具体示例的遵循度远高于抽象规则。一个可用的提示词模板大概长这样你在生成前端代码时必须遵守以下设计规则 间距所有 margin 和 padding 使用以下值之一4, 8, 12, 16, 24, 32, 48, 64。 卡片内边距用 16 或 24卡片间距用 16区块间距用 32 或 48。 颜色只使用以下 CSS 变量不要写十六进制值 --color-primary: #2563eb; --color-primary-dark: #1d4ed8; --color-text: #1f2937; --color-text-muted: #6b7280; --color-bg: #ffffff; --color-bg-subtle: #f9fafb; --color-border: #e5e7eb; 排版标题用 24px/600正文用 16px/400辅助文字用 13px/400。 行高标题 1.3正文 1.6。 圆角卡片和按钮用 8px 圆角输入框用 6px 圆角。 阴影卡片使用 0 1px 3px rgba(0,0,0,0.1)。这段提示词控制在 200 字以内代理在每次生成时都能完整读取。如果你用的代理支持系统提示把它放在系统提示里如果不支持在每次对话开始时作为第一条消息发送。4.3 用 CLI 做生成后校验与自动修正提示词注入能保证大部分输出合规但代理偶尔还是会“忘记”规则尤其是在生成长文件或复杂布局时。这时候需要 CLI 做后置校验。校验脚本的核心逻辑是读取生成的 CSS 文件或 HTML 中的 style 标签用正则提取所有margin、padding、font-size、color、border-radius的值然后与规则集比对。对于不符合的值计算与规则集中最近值的距离如果距离小于阈值比如 2px自动替换如果距离较大标记出来让开发者决定。下面是一个简化的 Python 校验脚本示例import re SPACING_SCALE [4, 8, 12, 16, 24, 32, 48, 64] COLOR_VARS [--color-primary, --color-text, --color-bg, --color-border] def check_spacing(css_text): pattern r(margin|padding)(?:-(?:top|right|bottom|left))?\s*:\s*(\d)px issues [] for match in re.finditer(pattern, css_text): prop, value match.group(1), int(match.group(2)) if value not in SPACING_SCALE: nearest min(SPACING_SCALE, keylambda x: abs(x - value)) issues.append((prop, value, nearest)) return issues def auto_fix(css_text, issues): for prop, old, new in issues: css_text re.sub( rf({prop}(?:-(?:top|right|bottom|left))?\s*:\s*){old}px, rf\g1{new}px, css_text ) return css_text这个脚本只处理了间距颜色和排版可以按类似思路扩展。实际使用时建议先运行校验但不自动修正人工确认一遍修正建议是否合理再决定是否开启自动修正。自动修正的风险在于可能把有意的设计决策“纠正”掉比如某个地方故意用 20px 间距来制造特殊节奏。4.4 浏览器扩展的安装与使用要点浏览器扩展形态的 impeccable 通常以开发者工具面板或页面浮层的形式工作。安装方式取决于你用的浏览器一般是从扩展商店安装或者以开发者模式加载未打包的扩展。使用时的关键操作有几个。开启审查模式在页面上激活扩展后它会扫描当前页面的所有元素计算每个元素的间距、颜色、字号并与规则集比对。查看问题列表扩展会列出所有不合规的元素按严重程度排序。间距偏差超过 8px 的标红4-8px 的标黄4px 以内的标绿。定位元素点击问题列表里的条目页面会自动滚动到对应元素并高亮显示。导出报告把问题列表导出为 JSON 或 Markdown可以直接粘贴给 AI 代理让它修正。实测下来扩展最有价值的场景是“代理生成后快速检查”。你不需要逐行读 CSS打开页面扫一眼审查面板就知道哪些地方需要让代理返工。对于响应式布局扩展通常还支持切换视口宽度检查不同断点下的合规情况。5. 常见问题与排查技巧实录5.1 代理不遵守规则怎么办这是最常见的问题。你明明在系统提示里写了间距规则代理生成时还是用了 20px 这种非标准值。原因通常有三个规则太长被代理“遗忘”、规则表述不够具体、代理在生成长文件时注意力分散。排查思路先检查规则摘要是否超过了 300 字。超过的话代理在生成到后半段时可能已经“忘记”了前面的规则。解决办法是把规则拆成两部分核心规则间距、颜色放在最前面次要规则圆角、阴影放在最后并在生成过程中定期提醒。如果规则表述太抽象比如只写了“使用标准间距”代理不知道标准是什么就会自由发挥。改成“使用 4、8、16、24、32 这几个值”就具体多了。另一个技巧是“分段生成”。不要让代理一次性生成整个页面而是按区块生成每个区块生成前重新发送规则摘要。这样代理的上下文里始终有规则存在遵守率会明显提高。5.2 自动修正把布局改乱了自动修正的初衷是省去手动改的麻烦但有时候它会把有意的设计改掉。比如你故意用 20px 间距来让某个卡片稍微突出一点自动修正把它改成了 16px视觉节奏就没了。避免这个问题的办法是“白名单机制”。在规则集里额外定义一个“允许的例外值”列表比如[20, 28, 36]这些值虽然不在主刻度里但被认为是合法的特殊值。校验脚本遇到这些值时跳过不报告也不修正。另一个办法是“注释标记”在 CSS 里用/* impeccable-ignore */注释标记某一行校验脚本遇到这个注释就跳过下一行。5.3 颜色对比度不达标怎么调AI 代理生成的颜色组合经常对比度不足尤其是浅色文字放在浅色背景上。扩展的对比度检查会标出这些问题但怎么调需要一些经验。对于正文文字对比度至少 4.5:1。如果当前是 3.8:1最简单的办法是把文字颜色加深一档或者把背景颜色调浅一档。不要试图通过加粗文字来“解决”对比度问题加粗只影响大号文字的 3:1 标准对正文的 4.5:1 标准没有帮助。对于按钮文字如果按钮背景是品牌色文字用白色通常没问题但要检查品牌色本身的亮度。深蓝色背景配白色文字对比度很高但亮黄色背景配白色文字就完全不可读。这种情况下要么把按钮背景改成深色变体要么把文字改成深色。5.4 与现有项目的样式冲突如果你在一个已有项目里引入 impeccable可能会遇到规则与现有样式冲突的情况。比如项目里已经用了 10px、14px 这种非标准间距全面改成 4 的倍数会牵动大量文件。稳妥的做法是“新代码新规则老代码逐步迁移”。在代理生成新组件时应用 impeccable 规则老组件保持原样。等新组件稳定后再逐步把老组件迁移过来。迁移时用 CLI 的校验功能扫描老代码生成一份“待修正清单”按影响范围排序从影响最小的开始改。5.5 代理生成的响应式断点不合规响应式断点本身不在 impeccable 的核心规则里但断点处的间距和排版值仍然需要合规。常见问题是代理在移动端断点用了桌面端的间距值导致小屏幕上元素挤在一起。解决办法是在规则摘要里补充断点相关的说明“移动端768px区块间距用 24px卡片内边距用 16px桌面端≥768px区块间距用 48px卡片内边距用 24px。”这样代理在写媒体查询时就有明确的取值依据。校验脚本也需要扩展能够识别媒体查询块内的值并应用不同的规则集。6. 把 impeccable 融入日常 AI 编码工作流6.1 项目初始化时的规则配置新项目开始时花 10 分钟配置好 impeccable 规则后续能省下大量返工时间。配置步骤很简单从成熟设计系统里选一套刻度写进项目的design-rules.md文件然后在代理的系统提示里引用这个文件。如果你用的是 Codex CLI可以在项目根目录放一个.codex/config文件把规则摘要写进去。如果是 Claude Code可以在CLAUDE.md里追加规则段落。关键是让规则成为项目的一部分而不是每次对话都手动输入。6.2 生成过程中的实时校验生成过程中不要等到整个页面写完才校验而是每生成一个区块就校验一次。CLI 可以监听文件变化每次保存时自动运行校验并输出报告。浏览器扩展可以保持开启状态生成后刷新页面就能看到审查结果。这种“生成-校验-修正”的小循环比“生成整个项目-发现大量问题-大规模返工”的大循环效率高得多。实测下来小循环的修正成本大约是大循环的五分之一。6.3 团队协作时的规则同步如果团队多人使用 AI 代理规则需要同步。把design-rules.md放进版本控制每个人在配置代理时都引用同一份文件。CLI 校验脚本也放进项目仓库作为 CI 的一部分运行。这样即使有人忘了在提示里加规则CI 也会在提交时拦截不合规的代码。浏览器扩展的规则集也可以导出为 JSON 文件放进仓库共享。团队成员导入同一份规则文件审查标准就一致了。6.4 规则迭代与项目演进设计规则不是一成不变的。项目初期可能只需要间距和颜色规则随着项目复杂化可能需要增加动效时长、阴影层级、图标尺寸等规则。每次增加规则时先在小范围试用确认不会造成大量返工后再全面推广。规则迭代的另一个方向是“放宽”。如果发现某条规则在实际使用中频繁被绕过可能说明规则本身不合理。比如间距刻度里没有 20px但项目中大量场景需要 20px那就把 20px 加进刻度而不是强迫所有人用 16px 或 24px。规则是服务于设计的不是设计服务于规则。7. 我踩过的坑与实测有效的技巧第一个坑是“规则太细”。一开始我把间距刻度定成了 4、8、12、16、20、24、28、32、36、40、48、56、64几乎每 4px 一个值。结果代理在生成时频繁在相邻值之间摇摆同一个页面里出现了 16、20、24 三种间距混用的情况。后来把刻度精简到 4、8、16、24、32、48、64代理的选择范围小了输出反而更一致。第二个坑是“只靠提示词不做校验”。有段时间我偷懒只在系统提示里写了规则没有配 CLI 校验。结果代理在生成大型页面时后半部分的合规率明显下降。后来加上校验脚本每次生成后自动扫描不合规的地方让代理针对性修正整体合规率从 70% 左右提升到了 95% 以上。第三个坑是“自动修正太激进”。开启自动修正后有一次代理生成的页面里有个卡片用了 20px 内边距自动修正把它改成了 16px结果卡片里的文字换行了布局反而变差。后来改成“先报告后修正”每次修正前人工确认一遍虽然多花几秒钟但避免了布局事故。实测有效的技巧里最值得分享的是“规则摘要 示例代码”。不要只给代理规则文字还要给一段符合规则的示例代码。比如给一个卡片组件的 HTML 和 CSS里面所有间距、颜色、字号都合规。代理看到示例后模仿的准确率比只看文字规则高很多。这段示例代码控制在 30 行以内放在规则摘要后面效果立竿见影。另一个技巧是“定期重置上下文”。代理在长对话中会积累大量历史信息规则摘要可能被淹没。每隔 10-15 轮对话重新发送一次规则摘要或者干脆开一个新对话把规则摘要作为第一条消息。这样代理的“注意力”始终在规则上合规率不会随时间下降。最后分享一个排查技巧如果代理反复在某个特定值上违规比如总是用 20px 而不是 16px 或 24px检查一下你的规则摘要里是不是有歧义。比如写了“卡片内边距用 16 或 24”代理可能理解成“16 到 24 之间的值都可以”于是选了 20。改成“卡片内边距用 16px 或 24px不要用其他值”违规就消失了。规则表述的精确度直接决定代理的遵守程度。