1. 项目缘起一个叫 impeccable 的前端设计工具到底想解决什么问题第一次看到impeccable这个词是在几个 AI coding agent 的讨论串里。它本身是个形容词意思是“无可挑剔的、完美的”但在这个语境下它指向的是一类很具体的东西让 AI 写出来的前端界面从“能跑”变成“能看”。我自己做前端断断续续有七八年最近一年大量在用各种 AI coding agent 辅助开发。说实话模型写业务逻辑、写工具函数、写数据处理已经相当靠谱了。但一到 UI 层面问题就集中爆发间距忽大忽小、颜色搭配像上世纪的模板、圆角和阴影用得毫无章法、响应式断点全靠猜。你让它改它改一处崩一处最后你只能自己上手调 CSS。impeccable这类工具切入的正是这个痛点。它不是一个框架也不是一个组件库而更像是一层设计约束与校验层——通过 CLI 或者浏览器扩展的形式把一套“看起来专业”的设计规则注入到 AI coding agent 的工作流里。你写 prompt 的时候带上它或者让 agent 在生成代码后过一遍它的检查输出的界面质量会有肉眼可见的提升。这篇文章我会把impeccable相关的核心概念、CLI 工具的安装与使用、和主流 AI coding agent比如 codex cli 这一类命令行工具的配合方式、以及我自己踩过的坑完整地梳理一遍。适合两类人看一是已经在用 AI 写前端、但被 UI 质量折磨的开发者二是刚接触 CLI 类 AI 工具、想搞清楚这套工作流怎么搭起来的新手。不需要你有多深的 CSS 功底但至少要能看懂 HTML 结构和基本的命令行操作。2. 核心概念拆解impeccable 到底管的是什么2.1 它不是什么先排除三个常见误解很多人第一次听到impeccable会下意识把它归类成下面三种东西之一我先把这个误区清掉。它不是 UI 组件库。你装完它不会多出一堆 Button、Card、Modal 组件让你 import。它不提供任何可视组件也不绑定任何框架。React、Vue、Svelte、甚至纯 HTML它都能作用因为它管的是“设计决策”而不是“组件实现”。它不是 CSS 框架。它不像 Tailwind 那样给你一堆 utility class也不像 Bootstrap 那样给你一套预设样式。它更像一个“设计顾问”在你生成界面的时候告诉你间距该用多少、层级该怎么分、对比度够不够。它不是代码格式化工具。Prettier 管的是缩进和换行ESLint 管的是代码规范impeccable管的是视觉规范。三者是正交的可以同时用互不冲突。理解这三点很重要因为它决定了你该怎么把它塞进现有的工作流。你不会用它替换任何东西而是把它当成一层额外的“质检”。2.2 它实际管的三件事间距、层级、一致性把impeccable的能力拆开看核心就三块。第一块是间距系统spacing system。人眼对间距极其敏感。两个元素之间差 2px普通人看不出来差 6px就会觉得“哪里怪怪的”。AI 生成代码时最大的问题就是间距随机——这次用margin: 13px下次用padding: 1.2rem完全没有节奏。impeccable的做法是强制一套基准间距通常是 4px 或 8px 的倍数所有间距必须落在这套刻度上。这样出来的界面即使配色一般也会显得“整齐”。第二块是视觉层级visual hierarchy。一个页面里什么是主标题、什么是次要信息、什么是辅助说明字号、字重、颜色深浅要有明确的梯度。AI 经常犯的错是把所有文字都设成差不多的字号导致页面“平”得像一张表格。impeccable会检查你的字号阶梯是否合理比如标题和正文的字号比是否在 1.25 到 1.5 之间颜色对比度是否达到可读标准。第三块是一致性consistency。同一个页面里所有卡片的圆角是不是一样所有按钮的高度是不是一样所有输入框的边框颜色是不是同一个这些在人工开发时靠设计系统保证但 AI 生成时经常前后不一致。impeccable通过扫描生成结果把不一致的地方标出来。提示这三块里间距系统的收益最大、见效最快。如果你时间有限优先把间距规则接进去界面观感立刻上一个台阶。2.3 为什么用 CLI 和浏览器扩展两种形态impeccable提供两种接入方式不是重复造轮子而是对应两个不同的使用场景。CLI 形态适合“生成阶段”。你在终端里跑 AI coding agentagent 生成代码文件CLI 在文件落盘后立刻扫描把设计问题以警告形式打出来。这个流程是自动化的适合批量生成、适合集成到脚本里。浏览器扩展形态适合“预览阶段”。代码已经跑起来了你在浏览器里看到实际渲染效果扩展直接在页面上叠加标注告诉你哪个元素间距不对、哪个对比度不够。这个流程是交互式的适合调试和微调。两者共享同一套规则引擎所以你在 CLI 里看到的警告和扩展里看到的标注是一致的。我个人的习惯是生成阶段用 CLI 快速过滤明显问题预览阶段用扩展做精细调整。3. 环境准备CLI 工具链的安装与配置3.1 Node 环境与包管理器选择impeccable的 CLI 是基于 Node 生态的所以第一步是把 Node 装好。这里有个很多人踩过的坑Node 版本太低会导致安装极慢甚至失败。我实测下来Node 18 LTS 是底线推荐直接上 Node 20 LTS。如果你用的是 macOS用nvm管理版本最省心# 安装 nvm如果还没装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 装 Node 20 nvm install 20 nvm use 20 node -v # 应该输出 v20.x.xWindows 用户建议用nvm-windows或者直接去 Node 官网下 LTS 安装包。别用系统自带的包管理器装 Node版本往往很旧。包管理器方面npm、pnpm、yarn都能用。但我强烈推荐pnpm原因是impeccable这类工具依赖树比较深pnpm的硬链接机制能省下大量磁盘空间安装速度也快一截。# 装 pnpm npm install -g pnpm # 验证 pnpm -v注意如果你之前用 npm 装过全局包切到 pnpm 后全局包不共享需要重新装一遍。这是正常的不是 bug。3.2 安装 impeccable CLI 的完整流程环境就绪后安装本身很简单但有几个细节决定了你后面用得顺不顺。# 全局安装 pnpm add -g impeccable-cli # 验证安装 impeccable --version如果impeccable --version报“command not found”八成是全局 bin 目录没进 PATH。pnpm的话跑一下pnpm setup然后重开终端就行。安装慢的问题我在热搜里看到有人专门问“node 安装 codex cli 很慢”这其实是同一类问题。根源通常是 npm registry 默认走海外源国内访问不稳定。解决办法是换源# 换成国内镜像源 npm config set registry https://registry.npmmirror.com # pnpm 的话 pnpm config set registry https://registry.npmmirror.com换完源再装速度能从几分钟降到十几秒。这个技巧对所有 Node 生态的 CLI 工具都通用包括 codex cli、openspec cli、minimax cli 这些。3.3 初始化配置文件别跳过这一步装完之后很多人直接就跑结果发现规则没生效。原因是impeccable需要一个配置文件来告诉它“你的项目用哪套设计基准”。在项目根目录跑impeccable init它会生成一个impeccable.config.json内容大概长这样{ spacingBase: 4, spacingScale: [0, 4, 8, 12, 16, 24, 32, 48, 64], fontScaleRatio: 1.25, contrastStandard: AA, ignore: [node_modules/**, dist/**] }几个关键参数解释一下spacingBase间距基准单位4 或 8。选 4 更灵活选 8 更规整。我一般选 4。spacingScale允许的间距值列表。生成代码时任何不在这个列表里的间距都会被警告。fontScaleRatio字号阶梯比例。1.25 是“大三度”比较温和1.333 是“纯四度”对比更强。contrastStandard对比度标准AA 是基础AAA 更严格。ignore忽略的目录别让工具去扫依赖包。提示spacingScale不要设得太密。如果你把 0 到 64 之间每个整数都列进去等于没约束。保持 8 到 10 个刻度最合适。4. 与 AI Coding Agent 的配合把 impeccable 接进生成流程4.1 为什么要在 agent 工作流里加一层校验AI coding agent 的工作模式是“你给指令它生成代码”。问题在于agent 生成代码时脑子里没有“设计系统”这个概念。它是在概率上选最可能的写法而不是在逻辑上选最合理的写法。举个我实际遇到的例子。我让 agent 生成一个登录表单它给出的 CSS 是这样的.form-group { margin-bottom: 13px; } input { padding: 9px 11px; } button { padding: 10px 18px; }单看每一行都没问题但放在一起就乱了13、9、11、10、18五个数字毫无规律。人眼扫过去会觉得“不整齐”但说不出哪里不对。impeccable的作用就是在 agent 生成后立刻扫描把这些数字标出来然后你可以让 agent 按规则重写。4.2 在 codex cli 这类工具里挂载校验钩子如果你用的是 codex cli 这类命令行 agent可以在它的配置里挂一个 post-generation hook。具体做法是在项目里加一个脚本#!/bin/bash # scripts/post-gen-check.sh impeccable check ./src --formatcompact然后在 agent 的配置里指向这个脚本。不同 agent 的配置方式不一样但思路是一样的生成完成后自动跑一次检查。impeccable check的输出格式有三种格式用途输出示例compact终端快速浏览src/Login.tsx:12 spacing 13px not in scalejson喂给其他工具{file:...,line:12,rule:spacing}html生成可视化报告输出一个可打开的 HTML 文件我平时用compact因为信息密度高一眼能扫完。如果要给团队看就生成html报告。4.3 让 agent 自己修复闭环工作流光检查不修复等于白干。真正高效的做法是让 agent 根据检查结果自动重写。这里有个技巧把 impeccable 的输出直接作为下一轮 prompt 的输入。# 第一步生成代码 codex generate 做一个登录表单 # 第二步检查 impeccable check ./src --formatjson /tmp/issues.json # 第三步把问题喂回 agent codex fix --issues /tmp/issues.json这样形成一个闭环生成 → 检查 → 修复 → 再检查。我实测下来两轮之后基本就能达到“间距整齐、层级清晰”的水平。第三轮开始收益递减可以停。注意不要让 agent 无限循环修复。设一个上限比如最多 3 轮。超过 3 轮还有问题说明是规则配置的问题不是代码的问题该去调配置了。4.4 浏览器扩展的安装与实时标注CLI 管生成阶段浏览器扩展管预览阶段。安装方式取决于你用的浏览器主流浏览器都支持从扩展商店直接装。装完之后打开你的开发页面点扩展图标它会做三件事扫描当前页面的所有元素计算间距、字号、对比度。在页面上叠加彩色标注框红色表示严重问题黄色表示建议改进。在侧边栏列出所有问题点击可以定位到具体元素。这个功能在调响应式的时候特别好用。你把窗口从桌面宽度拖到移动宽度扩展会实时更新标注告诉你哪个断点下间距崩了。5. 实操全流程从零搭一个受控的前端生成环境5.1 项目初始化与目录结构我拿一个真实的例子走一遍。假设你要做一个后台管理系统的登录页。# 建项目 mkdir admin-login cd admin-login pnpm init # 装依赖 pnpm add -D impeccable-cli vite # 初始化 impeccable impeccable init目录结构建议这样admin-login/ ├── src/ │ ├── pages/ │ │ └── Login.tsx │ └── styles/ │ └── tokens.css ├── impeccable.config.json └── package.json关键是把设计 token 单独抽出来放tokens.css这样impeccable检查的时候有明确的基准可依。5.2 定义设计 token间距与字号的计算过程这一步是很多人忽略的但它决定了后面所有检查是否有意义。设计 token 就是一套“允许使用的值”的白名单。间距 token 的计算逻辑以 4px 为基准按近似 1.5 倍递增。4, 8, 12, 16, 24, 32, 48, 64, 96为什么是这几个数因为相邻两个数的比值在 1.33 到 2 之间既能拉开层次又不会跳得太突兀。如果你用 4, 8, 12, 16, 20, 24 这种等差数列层次感会弱很多。字号 token 的计算逻辑以 16px 正文为基准按 1.25 倍递增和递减。12.8, 16, 20, 25, 31.25, 39实际用的时候取整13, 16, 20, 25, 31, 39。这套阶梯保证任意两个相邻字号之间有明显的视觉差异。把这些写进tokens.css:root { --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-5: 24px; --space-6: 32px; --space-7: 48px; --space-8: 64px; --text-xs: 13px; --text-sm: 16px; --text-md: 20px; --text-lg: 25px; --text-xl: 31px; --text-2xl: 39px; }然后在impeccable.config.json里把spacingScale和fontScale对齐这套 token。这样检查的时候任何不在 token 里的值都会被标出来。5.3 生成代码并跑第一轮检查现在让 agent 生成登录页。prompt 里明确要求用 token生成一个登录页使用 tokens.css 里定义的间距和字号变量 不要硬编码任何数值。生成完之后跑检查impeccable check ./src --formatcompact假设输出是这样的src/pages/Login.tsx:18 spacing 13px not in scale (use 12px or 16px) src/pages/Login.tsx:24 spacing 9px not in scale (use 8px) src/pages/Login.tsx:31 font 15px not in scale (use 13px or 16px) src/pages/Login.tsx:45 contrast #999 on #fff ratio 2.8 (need 4.5)四条问题两类间距/字号不在刻度上对比度不够。这就是典型的 AI 生成结果。5.4 修复与二次验证把问题喂回 agentimpeccable check ./src --formatjson issues.json codex fix --issues issues.jsonagent 会按提示把 13px 改成 12px9px 改成 8px15px 改成 16px把 #999 改成对比度达标的颜色比如 #767676。再跑一次检查impeccable check ./src --formatcompact如果输出是空的说明全部通过。这时候打开浏览器看效果你会发现界面虽然简单但“整齐”了。这种整齐感就是impeccable带来的最直接价值。提示对比度问题不要只靠工具判断。工具算的是数值但实际可读性还受字号、字重影响。大字号18px 以上的对比度要求可以放宽到 3:1。6. 常见问题与排查技巧实录6.1 安装类问题速查现象原因解决impeccable: command not found全局 bin 不在 PATH跑pnpm setup后重开终端安装卡住不动registry 访问慢换国内镜像源EBADENGINE报错Node 版本太低升级到 Node 18装完但init报错目录没有写权限检查目录权限别在系统目录跑6.2 检查结果异常的处理问题一明明用了 token还是被警告。这种情况通常是 CSS 变量没被正确解析。impeccable默认能识别var(--space-4)这种写法但如果你用了calc(var(--space-4) * 2)它可能算不出来。解决办法是在配置里加resolveCalc: true或者干脆避免在间距上用 calc。问题二警告太多看不过来。说明你的spacingScale设得太严或者项目里历史遗留的硬编码太多。建议先跑一次impeccable check --summary只看统计不看明细评估一下问题总量。如果超过 200 条先放宽规则逐步收紧。问题三浏览器扩展不显示标注。先确认页面不是file://协议打开的扩展通常只在http://localhost或真实域名下工作。其次检查扩展是否有当前页面的权限。最后如果页面用了 Shadow DOM扩展可能扫不到内部元素这是已知限制。6.3 我踩过的三个坑坑一把spacingBase设成 8结果小间距全废。8px 基准意味着最小间距是 8px。但实际设计里图标和文字之间经常需要 4px 的微调。设成 8 之后这类微调全被警告。后来我改回 4世界清净了。坑二忽略目录没配好扫了 node_modules。第一次跑检查输出刷了满屏全是依赖包里的问题。后来在ignore里加上node_modules/**和dist/**才正常。这个配置一定要在init之后就改好别等跑完才发现。坑三让 agent 无限修复越修越乱。有一次我没设上限agent 修了七轮最后把好好的布局改得面目全非。原因是它在“满足规则”和“保持原意”之间失去了平衡。后来我固定最多 3 轮第 3 轮还不过就人工介入。6.4 性能优化大项目怎么跑得快项目大了之后全量扫描会很慢。几个优化手段用--changed只扫改动过的文件。用--cache开启缓存第二次扫描快很多。把ignore配全别让工具去扫构建产物。如果只是想在提交前快速过一遍用--formatcompact --quiet只输出错误不输出警告。我实测一个 300 文件的项目全量扫描大概 8 秒开缓存后降到 1.5 秒。这个速度完全可以挂到 pre-commit hook 里。7. 扩展玩法把 impeccable 用在更多场景7.1 和 openspec cli 配合做规范驱动开发openspec cli这类工具的思路是“先写规范再生成代码”。把impeccable接进去就变成了“规范里包含设计约束生成后自动校验”。具体做法是在 spec 文件里加一段设计约束design: spacingBase: 4 fontScaleRatio: 1.25 contrastStandard: AA生成代码后impeccable按这段约束检查。这样设计和开发就在同一个规范体系里了不会出现“规范说一套、代码写一套”的情况。7.2 在 CI 里做设计质量门禁把impeccable check加到 CI 流程里任何 PR 如果引入了设计问题直接卡住不让合并。# .github/workflows/design-check.yml name: Design Check on: [pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 - run: pnpm install - run: pnpm impeccable check ./src --formatcompact这个门禁一开始会很烦因为历史代码问题多。建议先设成“只警告不阻断”等存量问题清理得差不多了再改成阻断。7.3 给团队做设计规范培训的素材impeccable生成的 HTML 报告其实是很好的培训素材。报告里每个问题都附了“当前值”和“建议值”新人看一眼就明白为什么 13px 不行、12px 行。我团队里新来的前端第一周的任务就是跑一遍报告把里面的问题分类整理。整理完他对设计系统的理解就到位了。8. 一些个人体会用impeccable这几个月最大的感受是它不提升上限但大幅提升下限。它不会让你的界面变得惊艳惊艳靠的是设计师的审美和创意工具替代不了。但它能保证你的界面不丑、不乱、不廉价。对于大量用 AI 生成代码的场景来说这个“保底”价值极高。另一个体会是规则要慢慢加不要一次到位。我一开始把规则设得很严结果警告刷屏团队怨声载道。后来改成“先松后紧”每周收紧一点大家反而接受得很好。工具是给人用的别让工具反过来绑架人。最后分享一个小技巧impeccable的配置文件可以分环境。开发环境用宽松规则快速迭代CI 环境用严格规则保证质量。在impeccable.config.json里用extends字段继承基础配置然后按环境覆盖。这样一套配置能适配整个开发流程不用来回改。
