1. 从impeccable说起一个被低估的前端设计关键词第一次看到impeccable这个词被拿来命名一个前端设计相关的项目我的反应是——这名字起得挺狂。无可挑剔口气不小。但仔细琢磨一下这个词精准地戳中了当下前端开发的一个核心痛点AI coding agents 能帮你写逻辑、写接口、写测试但写出来的界面往往能用但不好看。这就是impeccable这个项目要解决的问题。它不是一个框架不是一个组件库而是一套面向 AI coding agents 的前端设计约束系统。简单说它做的事情是让 AI 在生成前端代码时遵循一套经过精心设计的视觉规范从而产出无可挑剔的界面。你可能会问这跟直接用 Tailwind、用 shadcn/ui 有什么区别区别在于那些工具是给人用的而 impeccable 是给 AI 用的。它的核心交付物包括一套 CLI 工具、一个浏览器扩展以及一套嵌入到 AI agent 工作流中的设计规则集。你可以在终端里通过 CLI 快速初始化项目、校验设计规范的合规性也可以在浏览器里通过扩展实时预览 AI 生成的界面效果甚至直接把设计反馈回传给 agent。适合谁来关注这个项目三类人一是正在用 AI coding agents比如各种 CLI 形态的编码助手做前端开发的工程师二是对前端设计有要求但不想手动调 CSS 的全栈开发者三是想把自己团队的设计规范喂给 AI 的技术负责人。不管你是哪种impeccable 的思路都值得了解——它代表了一种新的前端工程范式设计规范不再只是给人看的文档而是可以直接被 AI 消费和执行的代码级约束。2. 核心设计思路拆解为什么是约束而不是生成2.1 AI 写前端的根本问题不在能不能写而在写得对不对我用过不少 AI coding agents 来生成前端页面踩过的坑基本可以归为三类。第一类是间距混乱AI 生成的组件padding 一会儿是 12px一会儿是 16px一会儿又变成 1rem完全没有节奏感。第二类是颜色失控主色、辅助色、语义色混着用hover 状态和 active 状态的颜色差异微乎其微用户根本感知不到反馈。第三类是层级缺失标题和正文的字号差距不够卡片的阴影和背景对比度太低整个页面看起来平得像一张纸。这些问题的根源不是 AI 不够聪明而是AI 没有被赋予一套明确的、可执行的视觉约束。你给它的 prompt 里写做一个好看的登录页它只能根据训练数据里的平均审美来猜。但如果你告诉它间距只能用 4px 的倍数主色只能从这三个色值里选标题和正文的字号比不得低于 1.5它就能稳定地产出符合预期的结果。impeccable 的核心设计思路就是围绕这个洞察展开的与其让 AI 自由发挥不如给它一套精心设计的约束框架。2.2 三层架构CLI 浏览器扩展 Agent 规则集impeccable 的架构可以拆成三层来理解。最底层是设计规则集这是一组用结构化格式通常是 JSON 或 YAML定义的设计 token 和约束条件。它规定了间距的粒度、颜色的取值范围、字号的阶梯、圆角的档位、阴影的层级等等。这层是整个系统的宪法所有其他层都围绕它运转。中间层是CLI 工具。它的作用是把设计规则集注入到你的项目里并且在开发过程中提供校验能力。比如你可以在项目根目录跑一条命令它会扫描你的 CSS 文件或者组件代码检查是否有违反设计规范的地方然后给出具体的修改建议。这层的价值在于把设计规范的执行从靠人自觉变成靠工具强制。最上层是浏览器扩展。它做的事情更直观在你本地开发的时候实时在浏览器里标注出哪些元素的样式偏离了设计规范。比如某个按钮的 padding 不在允许的档位里扩展会直接在那个元素上画一个高亮框旁边显示期望值16px实际值14px。这层的价值在于把抽象的规范变成可视化的反馈大大降低了理解和修正的成本。这三层配合起来形成了一个闭环规则集定义标准CLI 在代码层面校验浏览器扩展在视觉层面校验而 AI agent 在整个过程中根据这些反馈不断调整自己的输出。2.3 为什么不做成一键生成完美 UI的工具这里有一个关键的设计取舍值得说清楚。impeccable 完全有能力做成一个你描述需求它直接生成完美页面的工具但它没有这么做。为什么因为前端设计的本质是权衡而权衡需要上下文。一个电商详情页和一个 SaaS 仪表盘对信息密度的要求完全不同一个面向年轻人的社交产品和一个面向企业的管理后台对色彩饱和度的容忍度也天差地别。如果 impeccable 试图用一个万能模板来覆盖所有场景结果一定是每个场景都做得不够好。所以它选择了另一条路提供约束框架让 AI 在框架内根据具体场景做决策。这就像给一个厨师一套精选的食材和调料而不是直接给他一份做好的菜。厨师可以根据客人的口味、当天的食材状态、甚至天气来调整做法但无论如何调整用的都是那套经过筛选的原料。这种约束下的自由才是 AI 前端设计的正确打开方式。3. 核心细节解析设计规则集到底长什么样3.1 间距系统4px 基准网格不是随便定的impeccable 默认的间距系统基于4px 基准网格。这个数字不是拍脑袋来的。在 1x 屏幕密度下4px 是一个足够小的粒度可以表达出细微的间距差异同时它又足够大不会因为过于精细而导致样式表膨胀。更重要的是4px 的倍数4、8、12、16、24、32、48、64在视觉上形成了自然的节奏感人眼能感知到这些间距之间的比例关系。在实际配置中间距 token 通常这样定义{ spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, 2xl: 48px, 3xl: 64px } }注意这里用的是语义化命名而不是直接的数字。为什么因为当 AI 看到spacing.md的时候它能理解这是一个中等间距适合用在卡片内部、表单元素之间而看到16px的时候它只知道这是一个数值不知道什么时候该用。语义化命名给了 AI 更多的上下文信息让它能做出更合理的决策。注意如果你团队已经有自己的间距体系不要直接照搬 impeccable 的默认值。先把你们现有的间距值整理出来看看是否能归纳到一个基准网格上。如果不能说明你们的间距系统本身就有问题正好借这个机会统一一下。3.2 颜色系统语义层比色值层更重要impeccable 的颜色系统分两层原始色板层和语义层。原始色板层定义了一组具体的色值比如blue-500: #3B82F6、gray-100: #F3F4F6。语义层则定义了这些色值在不同场景下的用途比如color-primary: blue-500、color-background-subtle: gray-100。这种分层的好处是当你想换主题色的时候只需要改语义层的映射关系不需要去每个组件里替换色值。对于 AI 来说它只需要知道这个按钮应该用color-primary而不需要关心color-primary具体是什么颜色。这大大降低了 AI 做出错误颜色决策的概率。在实际项目中语义层的定义通常包括以下几类语义 token用途默认映射color-primary主操作按钮、链接、选中状态blue-600color-primary-hover主操作按钮的悬停状态blue-700color-danger危险操作、错误提示red-600color-success成功提示、完成状态green-600color-warning警告提示、需要注意的状态amber-500color-text-primary主要文字内容gray-900color-text-secondary次要文字、辅助说明gray-500color-background页面背景whitecolor-background-subtle卡片背景、代码块背景gray-50color-border边框、分割线gray-200这张表看起来简单但它是整个颜色系统的核心。AI 在生成代码时只要按照这张表来选择 token就不会出现这个按钮用了蓝色那个按钮用了紫色的混乱情况。3.3 字号阶梯1.25 倍比例背后的视觉逻辑impeccable 默认的字号阶梯采用1.25 倍比例也叫 Major Third。基础字号是 16px那么各级字号分别是16、20、25、31、39、49。实际使用时会取整到常用值16、20、24、32、40、48。为什么是 1.25 倍而不是 1.5 倍或者 1.2 倍1.5 倍的比例太激进相邻两级之间的差距过大会导致页面上的文字层级过于分明看起来跳跃感太强。1.2 倍的比例又太保守相邻两级之间的差距不够明显用户很难一眼分辨出哪个是标题哪个是正文。1.25 倍是一个经过大量实践验证的甜点区既能形成清晰的层级又不会显得突兀。对于 AI 来说字号阶梯的意义在于它不需要猜某个文字应该用多大字号只需要根据内容的层级从阶梯里选一个。页面主标题用font-size-3xl32px卡片标题用font-size-lg20px正文用font-size-base16px辅助说明用font-size-sm14px。每个层级都有明确的对应关系AI 只需要做选择题不需要做填空题。3.4 圆角和阴影克制是最高级的设计impeccable 在圆角和阴影上的态度非常克制。圆角只提供三档radius-sm: 4px、radius-md: 8px、radius-lg: 16px。阴影只提供三档shadow-sm、shadow-md、shadow-lg分别对应轻微浮起、明显浮起、强烈浮起三种视觉层级。这种克制是有意为之的。我见过太多项目圆角从 2px 到 24px 有七八种不同的值阴影更是五花八门每个组件都有一套自己的阴影参数。结果就是整个页面看起来碎缺乏统一感。AI 在这种环境下生成代码只会加剧混乱——它可能会给一个按钮加上 12px 的圆角给另一个按钮加上 10px 的圆角因为它觉得差不多。实操心得圆角和阴影的档位越少AI 做出正确选择的概率越高。如果你觉得三档不够用先问问自己是不是在过度设计。大多数情况下三档足够了。4. CLI 工具实操从初始化到校验的完整流程4.1 安装与初始化一条命令搞定impeccable 的 CLI 工具安装方式很直接。如果你用的是 npm 生态全局安装即可npm install -g impeccable-cli安装完成后在你的项目根目录执行初始化命令impeccable init这条命令会做几件事在项目根目录创建一个impeccable.config.json文件里面包含默认的设计规则集在你的 CSS 入口文件里注入必要的 CSS 变量定义如果检测到你在用 Tailwind它还会自动生成对应的tailwind.config.js扩展配置。初始化完成后你会看到项目里多了一个design-tokens目录里面按类别存放了间距、颜色、字号等 token 的定义文件。这些文件是后续所有校验和生成的依据不要手动修改它们如果需要调整规范应该通过impeccable config命令来修改。4.2 校验命令找出所有偏离规范的地方初始化完成后你可以随时运行校验命令impeccable lint这条命令会扫描你项目里所有的 CSS、SCSS、Less 文件以及组件文件里的内联样式检查是否有违反设计规范的地方。输出结果类似这样src/components/Button.css 12:5 warning padding value 14px is not in spacing scale [impeccable/spacing] 18:3 warning color #3B82F6 should use token color-primary [impeccable/color] 24:1 error border-radius 10px is not in radius scale [impeccable/radius] 3 problems (1 error, 2 warnings)每条问题都标注了文件路径、行号、严重程度、问题描述和对应的规则名称。warning级别的可以暂时忽略但error级别的必须修复否则在 CI 流程中会阻断构建。如果你只想检查某个特定目录可以加上路径参数impeccable lint src/components/如果你想自动修复那些可以自动修复的问题比如把#3B82F6替换成var(--color-primary)可以加上--fix参数impeccable lint --fix注意--fix只会修复那些语义明确的问题比如色值替换。对于间距和圆角这类需要判断意图的问题它不会自动修改只会给出警告。这是为了避免自动修复引入意料之外的视觉变化。4.3 与 AI Agent 的集成让 agent 自己检查自己的输出这是 impeccable 最有价值的部分。它提供了一个专门给 AI agent 调用的命令impeccable check --formatjson这条命令会输出结构化的 JSON 结果包含所有违规项的位置、类型和建议的修复值。你可以在 AI agent 的工作流里配置一个生成后检查的步骤agent 生成完代码后自动运行这条命令如果发现有违规项就把 JSON 结果回传给 agent让它根据建议重新生成。在实际配置中你可以在 agent 的 prompt 里加入这样一段指令在生成任何前端代码后必须运行 impeccable check --formatjson 命令。 如果输出结果中包含 error 级别的违规项根据返回的 suggestedFix 字段修正代码 然后重新运行检查直到没有 error 级别的违规项为止。这段指令看起来简单但它把 impeccable 从一个事后检查工具变成了实时约束系统。AI agent 不再是生成完就完事而是会主动检查自己的输出是否符合规范不符合就改直到符合为止。4.4 自定义规则把你的团队规范写进去impeccable 的默认规则集是一个起点不是终点。每个团队都有自己的设计偏好你可以通过修改impeccable.config.json来定制规则。比如你们团队规定所有卡片的圆角必须是 12px不允许用其他值{ rules: { radius: { scale: [0, 12px, 9999px], strict: true } } }strict: true表示只允许使用 scale 里列出的值任何不在列表里的圆角值都会被视为 error。这种严格模式适合那些设计规范已经非常成熟的团队可以强制 AI 和开发者都遵守统一的标准。如果你还在探索阶段可以把strict设为false这样不在 scale 里的值只会被标记为 warning不会阻断构建。等规范稳定了再切换到严格模式。5. 浏览器扩展所见即所得的规范校验5.1 安装与启用开发者工具里的新面板impeccable 的浏览器扩展安装后会在 Chrome DevTools 里增加一个名为 Impeccable 的面板。打开你的本地开发页面按 F12 打开 DevTools切换到 Impeccable 面板你会看到一个类似审计工具的界面。面板顶部有一个开始检测按钮点击后扩展会扫描当前页面上所有可见元素的样式然后按类别列出所有偏离规范的地方。检测结果分为三个视图按元素查看、按规则查看、按严重程度查看。你可以根据自己的习惯切换。5.2 实时标注页面上直接画框这是浏览器扩展最直观的功能。当你开启实时标注模式后页面上所有违反规范的元素都会被画上一个彩色边框。红色边框表示 error 级别的问题黄色边框表示 warning 级别的问题。鼠标悬停在边框上会弹出一个提示框显示具体的问题描述和建议的修复值。比如你有一个按钮的 padding 是 14px而规范里只允许 12px 或 16px扩展会在这个按钮上画一个黄色边框提示框里显示padding: 14px 不在间距规范内建议改为 12px 或 16px。这种可视化的反馈方式比在控制台里看一堆文字输出要高效得多。特别是当你需要快速定位问题时直接在页面上扫一眼就能找到所有违规元素。5.3 与 CLI 的联动浏览器里发现问题终端里修复浏览器扩展和 CLI 工具之间有一个联动机制。当你在浏览器里发现某个元素有问题时可以点击提示框里的复制修复命令按钮扩展会把对应的修复命令复制到剪贴板。你切换到终端粘贴命令CLI 会自动定位到对应的文件和行号并给出修复建议。这个联动看起来只是省了几次复制粘贴的操作但在实际开发中它大大缩短了发现问题→定位问题→修复问题的循环。特别是当页面上有几十个违规元素时你可以逐个点击、逐个修复不需要手动去代码里搜索。实操心得我通常会在开发过程中一直开着实时标注模式这样每写一个组件就能立刻看到它是否符合规范。等到提交代码前再跑一次impeccable lint做最终检查。这种实时最终的双重校验基本可以保证不会把违规代码提交到仓库。6. 常见问题与排查技巧实录6.1 为什么 CLI 报的错和浏览器扩展报的不一样这是最常见的问题。原因通常是 CLI 扫描的是源代码而浏览器扩展扫描的是渲染后的样式。有些样式是通过 CSS-in-JS 动态生成的CLI 可能无法解析有些样式是通过 JavaScript 在运行时计算的浏览器扩展能看到但 CLI 看不到。解决方法是以 CLI 的结果为准来修复代码以浏览器扩展的结果为准来验证效果。如果 CLI 没报错但浏览器扩展报了说明问题出在运行时逻辑上需要检查你的 JavaScript 代码里是否有硬编码的样式值。6.2 第三方组件的样式被误报怎么办如果你用了第三方 UI 库比如 Ant Design、Element Plus它们的组件样式很可能不符合 impeccable 的规范导致大量误报。解决方法是在配置文件里把第三方组件的样式路径加入忽略列表{ ignore: [ node_modules/**, src/styles/vendor/** ] }如果你只想忽略特定的规则可以在 ignore 里指定规则名称{ ignore: [ { path: src/components/ThirdParty/**, rules: [impeccable/spacing, impeccable/radius] } ] }6.3 AI agent 不遵守规范怎么办有时候你配置好了所有规则但 AI agent 生成代码时还是我行我素。这通常是因为 agent 的 prompt 里没有明确引用 impeccable 的规则。你需要在 prompt 里显式地告诉 agent本项目使用 impeccable 设计规范。所有前端代码必须通过 impeccable check 校验。 在生成代码前先阅读 design-tokens/ 目录下的所有 token 定义文件。 生成代码后必须运行 impeccable check --formatjson 并修复所有 error 级别的问题。另外确保你的 agent 有权限读取design-tokens/目录和运行 CLI 命令。有些 agent 默认只能读写特定目录需要手动配置权限。6.4 规范太严格导致开发效率下降这是一个需要平衡的问题。我的建议是分阶段推进第一阶段只启用颜色和字号的校验这两个对视觉影响最大且最容易统一第二阶段加入间距和圆角第三阶段再加入阴影和其他细节。每个阶段间隔一到两周让团队和 AI 都有时间适应。另外对于正在快速迭代的项目可以把strict设为false让违规项只产生 warning 而不阻断构建。等到项目进入稳定期再切换到严格模式。6.5 常见问题速查表问题现象可能原因解决方法CLI 报错但浏览器正常源代码里有硬编码值但被运行时覆盖检查 JS 里的样式逻辑移除硬编码浏览器报错但 CLI 正常运行时动态生成的样式检查 CSS-in-JS 代码改用 token第三方组件大量误报第三方样式不符合规范在 ignore 列表里排除AI agent 不遵守规范prompt 里没有引用规则在 prompt 里显式引用并配置权限校验速度太慢扫描了 node_modules在 ignore 里排除 node_modules修复后仍然报错缓存未清除运行impeccable lint --clear-cache7. 我对这套工具链的实际体会用了几个月 impeccable 之后最大的感受是它改变了我对设计规范这件事的认知。以前我觉得设计规范就是一份 Figma 文档或者一个 Storybook 页面是给人看的参考。但 impeccable 让我意识到规范应该是可执行的代码是能被工具校验、被 AI 消费的约束条件。当然它也不是银弹。如果你的项目本身就没有明确的设计规范impeccable 帮不了你——它只能执行规范不能替你制定规范。如果你的团队对设计的要求是差不多就行那这套工具可能会显得过于繁琐。但如果你和我一样受够了 AI 生成的那些能用但不好看的界面想找到一个系统性的解决方案那 impeccable 的思路值得你花时间研究。最后分享一个我在实际配置中的小技巧把impeccable.config.json纳入版本控制并且在 PR 模板里加一条检查项是否通过了 impeccable lint。这样每次代码审查时reviewer 不需要手动检查样式规范CI 会自动跑校验不通过就阻断合并。坚持一段时间后团队里所有人包括 AI agent都会形成肌肉记忆生成符合规范的代码变成了一种默认行为而不是需要刻意注意的事情。