1. 项目缘起为什么我们需要一个叫“impeccable”的前端设计辅助工具第一次看到“impeccable”这个词是在一个前端技术群里。有人丢了一张截图说“这玩意儿生成的页面比我手写的还干净”。截图里是一个命令行界面输入一句自然语言描述几秒钟后终端里就吐出了一段结构清晰的 HTML 和 CSS 代码浏览器打开一看布局规整、间距舒适、配色克制确实配得上“impeccable”这个词——无可挑剔。这个项目本质上是一个面向AI coding agents的前端设计辅助工具形态上同时提供了CLI和browser extension两种入口。它的核心价值在于把“设计感”这个原本依赖人类审美和经验的东西通过一套可复用的规则和提示词工程注入到 AI 生成前端代码的过程中。换句话说它解决的是当前 AI 写前端代码时最让人头疼的问题——能跑但丑。我接触过不少用 AI 生成前端页面的场景无论是用 codex cli、claude code 还是其他 agent 工具生成出来的代码往往功能正确但视觉上一言难尽间距要么挤成一团要么空旷得离谱颜色搭配像是随机抽的字体层级混乱响应式断点形同虚设。impeccable 试图做的就是在 AI 生成代码的链路上加一层“设计约束层”让输出结果在视觉上达到可交付的水准。这篇文章适合几类人看一是正在用 AI coding agents 做前端开发、但苦于输出质量不稳定的工程师二是对 CLI 工具链感兴趣、想了解如何把设计规范工程化的技术人三是做 browser extension 开发、想看看别人怎么把设计能力封装成浏览器插件的开发者。我会从项目设计思路、核心实现细节、实操流程、常见问题几个维度展开尽量把每个环节的“为什么”讲清楚。2. 核心设计思路拆解设计规范如何变成可执行的代码约束2.1 从“设计系统”到“提示词系统”的映射逻辑传统的前端设计流程里设计师产出设计系统Design System里面包含颜色变量、间距刻度、字体层级、圆角规范、阴影层级等。工程师拿到这套系统后在代码里通过 CSS 变量或预处理器变量来引用。这个流程的问题是它依赖人类去理解和执行AI 并不天然知道这些规范。impeccable 的思路很直接把设计系统里的每一个决策点转化成 AI 能理解的提示词片段和代码模板。比如间距人类设计师会说“用 4px 的倍数”impeccable 会把它转化成一组具体的 CSS 变量定义并在生成代码时强制引用这些变量而不是让 AI 自由发挥写margin: 13px这种随意值。我拆解过它的提示词结构大致分为三层基础层定义原子级的样式变量包括颜色、间距、字号、行高、圆角、阴影、过渡时长。这一层是硬约束AI 生成代码时必须从这些变量里选值。组合层定义常见 UI 组件的样式规则比如按钮、卡片、表单、导航栏。这一层是半硬约束AI 可以参考这些规则来组装组件也可以根据场景微调。布局层定义页面级的布局模式比如栅格系统、容器宽度、断点策略。这一层是软约束AI 根据内容结构选择合适的布局模式。这种分层设计的好处是既保证了视觉一致性又给 AI 留出了根据具体内容做调整的空间。如果全部硬约束生成的页面会千篇一律如果全部软约束又回到“能跑但丑”的老路。2.2 为什么选择 CLI Browser Extension 双形态impeccable 同时提供 CLI 和 browser extension这个选择背后有明确的场景考量。CLI 的典型使用场景是你在终端里用 codex cli 或类似工具做开发想让 AI 直接生成一个完整的页面或组件。这时候你可以在命令行里调用 impeccable把设计约束注入到生成流程里。CLI 的优势是自动化程度高可以集成到脚本里适合批量生成或 CI/CD 流程。Browser extension 的典型使用场景是你在浏览器里看到一个页面想快速提取它的设计规范或者想对当前页面做设计层面的审查。extension 可以直接读取页面的计算样式分析出间距、颜色、字体等实际使用的值然后给出优化建议。这个场景是 CLI 覆盖不到的因为 CLI 拿不到浏览器渲染后的真实样式。两者共享同一套设计规则引擎只是输入输出的接口不同。CLI 的输入是自然语言描述或代码片段输出是生成或优化后的代码extension 的输入是当前页面的 DOM 和样式输出是设计审查报告或优化后的样式建议。2.3 与现有 AI coding agents 的协作方式impeccable 本身不是一个独立的 AI 模型它更像是一个“设计中间件”。它不直接生成代码而是把设计约束转化成 AI 能理解的提示词然后交给底层的 AI agent 去执行。这种设计的好处是解耦。你可以用 codex cli也可以用其他 agent 工具只要它们支持自定义提示词或系统指令就能接入 impeccable 的设计规则。我实测下来接入方式主要有两种一种是通过配置文件。impeccable 会生成一个配置文件里面包含设计变量和规则你在 agent 的配置里引用这个文件agent 在生成代码时就会自动带上这些约束。另一种是通过命令行参数。在调用 agent 时把 impeccable 生成的提示词片段作为参数传进去。这种方式更灵活适合临时调整设计规范。注意不同 agent 工具对提示词的解析方式不同有些工具会把提示词里的 CSS 变量定义当成普通文本忽略掉这时候需要把变量定义转换成 agent 能识别的格式比如 JSON 或 YAML。3. 核心细节解析设计规则引擎的内部构造3.1 颜色系统的工程化处理颜色是前端设计里最容易出问题的地方。AI 生成代码时经常写出#3a7bd5这种看起来还行但缺乏系统性的颜色值。impeccable 对颜色的处理方式是先定义一组基础色板然后通过算法生成完整的色阶。基础色板通常包含 5 到 7 个主色每个主色生成 9 到 11 个明度层级。生成算法用的是 HSL 色彩空间因为 HSL 比 RGB 更符合人类对颜色的直觉。具体做法是固定色相和饱和度调整明度从 95% 到 10%生成从浅到深的色阶。这样做的好处是AI 在生成代码时只需要从色阶里选一个变量名比如--color-primary-500而不是自己编一个十六进制值。变量名本身携带了语义信息后续维护和主题切换也方便。我实际用下来这套颜色系统在生成按钮、卡片、提示框等组件时效果很明显。以前 AI 生成的按钮悬停态和默认态颜色差异要么太大要么太小现在因为色阶是预先定义好的悬停态直接用相邻色阶视觉过渡很自然。3.2 间距系统的数学约束间距是另一个重灾区。AI 生成代码时间距值往往是“看起来差不多就行”导致页面里出现 12px、13px、15px 这种不规律的值。impeccable 的间距系统基于一个基准值通常是 4px 或 8px生成一组等比或等差数列。我看到的实现里用的是 4px 基准生成如下间距刻度变量名值典型用途--space-14px图标与文字间距--space-28px紧凑元素间距--space-312px表单元素内边距--space-416px卡片内边距--space-520px段落间距--space-624px区块间距--space-832px大区块间距--space-1040px页面级间距--space-1248px章节间距--space-1664px页面顶部/底部留白这套刻度不是随便定的。4px 基准是因为大多数屏幕的像素密度下4px 是一个视觉上可感知的最小单位。刻度值的选择参考了斐波那契数列的变体保证相邻刻度之间的视觉差异既不过于突兀也不过于微弱。实操心得如果你的项目面向移动端可以把基准值改成 8px因为移动端屏幕小4px 的差异在视觉上不够明显。但桌面端建议保持 4px否则间距层级会显得太粗糙。3.3 字体层级的语义化定义字体层级的问题在于AI 经常把字号和字重混在一起用导致标题和正文的区分度不够。impeccable 的做法是定义一套语义化的字体样式每个样式包含字号、字重、行高、字间距四个属性。常见的层级定义如下Display用于页面主标题字号 36-48px字重 700行高 1.1字间距 -0.02emHeading 1用于区块标题字号 28-32px字重 600行高 1.2字间距 -0.01emHeading 2用于子区块标题字号 22-24px字重 600行高 1.3字间距 0Heading 3用于卡片标题字号 18-20px字重 500行高 1.4字间距 0Body用于正文字号 15-16px字重 400行高 1.6字间距 0Caption用于辅助文字字号 13-14px字重 400行高 1.5字间距 0.01em这套定义的关键在于每个层级都有明确的用途说明。AI 在生成代码时根据内容的语义角色选择对应的样式而不是凭感觉设字号。3.4 响应式断点的策略选择响应式设计是 AI 生成前端代码时最容易忽略的部分。很多 AI 生成的页面在桌面端看着还行一到移动端就崩了。impeccable 的断点策略是移动优先定义三个核心断点sm640px对应大屏手机横屏和小平板竖屏md768px对应平板竖屏和部分平板横屏lg1024px对应桌面端和小部分大屏平板选择这三个断点而不是更细的粒度是因为断点越多AI 需要处理的布局变体就越多出错概率也越大。三个断点覆盖了绝大多数设备场景同时保持了实现复杂度可控。在生成代码时impeccable 会强制要求 AI 为每个断点定义布局规则而不是只写桌面端样式然后加个media了事。具体做法是在提示词里明确要求“为每个组件定义 sm、md、lg 三个断点下的布局行为如果某个断点下布局不变显式声明继承上一断点。”4. 实操过程从安装到生成第一个页面的完整记录4.1 环境准备与 CLI 安装impeccable 的 CLI 安装方式取决于你的运行环境。我实测下来最稳妥的方式是通过包管理器安装。假设你用的是 Node.js 环境安装命令如下npm install -g impeccable-cli安装完成后运行impeccable --version验证是否成功。如果提示命令找不到检查一下 npm 的全局 bin 目录是否在 PATH 里。注意如果你同时安装了多个版本的 Node.js确保全局安装的包和当前使用的 Node.js 版本匹配。我踩过一次坑用 nvm 切换版本后之前装的 CLI 工具全部失效了因为全局包是装在旧版本下的。安装完成后需要初始化一个项目配置。在项目根目录下运行impeccable init这个命令会生成一个impeccable.config.json文件里面包含默认的设计变量和规则。你可以直接用它也可以根据项目需求修改。4.2 配置文件的关键参数解读配置文件是 impeccable 的核心它决定了生成代码时使用的设计规范。我截取几个关键参数说明{ baseSpacing: 4, colorPalette: { primary: #3b82f6, secondary: #64748b, accent: #f59e0b }, fontFamily: { sans: Inter, system-ui, sans-serif, mono: JetBrains Mono, monospace }, breakpoints: { sm: 640, md: 768, lg: 1024 }, outputFormat: css-variables }baseSpacing控制间距刻度的基准值默认 4px。colorPalette定义主色、辅色和强调色impeccable 会根据这三个颜色自动生成完整色阶。fontFamily定义字体栈建议用系统字体优先避免加载外部字体带来的性能问题。breakpoints定义响应式断点单位是像素。outputFormat控制输出格式支持css-variables、scss-variables、tailwind-config三种。我一般会把outputFormat设成tailwind-config因为 Tailwind 的原子化类名和 AI 生成代码的配合度很高。impeccable 会生成一个tailwind.config.js文件里面包含所有设计变量AI 生成代码时直接引用 Tailwind 类名即可。4.3 用自然语言生成第一个页面配置完成后就可以用 CLI 生成页面了。基本命令格式是impeccable generate 一个产品落地页包含导航栏、英雄区、三个特性卡片、用户评价区和页脚运行后CLI 会调用底层的 AI agent把设计约束和你的描述一起传进去。生成过程通常需要 10 到 30 秒取决于页面复杂度和网络状况。生成完成后会在当前目录下创建一个output文件夹里面包含index.html、styles.css和script.js。用浏览器打开index.html就能看到生成的页面。我实测生成一个包含五个区块的落地页耗时约 22 秒生成的 HTML 结构清晰CSS 里所有间距和颜色都引用了变量没有出现硬编码的值。页面在桌面端和移动端的表现都正常没有出现布局错乱。4.4 Browser Extension 的安装与使用Browser extension 的安装方式取决于你用的浏览器。以 Chrome 为例在扩展管理页面开启开发者模式然后加载 impeccable 的扩展文件夹。安装完成后浏览器工具栏会出现 impeccable 的图标。使用场景主要有两个一是设计审查。打开任意网页点击 impeccable 图标它会分析当前页面的样式生成一份报告指出间距不一致、颜色不协调、字体层级混乱等问题。我拿几个常见的网站试过报告里指出的问题确实存在比如某个按钮的 padding 是 13px 而不是 12px 或 16px这种细微的不一致肉眼很难发现但工具能准确识别。二是样式提取。如果你看到一个页面的设计风格很喜欢可以用 impeccable 提取它的设计变量生成一份配置文件然后用在你的项目里。这个功能对于快速复刻设计风格很有用但要注意版权问题不要直接复制别人的品牌色和独特设计元素。实操心得extension 的设计审查功能在开发阶段特别有用。我习惯在本地开发时开着它每次改完样式刷新页面它都会重新分析并给出建议。相当于有一个设计规范检查器在实时工作。5. 常见问题与排查技巧实录5.1 生成代码时设计约束不生效这是最常见的问题。表现是 AI 生成的代码里出现了硬编码的颜色值和间距值没有引用配置文件里的变量。排查思路如下首先检查配置文件是否被正确加载。运行impeccable config --show查看当前生效的配置。如果配置为空或不是你的项目配置说明配置文件路径不对。impeccable 默认从当前目录查找impeccable.config.json如果你在子目录里运行命令需要加上--config参数指定路径。其次检查 AI agent 是否支持提示词注入。有些 agent 工具对系统提示词的长度有限制如果 impeccable 生成的提示词太长agent 可能会截断或忽略部分内容。解决办法是精简配置只保留必要的设计变量或者把提示词拆分成多次注入。最后检查输出格式是否匹配。如果你用的是 Tailwind 项目但outputFormat设成了css-variables生成的代码里就不会有 Tailwind 类名。确保输出格式和项目技术栈一致。5.2 响应式布局在移动端错乱AI 生成的响应式代码经常在移动端出问题典型表现是元素溢出、文字重叠、点击区域太小。排查时重点关注以下几点检查 viewport meta 标签是否存在。AI 有时会忘记加这个标签导致移动端浏览器按桌面宽度渲染。正确的写法是meta nameviewport contentwidthdevice-width, initial-scale1.0检查断点定义是否和配置文件一致。如果配置文件里定义的是 640px、768px、1024px但生成代码里用的是 600px、900px、1200px说明 AI 没有正确读取配置。这时候需要在提示词里更明确地强调断点值。检查是否有元素设置了固定宽度。AI 经常给容器设width: 1200px这种固定值在移动端就会溢出。正确的做法是用max-width配合width: 100%。5.3 CLI 命令执行报错排查CLI 报错通常有几类权限问题、依赖缺失、网络超时。权限问题表现为EACCES错误解决办法是用sudo运行或者修改 npm 全局目录权限。依赖缺失表现为Cannot find module错误运行npm install重新安装依赖即可。网络超时表现为命令卡住不动检查网络连接或者设置更长的超时时间。我整理了一个常见错误速查表错误信息可能原因解决办法EACCES全局安装权限不足用 sudo 或修改 npm 目录权限Cannot find module依赖未安装运行 npm installETIMEDOUT网络超时检查网络增加超时参数Config not found配置文件路径错误用 --config 指定路径Invalid output format输出格式不支持检查 outputFormat 值5.4 设计审查报告误报处理Browser extension 的设计审查功能偶尔会误报比如把有意的设计决策当成问题。典型场景是品牌色和标准色阶不一致或者某个组件的间距故意打破规律。处理方式是给 impeccable 加白名单。在配置文件里添加ignoreRules数组把不想被检查的规则加进去。比如{ ignoreRules: [color-palette-consistency, spacing-scale] }这样 extension 在审查时会跳过这些规则。但要注意白名单不要加太多否则审查功能就形同虚设了。我一般只对确实有设计意图的例外情况加白名单并且会在代码注释里说明原因。6. 进阶用法把 impeccable 集成到日常开发流6.1 与 codex cli 的深度集成codex cli 是我用得比较多的 AI coding agent它支持自定义系统提示词。把 impeccable 的设计规则注入到 codex cli 的方式是在 codex 的配置文件里引用 impeccable 生成的提示词文件。具体操作是先运行impeccable export --format prompt生成一个提示词文件然后在 codex 的配置里加上{ systemPromptFile: ./impeccable-prompt.txt }这样每次用 codex cli 生成代码时都会自动带上设计约束。我实测下来集成后的生成质量比不集成时提升明显尤其是间距和颜色的一致性。注意codex cli 的提示词长度有限制如果 impeccable 生成的提示词太长需要精简。我一般只保留颜色、间距、字体三个核心部分布局和组件规则让 AI 自己发挥。6.2 在 CI/CD 流程中加入设计审查如果你想让设计审查自动化可以在 CI/CD 流程里加入 impeccable 的审查命令。比如在 GitHub Actions 里加一个步骤- name: Design Review run: impeccable review --path ./src --fail-on-error这个命令会扫描src目录下的所有 HTML 和 CSS 文件检查设计规范遵守情况。如果发现严重问题--fail-on-error参数会让流程失败阻止合并。我建议在 PR 流程里加这个步骤但不要设成强制失败而是生成报告供参考。因为设计规范有时候需要灵活处理强制失败会导致开发者为了通过检查而写出不自然的代码。6.3 自定义设计规则的扩展方法impeccable 内置的设计规则覆盖了大多数场景但如果你有特殊需求可以自定义规则。规则文件是一个 JavaScript 模块导出一个函数接收样式对象返回审查结果。比如你想加一条规则所有按钮的圆角必须一致。规则实现如下module.exports function(styles) { const buttonRadii styles .filter(s s.selector.includes(button)) .map(s s.borderRadius); const uniqueRadii [...new Set(buttonRadii)]; if (uniqueRadii.length 1) { return { level: warning, message: 按钮圆角不一致${uniqueRadii.join(, )} }; } return null; };把规则文件放到impeccable.rules目录下impeccable 会自动加载。这个扩展机制让工具能适应不同团队的规范而不是强制所有人用同一套标准。6.4 多项目配置的复用策略如果你同时维护多个项目每个项目都想用 impeccable但设计规范略有不同可以创建一个基础配置然后各项目继承并覆盖。基础配置放在全局目录比如~/.impeccable/base.json。项目配置里加上extends字段{ extends: ~/.impeccable/base.json, colorPalette: { primary: #8b5cf6 } }这样项目配置只需要写差异部分公共部分自动继承。我管理三个前端项目用这种方式把配置维护成本降到了最低。改基础配置里的间距基准值三个项目同时生效。7. 个人实操体会与几个容易忽略的细节用了几个月 impeccable有几个体会比较深。第一设计约束不是越严越好。我一开始把间距刻度设得很细4px 到 64px 之间塞了十几个值结果 AI 生成代码时反而不知道该选哪个经常出现同一页面里相邻区块用了不同间距的情况。后来精简到八个刻度生成质量反而提升了。约束的目的是减少决策成本不是增加决策复杂度。第二颜色系统的色阶数量要控制。我试过生成 11 个色阶结果 AI 在选颜色时经常在相邻色阶之间犹豫生成的按钮悬停态和默认态差异太小用户根本看不出来。后来改成 7 个色阶相邻色阶的明度差拉大视觉效果反而更清晰。第三browser extension 的设计审查功能最好在开发阶段用不要等到代码写完再审查。我现在的习惯是每写完一个组件就点一下 extension 图标看看有没有明显问题。这样修改成本最低等到整个页面写完再审查改起来就麻烦了。第四CLI 生成代码后一定要人工过一遍。AI 生成的结构有时候会有冗余的 div 嵌套或者用了不合适的语义标签。impeccable 管的是视觉规范管不了代码语义。我一般会花几分钟清理一下 HTML 结构把该用section的地方从div改过来该用button的地方从a改过来。第五配置文件要纳入版本控制。impeccable.config.json是项目设计规范的核心应该和代码一起提交到 Git。这样团队里每个人生成的代码都遵循同一套规范不会出现张三生成的页面间距是 4px 倍数、李四生成的是 5px 倍数的情况。最后分享一个小技巧如果你想让 AI 生成特定风格的页面可以在自然语言描述里加上风格关键词比如“极简风格”“科技感”“温暖柔和”。impeccable 会把这些关键词转化成对应的设计变量调整比如“极简风格”会减少阴影和圆角“科技感”会加深色背景和高对比度配色。这个功能在快速出原型时特别有用不用手动调配置就能切换整体风格。
