1 套 impeccable 设计技能，让 AI 前端协作产出生产级设计：AI 设计技能使用指南

1 套 impeccable 设计技能，让 AI 前端协作产出生产级设计：AI 设计技能使用指南

【免费下载链接】impeccable The design language that makes your AI harness better at design. 项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

让 AI 编程助手做前端，它十有八九交给你一个"能用但平庸"的页面：三张等大卡片排一排，hero 区放大数字加小标签，标题上面挤一行红色小字。界面没坏，只是没有主见。impeccable 是给 Claude、Cursor 这类 AI 编程助手安装前端设计技能的设计技能包，装上之后，AI 会像一个设计总监那样工作：先采集产品上下文，再创建视觉世界，逐条命令地评审、打磨、增强、修复，最后用有界验证（bounded verify，指设定上限的验证轮次而不是无限自测）完成交付。这套技能一共带了 23 个设计命令、四种访问者模式，以及一个在你编辑文件时自动把关的设计检测器（design detector）。下面按"你实际要走的路线"讲一遍。

🚀 三步跑通：让 AI 先"读懂你的项目"再动手

这一节解决"第一次用它到底敲什么"。

把仓库克隆下来（地址：git clone https://gitcode.com/GitHub_Trending/im/impeccable），进到任意一个你自己的前端项目目录，在 AI 助手里安装技能后，第一步永远是跑一次引导命令，把项目的产品上下文喂给模型：

<skill-base-dir>/scripts/impeccable context

这里的 <skill-base-dir> 是放着 SKILL.md 的技能目录，保持当前工作目录停在你的项目上。它会自动读 PRODUCT.md（产品事实）、DESIGN.md（现有视觉系统）、匹配的表面简报（surface brief），以及原生平台指导，然后把指令输出给模型。三个要点：每个会话只跑一次；要针对某个具名文件或路由就加 –target <path>；如果启动器不可用，AI 会先声明"context 没跑起来，我直接读现有上下文"，然后照常工作，不会卡住。

背后跑的是随技能附带的 Rust 自包含二进制，不依赖 Node 或任何运行时，首次运行按固定顺序找引擎二进制，找不到才从发布通道下载并做校验。你不需要关心这些，只需要知道它足够轻，不会成为流程里的瓶颈。跑完这一条命令，模型才真正"进入"你的项目。

🧭 按表面挑模式，别按产品类型

这一节解决"AI 该按什么标准设计这个页面"。

impeccable 把设计标准收敛成四种访问者模式（modes），本质问题是：访客在这个界面上"成功"长什么样？注意判定依据是请求的表面，不是产品本身——一个工具的落地页仍是 Persuade，一个时装屋的文档仍是 Read。

模式只持久化在对应表面的 surface brief 里，不会串到别的表面。想深入 Operate 和 Read 的设计细则，仓库里有专门的 playbook：.hermes/skills/impeccable/reference/mode-operate.md。先选定模式，后面所有命令的"好"才有统一标尺。

🗂️ 23 个命令速查：按"你此刻在做什么"对号入座

这一节解决"我这个问题该敲哪个命令"。

技能里的 23 个设计命令分成六大类（Build 5、Evaluate 2、Refine 6、Enhance 6、Fix 3、Iterate 1）。官方按类别分，我们换一个更贴手的维度——按你当下的处境分组：

几个细节值得记住：teach 是 init 的别名；shape 负责需求探索，只有涉及视觉世界决策才进入 new-work 流程。从零搭一个新表面时，流程会走到 comp-led 构建状态机：先 build-phase start 发牌定方向，再按 comps、spec、plates、hero、sections、motion、responsive 顺序关门，成稿过程类似下面这张"comp 原稿"到成品的转换（图为仓库测试素材里的 comp 示意稿）：

方向定下来之后，AI 在动任何 UI 代码之前（包括小修）会立即读一遍 reference/craft-floor.md。它定了质量底线：正文对比度不低于 4.5:1、行长 65–75 字符、一次主动效而不是零散特效，还有一组"品类默认"拒绝线——比如标题上方的 kicker/eyebrow 是硬性禁令，任何 brief 都挣不回。这是 AI 从"会写代码"到"有设计立场"的分水岭。

🔀 不带参数时，impeccable 会做什么

这一节解决"只发 /impeccable 不加词，会不会乱跑"。

不会。无参数时它读取 reference/routing.md，给你弹一个上下文感知菜单，绝不自动运行任何命令。菜单聪明在会读信号：如果项目有代码还没生成过 DESIGN.md，它推荐 document；如果从没跑过 critique，对已成型的项目它会把 critique 当强默认；如果 critique 分数低或还有 p0/p1 问题，推荐 polish；如果开发服务器在跑，live 才出现在选项里。本地文件检测器（无网络、不经过 npx）会把刚改动的文件命中的问题融进推荐。显式请求某命令时它直接加载对应 reference 执行；两个命令都合适时，只问你一次。其余情况按一般设计工作处理：缺 PRODUCT.md 且要开新表面，走 init 再进 new-work；对现有代码的小修，直接按 context 的指示在既有实现上做，事后提议补 init，而不是拦着你。

📐 三条设计原则和三条"如何设计"的铁律

这一节解决"它凭什么比通用提示词更克制"。

技能开头固定了三个工作原则：全力以赴——不投机取巧，交付物必须完整（用户自己提供的资产除外）；大胆做梦——要独特、出众、有启发性的作品；有界验证，而非死循环——验证上限覆盖整个循环：截图、缺陷扫描、微编辑、重建都算，先完整构建，再一次批量检查（Web 端桌面和移动一起看），一次性修完暴露的问题，最多再确认一轮就停手。无休止的自我 QA 既烧钱，效果还不如收尾交接做得好。

再叠加三条决策铁律：brief 优先——客户钉死的美学、字体、调色板，哪怕触发"饱和模式"警告也照办，把明确需求扭向自己的品味算失败；精修保留，重设计替换——polish 级别的动作保留现有身份、行为和文案，重设计则把旧外观当作反参考来替换，但绝不在已经放弃的旧皮肤上继续打磨；视觉权威是证据，不是文件名——缺一个 DESIGN.md 不代表项目是白纸，由 new-work 流程判定保留、扩展还是替换现有视觉世界。这两组规则一起，构成了"设计总监"而非"执行实习生"的底色。

🛡️ 编辑时自动把关：设计检测器 Hook 怎么开、怎么静默

这一节解决"AI 写出来的烂设计，有没有人当场拦"。

有。设计检测器 Hook 会在 UI 文件被编辑后自动运行，把发现浮出来。入口是一组子命令：

<skill-base-dir>/scripts/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>

规则分两档跑：per-edit 钩子只报"即时层"——坏图、溢出或裁剪、对比度失败、渐变文字、发光阴影、设计系统漂移这类机械且无歧义的问题；其余（文案节奏、调色板品味、布局韵律）延迟到会话结束时的 Stop 深度通道，对整轮会话碰过的 UI 文件跑全量规则，和已报过的去重后一次浮出。嫌每次编辑都全量跑，就把配置里的 hook.perEditRules 从 "all" 设回 "immediate"。配置落在项目里的 .impeccable/config.json，每位开发者的私有覆盖（含安装同意记录）写在 gitignore 的 .impeccable/config.local.json。

发现某条规则在某处确实误报，例外按"最窄优先"给：能定位到具体值就用 ignore-value，找不到值再退到 ignore-file，整个文件都不在设计评审范围（fixture、生成物）才用文件级，全项目抑制某规则才动用 ignore-rule。典型写法：

# 值级例外：确认 Inter 是有意选择
<skill-base-dir>/scripts/impeccable hooks ignore-value overused-font Inter –shared –reason "User confirmed Inter is intentional"

# 单条规则、单个文件例外
<skill-base-dir>/scripts/impeccable hooks ignore-value design-system-font-size "*" –file "src/overlay/widget.js" –reason "Widget builds its own type scale"

记住一条铁律：钩子自身永不写忽略配置，所有例外都必须走 impeccable hooks 命令，别手改 JSON。完整语义见 reference/hooks.md。

🩺 漂移诊断：doctor 命令的三级处置

这一节解决"项目用久了，AI 记的上下文还准吗"。

PRODUCT.md、DESIGN.md 及其 sidecar、.impeccable/config.json、surface brief、钩子配置——这些工件会随版本演进和代码演化慢慢偏离，这就是设计漂移（drift）。/impeccable doctor 专门报告并修复这类漂移：

<skill-base-dir>/scripts/impeccable doctor –json

monorepo 记得加 –target <path> 指向具体工作区，否则报告描述的是仓库根目录，往往不是你那个 app。输出里 findings 数组每条带 id、severity、summary、fix，空数组就是好消息。严重级别不是"多严重"，而是"该怎么处置"：auto 级不带决策，跑一次 doctor –fix 应用完一行汇报即可；mention 级只需你知道，逐条用一句话陈述；route 级指向某个具体命令（如 init、document），但这两个是对话，只在用户当轮要求时才跑。

两个别误读的发现：design-md-drift 统计的是 DESIGN.md 上次编辑以来视觉源目录的提交数，提交多不等于文档错；workspace-context-inherited 是有意设计的行为。最后一条红线：绝不把漂移修复当成设计任务的顺带副作用，CONTEXT_STALE 只报告不处置。协议全文在 reference/doctor.md。

🔬 什么时候用 live：在浏览器里边看边改

这一节解决"评审报告说得好，但我想自己指哪改哪"。

live 是技能里唯一的 Iterate 类命令，也是唯一需要人肉在场的设计动作：前提是一个跑着 HMR 热更新的本地 dev server（Vite、Next.js、Bun 等），或者浏览器里打开的静态 HTML，只支持本地 checkout，禁止注入生产站点。启动后进入长轮询循环：你在页面上点选元素、选一个设计动作，AI 生成的 HTML+CSS 变体经 dev server 热替换，选中哪个就留哪个。会话状态持久在 .impeccable/live/sessions/，中断后可以用 live-status、live-resume –id <SESSION_ID>、live-complete –id <SESSION_ID> 接上，不用从头再来。详细协议见 reference/live.md。判断标准很简单：要"快速比稿"就上 live，要"系统性地变好"就走 critique 加 polish。

⚠️ 容易踩的坑：九条来自流程本身的红线

这一节把前文散落的约束收拢成一张避坑清单。

• context 只跑一次。重复运行会稀释它的输出指令；跑不起来就走降级路径——声明后直接读现有 PRODUCT.md 与 DESIGN.md，不得虚构缺失上下文。
• init 和 document 各管一摊。init 只采集持久产品事实写进 PRODUCT.md，不发明视觉世界、不写 DESIGN.md；document 负责从现有代码反向生成 DESIGN.md。别让它俩越界，漂移诊断也是按这个分工派活的。
• 配置文件不手改。除声明 detector.extensions 这类追加项外，一切写入走 impeccable hooks 命令，保证校验与文件形态一致；配置坏了钩子会忽略坏文件继续用其余配置，hooks status 会标出被忽略的畸形文件。
• 全局关钩子用 hooks off（持久写 hook.enabled: false），遗留的环境变量 IMPECCABLE_HOOK_DISABLED=1 只是跟随当前 shell 的一次性覆盖。
• 验证有界。批量检查一轮、修完、最多再确认一轮。AI 如果开始第五轮自我截图，就是在浪费你的额度。
• live 仅限 Web。live 和内置 impeccable detect 都不适用原生平台，iOS/Android 表面的规则引擎是另一套。
• 无参数不自动执行，菜单只是菜单。
• 行内关闭标记是留给"必须随单文件离开仓库"的场景：impeccable-disable <rule> 关整文件，impeccable-disable-line / impeccable-disable-next-line 关单行。
• 仓库是只读的。本文所有命令都作用在你的项目目录上，技能目录本身不需要、也不应该被你改动。

回到开头那个平庸的定价页。装上 impeccable 之后，同样的请求会变成：一次 context 引导、一次模式判定（定价页是 Persuade）、一轮 critique 定标、若干条 Refine 命令逐层收口，最后停在一次批量截图验证上。差别不在 AI 会不会写 CSS，而在它有没有一位"设计总监"在场。想继续深挖，仓库里最直接的三处入口：全部 playbook 在 .hermes/skills/impeccable/reference/，新表面工作流看 reference/new-work.md，引擎二进制与动词分派的实现看 crates/。

【免费下载链接】impeccable The design language that makes your AI harness better at design. 项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考