1. 从“impeccable”说起一个前端设计增强工具的真实定位第一次看到“impeccable”这个词是在几个 AI coding agent 的讨论群里。有人甩出一句“impeccable skill 装完前端页面终于不像 AI 生成的了”底下立刻一堆人追问怎么装、支持不支持 codex cli、claude cli 能不能直接用。我当时的反应是又一个包装概念的工具但架不住反复被刷屏还是去把它拉下来跑了一遍。结论先放这儿impeccable 不是一个独立的设计软件也不是一个能自动帮你写页面的 AI它更像是一层“设计约束层”挂在你已有的 AI coding agent 工作流上专门治 AI 生成前端时那种“能跑但难看”的毛病。它通过 CLI 和浏览器扩展两种形态介入把一套经过打磨的设计规范、间距体系、配色逻辑、组件结构注入到 agent 的生成过程里让输出结果从“功能正确”往“视觉可用”靠。它解决的问题非常具体。用过 codex cli、claude cli 这类工具的人都知道你让它写一个登录页、一个仪表盘、一个卡片列表它给你的 HTML/CSS 大概率是颜色是随手挑的蓝间距是 16px 和 24px 混着来圆角一会儿 4px 一会儿 8px字体大小没有层级hover 状态基本靠猜。功能上没毛病但拿给设计师看对方会沉默三秒。impeccable 要干的就是这件事——在 agent 生成之前或之后用一套明确的规则去约束和修正这些视觉决策。适合谁来用三类人最对口。第一类是独立开发者和小团队没有专职设计师但产品又不能长得太寒碜第二类是前端工程师自己审美在线但不想每次都给 AI 擦屁股第三类是产品经理和创业者用 AI 快速做原型希望原型能直接拿去给人看而不是只给自己看。如果你只是偶尔让 AI 写个脚本、跑个数据处理那 impeccable 对你意义不大但只要你频繁用 AI 生成界面它值得花半小时研究一下。我下面会从它的设计思路、核心机制、CLI 和浏览器扩展两条实操路径、以及我踩过的坑完整拆一遍。内容基于我自己的使用记录和常见实践补充不是官方文档的复述。2. 核心设计思路拆解为什么是“约束层”而不是“生成器”2.1 一个关键判断AI 不缺生成能力缺的是决策纪律要理解 impeccable 为什么长这样得先理解 AI 生成前端的问题到底出在哪。很多人以为是“AI 不会写 CSS”其实不对。你让 claude cli 写一个 flex 布局它写得比很多工作两三年的前端还规范。真正的问题是决策不一致。同一个页面里AI 会在不同位置做出互相矛盾的视觉决策。标题用 20px副标题用 18px正文用 15px注释用 13px——看起来有层级但 20 和 18 差 2px视觉上几乎分不出来而 18 和 15 差 3px 又跳得太明显。间距也是卡片内边距 20px卡片之间 16px区块之间 32px没有一套统一的基数。颜色更典型主色是 #3B82F6按钮 hover 变成 #2563EB链接又是 #60A5FA三个蓝各说各话。这不是能力问题是没有约束。AI 每次做决策都是独立的它不知道上一个决策是什么也没有一套“必须遵守的规则”去校准。impeccable 的核心思路就是不去增强 AI 的生成能力而是给它一套决策纪律让它在做视觉选择时有据可依。这个判断很重要。市面上很多工具试图用“更好的模型”或“更多的训练数据”来解决前端美观问题但 impeccable 走的是另一条路——用规则和约束去收窄 AI 的自由度。自由度低了一致性自然就高了。2.2 约束层的三个组成部分impeccable 的约束体系我拆下来大概是三块尺度系统、语义令牌、结构模板。尺度系统解决的是“数值从哪来”。它定义了一套间距基数通常是 4px 或 8px 的倍数、一套字号阶梯比如 12/14/16/20/24/32/48、一套圆角档位4/8/12/16/full、一套阴影层级sm/md/lg/xl。AI 在生成时不能随便写padding: 17px必须从这套尺度里选。这就像给一个装修队规定了“所有瓷砖只能用这五种尺寸”出来的效果不一定惊艳但绝对不会乱。语义令牌解决的是“颜色和状态怎么表达”。它不直接给你#3B82F6而是给你primary、primary-hover、primary-active、surface、surface-raised、border-subtle、text-primary、text-secondary这样的语义名。AI 写样式时引用语义名底层色值由令牌系统统一管理。好处是换主题、调色时只改一处而且 AI 不会在同一个页面里用出三个不同的“主色”。结构模板解决的是“组件长什么样”。它预置了一批常见组件的结构规范——按钮的内边距和最小高度、输入框的边框和聚焦态、卡片的圆角和阴影组合、表格的行高和分隔线。AI 生成这些组件时模板会作为参考注入避免每次从零发明。2.3 为什么用 CLI 浏览器扩展双形态这是我觉得 impeccable 设计上比较聪明的地方。它没有只做 CLI也没有只做扩展而是两条腿走路因为这两种形态解决的是不同阶段的问题。CLI 形态介入的是生成阶段。你在 codex cli 或 claude cli 里调用 impeccable skill它会在 agent 生成代码的过程中注入约束。这时候约束是“事前”的AI 从一开始就在规则内工作出来的代码天然符合规范。适合的场景是你要从零做一个页面或一个组件希望一次成型。浏览器扩展形态介入的是审查阶段。页面已经生成出来了你在浏览器里打开扩展会实时扫描 DOM标出违反尺度系统的地方——这个 padding 不在基数上、这个字号不在阶梯里、这个颜色不在令牌中。它还能给出修正建议甚至一键应用。适合的场景是你手上已经有一堆 AI 生成的页面想批量体检和修正。两种形态共享同一套约束规则所以 CLI 生成的东西扩展能审扩展修正的结果也能反哺回代码。这个闭环是它区别于普通 lint 工具的关键。3. CLI 形态实操在 codex cli 和 claude cli 里挂载 impeccable skill3.1 安装前的环境确认在动手之前先把环境理清楚。impeccable 的 CLI 形态本质是一个 skill 包需要挂载到支持 skill 机制的 agent 上。目前主流的是 codex cli 和 claude cli 两条线安装方式略有差异。先确认你的 agent 版本。codex cli 建议用较新的版本老版本可能不支持 skill 的动态加载。在终端里跑一下版本命令确认输出正常。claude cli 同理尤其是 Mac 环境下用 qwen key 或其他第三方 key 的配置要确保 agent 本身能正常跑通一次对话再考虑挂 skill。# 确认 codex cli 可用 codex --version # 确认 claude cli 可用 claude --version如果这两条命令报错先解决 agent 本身的安装问题别急着上 impeccable。我见过有人 skill 装了半天没反应最后发现是 agent 根本没装好。3.2 安装 impeccable skill 的两种路径安装路径取决于你的 agent 生态。常见做法有两种包管理器安装和手动挂载。包管理器安装适合 codex cli 这类有插件市场的 agent。通常是一条 install 命令指定 impeccable 的包名agent 会自动下载并注册 skill。这种方式的优点是升级方便缺点是版本可能滞后。手动挂载适合 claude cli 或需要定制的情况。你需要把 impeccable 的 skill 目录克隆到 agent 的 skill 搜索路径下然后在配置文件里注册。skill 目录里一般包含一个清单文件描述 skill 的名称、触发词、能力和若干规则文件尺度系统、令牌、模板。# 手动挂载的典型结构 ~/.agent/skills/ impeccable/ manifest.json # skill 清单 tokens.json # 语义令牌 scale.json # 尺度系统 templates/ # 组件模板挂载完成后重启 agent让它重新扫描 skill 目录。这一步很多人会忘导致 skill 装了但 agent 不认。3.3 触发 impeccable skill 的正确姿势skill 装好之后怎么让它生效这里有个关键点impeccable 不是自动生效的需要显式触发。你可以在对话里用触发词唤醒它比如提到“用 impeccable 规范生成”“按设计系统来”“遵循尺度系统”之类。不同 agent 的触发机制不一样codex cli 可能识别特定的 skill 调用语法claude cli 可能靠自然语言触发词。我的习惯是在 prompt 开头就声明约束来源比如使用 impeccable skill 的设计规范生成一个用户仪表盘页面。 要求包含侧边栏导航、顶部统计卡片区、下方数据表格。 所有间距、字号、颜色必须从 impeccable 的尺度系统和令牌中选取。这样 agent 在生成前就知道要遵守哪套规则而不是生成完了再让它改。事前约束的成本远低于事后修正。注意如果你不显式触发agent 可能完全忽略 skill 的存在按自己的默认习惯生成。这不是 bug是 skill 机制的设计——它把是否启用规范的决定权留给你。3.4 生成结果的验证方法生成完之后别急着高兴要验证约束是否真的生效了。最直接的方法是看代码里的数值。打开生成的 CSS 或样式文件检查几个关键点所有padding和margin的值是否都是基数比如 4 或 8的倍数字号是否落在阶梯上12/14/16/20/24/32/48 这类颜色是否引用了语义令牌而不是硬编码色值圆角是否在档位内4/8/12/16/full如果发现padding: 18px这种不在基数上的值说明约束没完全生效可能是 skill 没触发也可能是 agent 在某个环节绕过了规则。这时候可以追问一句“检查并修正所有不符合 impeccable 尺度的数值”让它自查。我实测下来codex cli 对 skill 的遵守度比 claude cli 略高一些可能是因为 codex 的 skill 机制更结构化。claude cli 在长对话里偶尔会“忘记”约束需要中途提醒。这不是 impeccable 的问题是 agent 本身的上下文管理问题。4. 浏览器扩展形态给已有页面做设计体检4.1 扩展的安装与激活浏览器扩展形态的安装比 CLI 简单得多。通常是从扩展市场安装或者加载本地解压的扩展目录。安装后在浏览器工具栏会出现图标点击激活。激活后扩展一般有两种工作模式实时扫描和手动扫描。实时扫描会在页面加载时自动分析 DOM手动扫描需要你点一下按钮。我建议先用手动扫描因为实时扫描在复杂页面上可能拖慢浏览器。扩展激活后打开一个 AI 生成的页面点扫描。它会在页面上叠加一层标注把违反规范的元素高亮出来。标注通常分等级严重违规比如颜色完全不在令牌里、警告比如间距不在基数上、提示比如可以优化的层级关系。4.2 扩展能查出哪些问题我把扩展的检查项整理成了一张表方便对照检查维度具体检查内容常见违规示例间距padding/margin/gap 是否为基数倍数padding: 18px基数 4 时违规字号font-size 是否在阶梯内font-size: 17px颜色色值是否匹配语义令牌硬编码#3B82F6而非primary圆角border-radius 是否在档位内border-radius: 6px阴影box-shadow 是否使用预置层级自定义的复杂阴影层级标题字号是否递减、是否有跳级h1 和 h2 字号相同对比度文字与背景对比度是否达标浅灰字配白底这张表基本覆盖了 AI 生成前端最常见的视觉问题。对比度那一项尤其有用AI 经常生成对比度不足的文字肉眼看着还行但无障碍标准过不了。4.3 从扫描结果到修正的闭环扩展的价值不只是“发现问题”更在于“给出修正”。扫描后每个违规项通常会附带建议值。比如padding: 18px会建议改成16px或20px取决于上下文。你可以逐条应用也可以批量应用。批量应用要谨慎。我踩过一次坑批量把所有 18px 改成 16px结果某个卡片的视觉平衡被破坏了因为那个 18px 是刻意为之的。所以我的建议是先看建议再决定是否应用尤其是涉及布局关键位置的数值。修正完成后扩展一般支持导出修正后的样式你可以把它合并回代码。这样就完成了“生成—审查—修正—回写”的闭环。一个实用技巧把扩展的扫描结果导出成 JSON然后用脚本批量处理。对于有几十个页面的项目手动一条条改是不现实的。导出后用脚本按规则映射效率高很多。5. 尺度系统与语义令牌的落地细节5.1 尺度基数的选择4 还是 8尺度基数是整套系统的地基。常见选择是 4px 或 8px。选哪个不是拍脑袋要看你的产品密度。4px 基数适合信息密度高的产品比如后台管理系统、数据仪表盘、开发者工具。这类产品元素多、间距小4px 的粒度能做出更精细的区分。8px 基数适合信息密度低的产品比如营销页、移动端应用、内容型网站。这类产品留白多8px 的粒度足够而且数值更整齐。impeccable 默认可能给的是 4px 或 8px但你可以根据项目调整。调整后要重新生成尺度阶梯确保所有档位都是新基数的倍数。我一般会在项目启动时就定好中途改成本很高。5.2 字号阶梯的设计逻辑字号阶梯不是随便列几个数。它要满足两个条件相邻档位有可感知的差异整体覆盖从注释到标题的范围。一个常见的阶梯是12 / 14 / 16 / 20 / 24 / 32 / 48。12 用于辅助注释14 用于次要文字16 用于正文20 用于小标题24 用于中标题32 用于大标题48 用于展示型标题。相邻档位的比例大致在 1.2 到 1.5 之间视觉上能明显区分。AI 生成时最容易犯的错是“中间档位太多”。它可能生成 15px、17px、18px 这种看起来精细实际上视觉上分不出来反而显得杂乱。尺度系统的作用就是砍掉这些中间档强制 AI 在有限的档位里选。5.3 语义令牌的命名规范语义令牌的命名要遵循“用途优先色值其次”的原则。不要用blue-500、gray-100这种色值命名要用primary、surface、border-subtle这种用途命名。原因很简单色值会变用途不会。今天的主色是蓝色明天可能换成紫色但“主色”这个用途不变。用用途命名换色时只改令牌定义所有引用处自动生效。用色值命名换色时你得全局搜索替换容易漏。一套基础的语义令牌大概包括背景类background、surface、surface-raised、surface-overlay文字类text-primary、text-secondary、text-disabled、text-inverse边框类border-default、border-subtle、border-strong、border-focus状态类primary、primary-hover、primary-active、danger、success、warningAI 生成时引用这些令牌而不是硬编码色值。这样即使 AI 在多个地方生成样式颜色也是一致的。6. 常见问题与排查技巧实录6.1 skill 装了但 agent 不认这是最高频的问题。表现是你明明装了 impeccable skill也用了触发词但 agent 生成的东西还是老样子数值乱七八糟。排查顺序是这样的。先确认 skill 目录位置对不对agent 的 skill 搜索路径可能不止一个你装的地方未必是它扫的地方。再确认清单文件格式对不对JSON 格式错误会导致 skill 加载失败但 agent 不报错。然后确认 agent 版本支持 skill 机制老版本可能压根没这功能。最后确认触发词是否匹配不同 agent 的触发词识别逻辑不一样有的靠关键词有的靠特定语法。我遇到过一次是清单文件里 skill 名称写错了agent 扫到了但注册失败静默忽略。改对名称后立刻生效。6.2 约束在长对话中失效claude cli 在长对话里容易“忘记”约束生成到后面几轮就开始放飞。这不是 impeccable 的锅是 agent 的上下文窗口问题。应对方法有两个。一是缩短对话轮次每生成一个独立模块就开新对话别在一个对话里生成整个项目。二是中途重申约束在 prompt 里再提一句“继续遵循 impeccable 规范”。实测重申一次能管好几轮。6.3 扩展扫描结果误报扩展扫描偶尔会误报把一些合理的自定义值标成违规。比如某个动画的过渡时间、某个特殊组件的尺寸这些本来就不该受尺度系统约束。处理方法是给扩展加白名单。大多数扩展支持在配置里排除特定选择器或特定属性。把那些确实需要自定义的地方加进白名单扫描结果就干净了。别为了追求“零违规”把合理的自定义也改掉那是本末倒置。6.4 生成结果“规范但呆板”这是另一个极端。约束太严AI 生成的东西虽然一致但缺乏变化看起来像模板套出来的。我的经验是约束管的是基础层创意管的是表现层。尺度、令牌、结构这些基础层要严格约束但配色方案、插画风格、动效这些表现层可以放开。impeccable 的约束主要作用在基础层表现层它管得不多。如果你觉得呆板问题可能出在 prompt 里没给表现层的发挥空间而不是约束太严。6.5 常见问题速查表问题现象可能原因排查动作skill 不生效目录/清单/版本/触发词逐项确认看 agent 日志长对话失效上下文窗口溢出缩短轮次中途重申扫描误报合理自定义被误判加白名单排除结果呆板表现层无发挥空间prompt 里放开表现层数值仍混乱约束未真正注入检查生成代码的数值来源扩展拖慢浏览器实时扫描开销大改用手动扫描7. 我个人的使用体会与几个实用建议用了一段时间 impeccable最大的感受是它把“审美”这个模糊的东西拆成了可执行、可检查、可修正的规则。以前让 AI 生成前端好不好看全凭运气现在至少有个底线出来的东西不会太离谱。几个实用建议。第一项目启动时就定好尺度系统和令牌别等生成了一堆页面再回头统一成本高十倍。第二CLI 和扩展配合用CLI 管生成扩展管审查两条腿走路比单用一条稳。第三别追求零违规约束是服务产品的不是产品服务约束该自定义的地方就自定义。第四把扫描结果导出成数据用脚本批量处理比手动改快得多。还有一个我最近在试的玩法把 impeccable 的令牌系统导出成一份设计规范文档直接给团队里的设计师和前端看。这样人和 AI 用的是同一套规则协作时少很多扯皮。这个方向后续还可以扩展比如把令牌同步到 Figma 变量、同步到 CSS 变量、同步到 Tailwind 配置让规范真正落到工程的每个环节。踩过的坑也不少。最亏的一次是没确认 agent 版本就装 skill折腾了一小时才发现是版本不支持。所以再强调一遍先确认 agent 本身跑得通再上 skill。这个顺序反了后面全是无用功。
impeccable 设计约束层：用 CLI 与浏览器扩展规范 AI 生成前端
1. 从“impeccable”说起一个前端设计增强工具的真实定位第一次看到“impeccable”这个词是在几个 AI coding agent 的讨论群里。有人甩出一句“impeccable skill 装完前端页面终于不像 AI 生成的了”底下立刻一堆人追问怎么装、支持不支持 codex cli、claude cli 能不能直接用。我当时的反应是又一个包装概念的工具但架不住反复被刷屏还是去把它拉下来跑了一遍。结论先放这儿impeccable 不是一个独立的设计软件也不是一个能自动帮你写页面的 AI它更像是一层“设计约束层”挂在你已有的 AI coding agent 工作流上专门治 AI 生成前端时那种“能跑但难看”的毛病。它通过 CLI 和浏览器扩展两种形态介入把一套经过打磨的设计规范、间距体系、配色逻辑、组件结构注入到 agent 的生成过程里让输出结果从“功能正确”往“视觉可用”靠。它解决的问题非常具体。用过 codex cli、claude cli 这类工具的人都知道你让它写一个登录页、一个仪表盘、一个卡片列表它给你的 HTML/CSS 大概率是颜色是随手挑的蓝间距是 16px 和 24px 混着来圆角一会儿 4px 一会儿 8px字体大小没有层级hover 状态基本靠猜。功能上没毛病但拿给设计师看对方会沉默三秒。impeccable 要干的就是这件事——在 agent 生成之前或之后用一套明确的规则去约束和修正这些视觉决策。适合谁来用三类人最对口。第一类是独立开发者和小团队没有专职设计师但产品又不能长得太寒碜第二类是前端工程师自己审美在线但不想每次都给 AI 擦屁股第三类是产品经理和创业者用 AI 快速做原型希望原型能直接拿去给人看而不是只给自己看。如果你只是偶尔让 AI 写个脚本、跑个数据处理那 impeccable 对你意义不大但只要你频繁用 AI 生成界面它值得花半小时研究一下。我下面会从它的设计思路、核心机制、CLI 和浏览器扩展两条实操路径、以及我踩过的坑完整拆一遍。内容基于我自己的使用记录和常见实践补充不是官方文档的复述。2. 核心设计思路拆解为什么是“约束层”而不是“生成器”2.1 一个关键判断AI 不缺生成能力缺的是决策纪律要理解 impeccable 为什么长这样得先理解 AI 生成前端的问题到底出在哪。很多人以为是“AI 不会写 CSS”其实不对。你让 claude cli 写一个 flex 布局它写得比很多工作两三年的前端还规范。真正的问题是决策不一致。同一个页面里AI 会在不同位置做出互相矛盾的视觉决策。标题用 20px副标题用 18px正文用 15px注释用 13px——看起来有层级但 20 和 18 差 2px视觉上几乎分不出来而 18 和 15 差 3px 又跳得太明显。间距也是卡片内边距 20px卡片之间 16px区块之间 32px没有一套统一的基数。颜色更典型主色是 #3B82F6按钮 hover 变成 #2563EB链接又是 #60A5FA三个蓝各说各话。这不是能力问题是没有约束。AI 每次做决策都是独立的它不知道上一个决策是什么也没有一套“必须遵守的规则”去校准。impeccable 的核心思路就是不去增强 AI 的生成能力而是给它一套决策纪律让它在做视觉选择时有据可依。这个判断很重要。市面上很多工具试图用“更好的模型”或“更多的训练数据”来解决前端美观问题但 impeccable 走的是另一条路——用规则和约束去收窄 AI 的自由度。自由度低了一致性自然就高了。2.2 约束层的三个组成部分impeccable 的约束体系我拆下来大概是三块尺度系统、语义令牌、结构模板。尺度系统解决的是“数值从哪来”。它定义了一套间距基数通常是 4px 或 8px 的倍数、一套字号阶梯比如 12/14/16/20/24/32/48、一套圆角档位4/8/12/16/full、一套阴影层级sm/md/lg/xl。AI 在生成时不能随便写padding: 17px必须从这套尺度里选。这就像给一个装修队规定了“所有瓷砖只能用这五种尺寸”出来的效果不一定惊艳但绝对不会乱。语义令牌解决的是“颜色和状态怎么表达”。它不直接给你#3B82F6而是给你primary、primary-hover、primary-active、surface、surface-raised、border-subtle、text-primary、text-secondary这样的语义名。AI 写样式时引用语义名底层色值由令牌系统统一管理。好处是换主题、调色时只改一处而且 AI 不会在同一个页面里用出三个不同的“主色”。结构模板解决的是“组件长什么样”。它预置了一批常见组件的结构规范——按钮的内边距和最小高度、输入框的边框和聚焦态、卡片的圆角和阴影组合、表格的行高和分隔线。AI 生成这些组件时模板会作为参考注入避免每次从零发明。2.3 为什么用 CLI 浏览器扩展双形态这是我觉得 impeccable 设计上比较聪明的地方。它没有只做 CLI也没有只做扩展而是两条腿走路因为这两种形态解决的是不同阶段的问题。CLI 形态介入的是生成阶段。你在 codex cli 或 claude cli 里调用 impeccable skill它会在 agent 生成代码的过程中注入约束。这时候约束是“事前”的AI 从一开始就在规则内工作出来的代码天然符合规范。适合的场景是你要从零做一个页面或一个组件希望一次成型。浏览器扩展形态介入的是审查阶段。页面已经生成出来了你在浏览器里打开扩展会实时扫描 DOM标出违反尺度系统的地方——这个 padding 不在基数上、这个字号不在阶梯里、这个颜色不在令牌中。它还能给出修正建议甚至一键应用。适合的场景是你手上已经有一堆 AI 生成的页面想批量体检和修正。两种形态共享同一套约束规则所以 CLI 生成的东西扩展能审扩展修正的结果也能反哺回代码。这个闭环是它区别于普通 lint 工具的关键。3. CLI 形态实操在 codex cli 和 claude cli 里挂载 impeccable skill3.1 安装前的环境确认在动手之前先把环境理清楚。impeccable 的 CLI 形态本质是一个 skill 包需要挂载到支持 skill 机制的 agent 上。目前主流的是 codex cli 和 claude cli 两条线安装方式略有差异。先确认你的 agent 版本。codex cli 建议用较新的版本老版本可能不支持 skill 的动态加载。在终端里跑一下版本命令确认输出正常。claude cli 同理尤其是 Mac 环境下用 qwen key 或其他第三方 key 的配置要确保 agent 本身能正常跑通一次对话再考虑挂 skill。# 确认 codex cli 可用 codex --version # 确认 claude cli 可用 claude --version如果这两条命令报错先解决 agent 本身的安装问题别急着上 impeccable。我见过有人 skill 装了半天没反应最后发现是 agent 根本没装好。3.2 安装 impeccable skill 的两种路径安装路径取决于你的 agent 生态。常见做法有两种包管理器安装和手动挂载。包管理器安装适合 codex cli 这类有插件市场的 agent。通常是一条 install 命令指定 impeccable 的包名agent 会自动下载并注册 skill。这种方式的优点是升级方便缺点是版本可能滞后。手动挂载适合 claude cli 或需要定制的情况。你需要把 impeccable 的 skill 目录克隆到 agent 的 skill 搜索路径下然后在配置文件里注册。skill 目录里一般包含一个清单文件描述 skill 的名称、触发词、能力和若干规则文件尺度系统、令牌、模板。# 手动挂载的典型结构 ~/.agent/skills/ impeccable/ manifest.json # skill 清单 tokens.json # 语义令牌 scale.json # 尺度系统 templates/ # 组件模板挂载完成后重启 agent让它重新扫描 skill 目录。这一步很多人会忘导致 skill 装了但 agent 不认。3.3 触发 impeccable skill 的正确姿势skill 装好之后怎么让它生效这里有个关键点impeccable 不是自动生效的需要显式触发。你可以在对话里用触发词唤醒它比如提到“用 impeccable 规范生成”“按设计系统来”“遵循尺度系统”之类。不同 agent 的触发机制不一样codex cli 可能识别特定的 skill 调用语法claude cli 可能靠自然语言触发词。我的习惯是在 prompt 开头就声明约束来源比如使用 impeccable skill 的设计规范生成一个用户仪表盘页面。 要求包含侧边栏导航、顶部统计卡片区、下方数据表格。 所有间距、字号、颜色必须从 impeccable 的尺度系统和令牌中选取。这样 agent 在生成前就知道要遵守哪套规则而不是生成完了再让它改。事前约束的成本远低于事后修正。注意如果你不显式触发agent 可能完全忽略 skill 的存在按自己的默认习惯生成。这不是 bug是 skill 机制的设计——它把是否启用规范的决定权留给你。3.4 生成结果的验证方法生成完之后别急着高兴要验证约束是否真的生效了。最直接的方法是看代码里的数值。打开生成的 CSS 或样式文件检查几个关键点所有padding和margin的值是否都是基数比如 4 或 8的倍数字号是否落在阶梯上12/14/16/20/24/32/48 这类颜色是否引用了语义令牌而不是硬编码色值圆角是否在档位内4/8/12/16/full如果发现padding: 18px这种不在基数上的值说明约束没完全生效可能是 skill 没触发也可能是 agent 在某个环节绕过了规则。这时候可以追问一句“检查并修正所有不符合 impeccable 尺度的数值”让它自查。我实测下来codex cli 对 skill 的遵守度比 claude cli 略高一些可能是因为 codex 的 skill 机制更结构化。claude cli 在长对话里偶尔会“忘记”约束需要中途提醒。这不是 impeccable 的问题是 agent 本身的上下文管理问题。4. 浏览器扩展形态给已有页面做设计体检4.1 扩展的安装与激活浏览器扩展形态的安装比 CLI 简单得多。通常是从扩展市场安装或者加载本地解压的扩展目录。安装后在浏览器工具栏会出现图标点击激活。激活后扩展一般有两种工作模式实时扫描和手动扫描。实时扫描会在页面加载时自动分析 DOM手动扫描需要你点一下按钮。我建议先用手动扫描因为实时扫描在复杂页面上可能拖慢浏览器。扩展激活后打开一个 AI 生成的页面点扫描。它会在页面上叠加一层标注把违反规范的元素高亮出来。标注通常分等级严重违规比如颜色完全不在令牌里、警告比如间距不在基数上、提示比如可以优化的层级关系。4.2 扩展能查出哪些问题我把扩展的检查项整理成了一张表方便对照检查维度具体检查内容常见违规示例间距padding/margin/gap 是否为基数倍数padding: 18px基数 4 时违规字号font-size 是否在阶梯内font-size: 17px颜色色值是否匹配语义令牌硬编码#3B82F6而非primary圆角border-radius 是否在档位内border-radius: 6px阴影box-shadow 是否使用预置层级自定义的复杂阴影层级标题字号是否递减、是否有跳级h1 和 h2 字号相同对比度文字与背景对比度是否达标浅灰字配白底这张表基本覆盖了 AI 生成前端最常见的视觉问题。对比度那一项尤其有用AI 经常生成对比度不足的文字肉眼看着还行但无障碍标准过不了。4.3 从扫描结果到修正的闭环扩展的价值不只是“发现问题”更在于“给出修正”。扫描后每个违规项通常会附带建议值。比如padding: 18px会建议改成16px或20px取决于上下文。你可以逐条应用也可以批量应用。批量应用要谨慎。我踩过一次坑批量把所有 18px 改成 16px结果某个卡片的视觉平衡被破坏了因为那个 18px 是刻意为之的。所以我的建议是先看建议再决定是否应用尤其是涉及布局关键位置的数值。修正完成后扩展一般支持导出修正后的样式你可以把它合并回代码。这样就完成了“生成—审查—修正—回写”的闭环。一个实用技巧把扩展的扫描结果导出成 JSON然后用脚本批量处理。对于有几十个页面的项目手动一条条改是不现实的。导出后用脚本按规则映射效率高很多。5. 尺度系统与语义令牌的落地细节5.1 尺度基数的选择4 还是 8尺度基数是整套系统的地基。常见选择是 4px 或 8px。选哪个不是拍脑袋要看你的产品密度。4px 基数适合信息密度高的产品比如后台管理系统、数据仪表盘、开发者工具。这类产品元素多、间距小4px 的粒度能做出更精细的区分。8px 基数适合信息密度低的产品比如营销页、移动端应用、内容型网站。这类产品留白多8px 的粒度足够而且数值更整齐。impeccable 默认可能给的是 4px 或 8px但你可以根据项目调整。调整后要重新生成尺度阶梯确保所有档位都是新基数的倍数。我一般会在项目启动时就定好中途改成本很高。5.2 字号阶梯的设计逻辑字号阶梯不是随便列几个数。它要满足两个条件相邻档位有可感知的差异整体覆盖从注释到标题的范围。一个常见的阶梯是12 / 14 / 16 / 20 / 24 / 32 / 48。12 用于辅助注释14 用于次要文字16 用于正文20 用于小标题24 用于中标题32 用于大标题48 用于展示型标题。相邻档位的比例大致在 1.2 到 1.5 之间视觉上能明显区分。AI 生成时最容易犯的错是“中间档位太多”。它可能生成 15px、17px、18px 这种看起来精细实际上视觉上分不出来反而显得杂乱。尺度系统的作用就是砍掉这些中间档强制 AI 在有限的档位里选。5.3 语义令牌的命名规范语义令牌的命名要遵循“用途优先色值其次”的原则。不要用blue-500、gray-100这种色值命名要用primary、surface、border-subtle这种用途命名。原因很简单色值会变用途不会。今天的主色是蓝色明天可能换成紫色但“主色”这个用途不变。用用途命名换色时只改令牌定义所有引用处自动生效。用色值命名换色时你得全局搜索替换容易漏。一套基础的语义令牌大概包括背景类background、surface、surface-raised、surface-overlay文字类text-primary、text-secondary、text-disabled、text-inverse边框类border-default、border-subtle、border-strong、border-focus状态类primary、primary-hover、primary-active、danger、success、warningAI 生成时引用这些令牌而不是硬编码色值。这样即使 AI 在多个地方生成样式颜色也是一致的。6. 常见问题与排查技巧实录6.1 skill 装了但 agent 不认这是最高频的问题。表现是你明明装了 impeccable skill也用了触发词但 agent 生成的东西还是老样子数值乱七八糟。排查顺序是这样的。先确认 skill 目录位置对不对agent 的 skill 搜索路径可能不止一个你装的地方未必是它扫的地方。再确认清单文件格式对不对JSON 格式错误会导致 skill 加载失败但 agent 不报错。然后确认 agent 版本支持 skill 机制老版本可能压根没这功能。最后确认触发词是否匹配不同 agent 的触发词识别逻辑不一样有的靠关键词有的靠特定语法。我遇到过一次是清单文件里 skill 名称写错了agent 扫到了但注册失败静默忽略。改对名称后立刻生效。6.2 约束在长对话中失效claude cli 在长对话里容易“忘记”约束生成到后面几轮就开始放飞。这不是 impeccable 的锅是 agent 的上下文窗口问题。应对方法有两个。一是缩短对话轮次每生成一个独立模块就开新对话别在一个对话里生成整个项目。二是中途重申约束在 prompt 里再提一句“继续遵循 impeccable 规范”。实测重申一次能管好几轮。6.3 扩展扫描结果误报扩展扫描偶尔会误报把一些合理的自定义值标成违规。比如某个动画的过渡时间、某个特殊组件的尺寸这些本来就不该受尺度系统约束。处理方法是给扩展加白名单。大多数扩展支持在配置里排除特定选择器或特定属性。把那些确实需要自定义的地方加进白名单扫描结果就干净了。别为了追求“零违规”把合理的自定义也改掉那是本末倒置。6.4 生成结果“规范但呆板”这是另一个极端。约束太严AI 生成的东西虽然一致但缺乏变化看起来像模板套出来的。我的经验是约束管的是基础层创意管的是表现层。尺度、令牌、结构这些基础层要严格约束但配色方案、插画风格、动效这些表现层可以放开。impeccable 的约束主要作用在基础层表现层它管得不多。如果你觉得呆板问题可能出在 prompt 里没给表现层的发挥空间而不是约束太严。6.5 常见问题速查表问题现象可能原因排查动作skill 不生效目录/清单/版本/触发词逐项确认看 agent 日志长对话失效上下文窗口溢出缩短轮次中途重申扫描误报合理自定义被误判加白名单排除结果呆板表现层无发挥空间prompt 里放开表现层数值仍混乱约束未真正注入检查生成代码的数值来源扩展拖慢浏览器实时扫描开销大改用手动扫描7. 我个人的使用体会与几个实用建议用了一段时间 impeccable最大的感受是它把“审美”这个模糊的东西拆成了可执行、可检查、可修正的规则。以前让 AI 生成前端好不好看全凭运气现在至少有个底线出来的东西不会太离谱。几个实用建议。第一项目启动时就定好尺度系统和令牌别等生成了一堆页面再回头统一成本高十倍。第二CLI 和扩展配合用CLI 管生成扩展管审查两条腿走路比单用一条稳。第三别追求零违规约束是服务产品的不是产品服务约束该自定义的地方就自定义。第四把扫描结果导出成数据用脚本批量处理比手动改快得多。还有一个我最近在试的玩法把 impeccable 的令牌系统导出成一份设计规范文档直接给团队里的设计师和前端看。这样人和 AI 用的是同一套规则协作时少很多扯皮。这个方向后续还可以扩展比如把令牌同步到 Figma 变量、同步到 CSS 变量、同步到 Tailwind 配置让规范真正落到工程的每个环节。踩过的坑也不少。最亏的一次是没确认 agent 版本就装 skill折腾了一小时才发现是版本不支持。所以再强调一遍先确认 agent 本身跑得通再上 skill。这个顺序反了后面全是无用功。
