Impeccable Design Skill 完整介绍

📝 给小白的注释：这份文档里有大量设计术语。每个术语第一次出现时，我都会用”【注：…】”的格式在后面解释这个词是什么意思。读完这份文档，你就能掌握前端 UI 设计的大部分基础知识了。

概述

Impeccable 是一个 AI 前端【注：前端 = 你在浏览器/手机里看到的界面部分的代码】设计辅助工具，由 Paul Bakaus（Google 前端布道师）开发。它本质上是一个分层设计系统【注：分层设计系统 = 把设计工作分成不同层次，每个层次解决不同问题的一种方法论】，专门用于调教 AI 编程助手（Claude Code、Cursor、Copilot 等）生成更专业、更有辨识度的 UI 界面【注：UI界面 = 用户看到的界面，比如按钮、菜单、页面布局这些东西】，而不是千篇一律的”AI 色”界面【注：AI色 = AI 默认生成的样式，比如紫色渐变、灰色卡片、Inter 字体这些大家都能认出来的”AI 味道”】。

项目地址：https://github.com/pbakaus/impeccable Stars：18.6k | License：Apache 2.0

整体架构

┌─────────────────────────────────────────────────┐
│              agents/anti-patterns.md               │
│         ← 反模式引擎维护指南（给 Skill 开发者看）      │
├─────────────────────────────────────────────────┤
│              skills/impeccable/                   │
│              ├─ SKILL.md                          │
│              │    ↳ 上下文收集 + 设计原则 + 14项规范  │
│              └─ reference/ (7个参考文件)           │
│                   typography.md                    │
│                   color-and-contrast.md            │
│                   spatial-design.md                │
│                   motion-design.md                 │
│                   interaction-design.md            │
│                   responsive-design.md             │
│                   ux-writing.md                   │
│                   craft.md                        │
│                   extract.md                      │
├─────────────────────────────────────────────────┤
│              skills/ (18个独立命令)                │
│  audit / polish / critique / animate / layout /   │
│  typeset / colorize / distill / harden / adapt /  │
│  bolder / clarify / delight / quieter / optimize /│
│  shape / overdrive                              │
└─────────────────────────────────────────────────┘

核心母技能：impeccable/SKILL.md

这是整个 Skill 的核心，所有子命令都会先调用它获取设计原则和上下文收集协议。

Context Gathering Protocol（上下文收集协议）【注： Protocol = 协议，就是一套规定的流程和规矩】

AI 设计失败的根本原因是没有收集项目上下文就开始画 UI【注：上下文 = 这个项目是给谁用的、做什么用的、想要什么感觉。这些背景信息叫做”上下文”，没有这些就开始设计，就像不看题目就答题一样】。这个 Skill 强制要求在做任何设计工作前先确认上下文：

先检查当前指令里是否已有 ## Design Context 章节【注：Design Context = 设计上下文，一个专门记录项目设计背景信息的章节】
再检查项目根目录是否有 .impeccable.md 文件
如果都没有 → 必须先运行 /impeccable teach 收集上下文

三大使用模式

/impeccable craft [功能描述]  →  构建模式：先 shape 再 build
/impeccable teach            →  教学模式：一次性收集项目设计上下文
/impeccable extract [目标]    →  提取模式：从代码中提取可复用的设计 token

14 项设计规范（Frontend Aesthetics Guidelines）【注：Guidelines = 指南/准则】

排版 Typography【注：Typography = 字体排版，包括选择什么字体、字有多大、行距多少这些】

核心原则：

使用 fluid type scale【注：fluid = 流动的，fluid type scale = 字体大小会随着屏幕大小自动变大变小，不是固定死的】（clamp()）【注：clamp() 是一个 CSS 函数，意思是”把字体大小限制在最小值和最大值之间，中间的值根据情况自动计算”】，app UI 用固定 rem 刻度【注：rem = CSS 里的一种单位，1rem 等于浏览器默认的字体大小（通常是16px），用 rem 可以让字体跟着用户的设置走】
用更少字号 + 更大对比度（相邻级别最小 1.25 ratio）【注：ratio = 比例，1.25 ratio 意思是下一级字号是上一级的 1.25 倍。比如 16px 的下一级是 20px（16×1.25=20）】
行高根据栏宽反比调整（窄栏紧、宽栏松）【注：行高 = 줄之间的高度。窄的文章栏（比如手机屏幕）需要行距紧一点，不然读起来会觉得很散；宽的栏可以行距大一点，这样读起来更舒服】
限制行宽 65-75ch【注：ch = 一个字符的宽度单位，65ch 大约是 65 个字母的长度。行宽太长的话，眼睛从一行末尾移到下一行开头很累；太短的话频繁换行也很烦人】

字体选择流程（防止 AI 总是用同一套字体）：

写 3 个品牌形容词（不是”现代”或”优雅”——那些是死词汇）【注：死词汇 = 太模糊、太空泛、放在哪个品牌都说得通的词，没有辨识度】
列出自己本能会选的 3 个字体
reject 掉 reflex_fonts_to_reject 列表（Fraunces、Newsreader、Inter、DM Sans 等 25 个”AI 默认字体”）【注：reflex = 本能反应，reflex_fonts = AI 一看到某个描述就条件反射想用的字体。这些字体不是不好，而是”太 AI 了”，一看就知道是 AI 选的】
去 Google Fonts / 字体网站找真正符合品牌的
交叉检查——如果结果还是 reflex pattern，回到第 4 步

绝对禁止：

单一一套字体打天下（必须配对：显示字体 + 正文字体）【注：显示字体（Display font）= 用来做标题的大字，有装饰性；正文字体（Body font）= 用来读段落的，要清晰易读。两套配合着用】
平坦的 type hierarchy【注：type hierarchy = 字体的大小层级。平坦 = 所有字都一样大，没有主次之分，看起来很无聊】（字号太接近）
大段文字全大写【注：全大写（比如”THIS IS TEXT”）读起来很累，因为全大写的时候每个字母形状差不多，眼睛不好找单词的起点】
Inter/Roboto/Arial/system defaults【注：这些都是最常见的系统字体，用了就”没有设计”，跟没装修的出租屋一样】

颜色与主题 Color & Theme

核心原则：

用 OKLCH 而不是 HSL——OKLCH 的等步长在视觉上真的等距，HSL 不是【注：OKLCH 和 HSL 都是描述颜色的数学方式。HSL 是老方式，问题是同样”走了 50% 的亮度”，黄色看起来很亮但蓝色看起来很暗——视觉上不公平。OKLCH 是新方式，“公平地”处理每种颜色，让渐变看起来均匀自然】
中性色要向品牌色微调（chroma 0.005-0.01 就能感知到）【注：chroma = 色彩饱和度/鲜艳程度。0.005-0.01 是非常非常小的数字，但人的眼睛能感觉到。这个微调让灰色不只是”死灰”，而是带一点点品牌色的温暖或冷调】
60-30-10 规则是关于视觉重量而不是像素数量【注：60-30-10 规则 = 60% 的地方用中性色（背景、白空间），30% 用次要颜色（副标题、边框等），10% 用强调色（按钮、重点）。这个比例是关于”看起来的重量感”，不是说像素要严格按照这个比例分布】

主题选择（Light vs Dark）：

暗模式不是反色模式的亮模式——暗模式下用亮度而非阴影表达深度【注：很多 AI 做的暗模式就是把亮模式反色一下（白的变黑，黑的变白）。但真正的暗模式设计是另一套逻辑：用亮度（brightness）而不是阴影（shadow）来表达”这个东西在上面/下面”】
根据用户和使用场景选择，不要默认：

场景	建议
金融交易 DEX（快速操作）	暗色
医院患者门户（深夜手机）	亮色
儿童阅读 app	亮色
复古摩托车论坛（晚上 garage）	暗色
SRE 监控面板（暗办公室）	暗色
婚礼规划清单（周日早晨）	亮色

绝对禁止：

彩色背景上用灰色文字（看起来褪色）【注：灰色文字在彩色背景上会显得”脏脏的”，像是褪色的老照片。应该用背景色的深色版本】
纯黑（#000）或纯白（#fff）【注：自然界里没有纯黑和纯白，都是带一点点其他颜色的。纯黑纯白看起来不自然、不高级】
AI 调色板（cyan-on-dark、紫色渐变、neon accents）【注：调色板 = 配色的整套颜色。AI 调色板 = 那种一看就知道是 AI 生成的配色，比如青色配暗色背景、紫色渐变、霓虹色彩的点缀】
渐变文字【注：渐变文字 = 文字的颜色从一种渐变到另一种，看起来五彩斑斓的。这是 AI 设计的一个典型”指纹”】
默认暗模式带 glowing accents【注：glowing accents = 发光效果的点缀，比如按钮边缘发光、霓虹灯效果。不是说这个效果本身坏，而是 AI 太爱用了，变成了 AI 味的标志】

布局与空间 Layout & Space

核心原则：

用 4pt 间距系统（4, 8, 12, 16, 24, 32, 48, 64, 96）而不是 8pt【注：间距系统 = 所有元素之间的空隙都按照固定的一些数字来设置。4pt 比 8pt 更细致，4, 8, 12 的序列比只有 8, 16, 24 给设计更多”中间地带”的选择】
用 gap 而不是 margin 处理兄弟元素间距【注：gap = CSS Grid/Flexbox 里的属性，直接设置网格元素之间的间距。margin 是传统方式，需要单独给每个元素设置。gap 更干净，不会出现奇怪的”多出来一个空隙”的情况】
用 repeat(auto-fit, minmax(280px, 1fr)) 做响应式网格【注：这是一个 CSS Grid 的写法，意思是”尽可能多地放列，每列至少 280px 宽，多出来的空间平分”。这样不用写媒体查询（breakpoint）就能自动响应不同屏幕大小】
Container queries 用于组件，viewport queries 用于页面【注：Container query = 根据”这个组件所在的容器”大小来决定样式；Viewport query = 根据”整个屏幕”的大小来决定样式。比如同一个卡片，放在侧边栏里和放在主内容区里，应该显示不同的布局——用 Container query 实现】

绝对禁止：

所有东西都包 card【注：card = 卡片，就是一个带边框或阴影的方形容器，里面装内容。AI 太爱用卡片了，结果所有东西都变成”框框套框框”，没有呼吸感】
嵌套卡片【注：嵌套卡片 = 卡片里面再放卡片，像是俄罗斯套娃。视觉上很吵】
相同的 card grid（icon + heading + text 重复）【注：card grid = 多个卡片排列成网格。每个卡片都是”图标 + 标题 + 文字”的组合，整整齐齐，AI 味十足】
Hero metric layout 模板【注：Hero metric = 首屏大数字布局，比如一个很大的数字（“98%”）+ 下面一个小标签（“用户满意度”）+ 旁边几个小统计。这是 AI 制作 dashboard 时最爱用的模板】
所有东西居中（不对称布局更有设计感）【注：所有东西都居中 = 乖乖排排坐，很无聊。不对称布局（左重右轻或反过来）更有”人工设计”的感觉】

视觉细节 Visual Details

两个绝对禁止的 CSS 模式（最典型的 AI 设计指纹）：

BAN 1：侧边条纹边框

/* 禁止 */
border-left: 3px solid red;
border-left: 4px solid var(--color-warning);
border-left: 5px solid oklch(...);
 
/* 任何 > 1px 的单边边框都不行 */

【注：border-left = 在左边加一条边。AI 太爱用这个技巧了（红色左边线 = 警告、蓝色左边线 = 信息），变成了 AI 味的标志。CSS = 控制网页样式的一种语言，写在 style 里】

BAN 2：渐变文字

/* 禁止 */
background-clip: text + linear-gradient

【注：background-clip: text = 把背景贴在文字上面；linear-gradient = 线性渐变。两个加起来就是”渐变文字”效果。纯色文字更有设计感】

动效 Motion【注：Motion = 动画效果，比如按钮按下去有弹性、页面切换有滑动的过程】

时间规则：

100-150ms：即时反馈【注：ms = 毫秒，1ms = 千分之一秒。100-150ms 快到几乎感觉不到延迟，但又足够让用户知道”我按到了”】（按钮按下、toggle）【注：toggle = 开关，比如一个按钮点一下开、再点一下关】
200-300ms：状态变化（菜单打开、hover 状态）【注：hover = 鼠标悬停在某个元素上时的状态】
300-500ms：布局变化（手风琴、模态框）【注：手风琴（accordion）= 点击一个标题，下面的内容展开，再点合上，像手风琴一样。模态框（modal）= 弹出一个对话框，背景变暗】
500-800ms：入口动画（页面加载）

Easing 曲线：【注：Easing = 缓动，指动画的速度变化曲线。比如”ease-out”意思是开始快然后慢慢停下来】

用 ease-out-quart/quint/expo【注：这些是不同类型的缓动曲线：ease-out-quart = 快速启动然后优雅地停下；ease-out-quint = 更夸张的减速；ease-out-expo = 非常果断的停止】（自然减速）
禁止 bounce/elastic【注：bounce = 弹跳效果，像皮球落地；elastic = 弹性效果，像橡皮筋。这两种在 2015 年很流行，现在看起来过时又廉价】（过时、廉价感）
退出动画比进入动画快约 25%【注：退出比进入快 = 让人感觉”东西消失了”，而不是”还在那里碍事”。比如菜单打开用 200ms，关上用 150ms】

技术规范：

只动画 transform 和 opacity【注：transform = 移动、缩放、旋转；opacity = 透明度。这两个属性改变时浏览器不需要重新计算布局，最省资源】（GPU 加速）【注：GPU 加速 = 调动显卡来处理动画，比用 CPU（处理器）更流畅】
高度动画用 grid-template-rows: 0fr → 1fr【注：这是做”展开/收起”动画的新技巧。以前做高度动画很卡，现在用 Grid 的技巧（把一格设成 0 fraction 然后变成 1 fraction）可以很平滑】
必须支持 prefers-reduced-motion【注：prefers-reduced-motion = 一个浏览器设置，有些人不舒服看动画（眩晕症等），可以要求”减少动画”。必须尊重这个设置，要么不播放动画，要么播一个很简单的版本】

交互 Interaction

8 个交互状态（每个都要设计）：【注：每个用户能点击/输入的东西，都需要有这 8 种状态】

Default 【默认状态，平常的样子】
Hover 【鼠标悬停时的样子】
Focus 【键盘选中时的样子，比如按 Tab 键跳到这个按钮】
Active 【正在按下时的样子】
Disabled 【不能用的样子，比如灰色的按钮】
Loading 【加载中的样子，比如按钮上有个转圈】
Error 【出错了的样子】
Success 【成功了的样子】

Focus Ring 正确做法：【注：Focus ring = 当你用键盘（Tab 键）导航到一个按钮时，周围会出现一个圈，表示”现在在这个元素上”】

/* 鼠标/触摸时隐藏 */
button:focus { outline: none; }
 
/* 只对键盘用户显示 */
button:focus-visible {
  outline: 2px solid var(--color-accent);
  outline-offset: 2px;
}

【注：这段 CSS 意思是：用鼠标点的时候不显示 Focus ring（因为鼠标用户不需要这个）；但用键盘的时候显示。outline = 外轮廓，offset = 往外偏移多少像素】

核心原则：

用 optimistic UI【注：optimistic UI = 乐观更新。比如点”点赞”按钮，不等服务器确认就立刻显示”已赞”，如果服务器说失败了再改回去。这样感觉超快！】（先更新，失败再回滚）
表单 blur 时验证，不要每次 keystroke【注：blur = 光标离开输入框。keystroke = 每次按键。验证不应该每次按键都触发（那样的话用户打一半字就报错），而是在用户”离开”这个输入框时检查】
用 inert 属性处理模态框【注：inert = HTML 的一个新属性，加在某个元素上会让它”不可交互、不可点击”，而且屏幕阅读器也会跳过它。用 inert 实现模态框的背景遮罩比老的 JS 方法简单很多】
Dropdown 绝对不要用 position: absolute + overflow: hidden 组合（会被裁剪）【注：dropdown = 下拉菜单。position: absolute = 相对于父元素定位；overflow: hidden = 超出父元素的部分隐藏。如果下拉菜单的父元素设置了 overflow: hidden，菜单就会被”剪掉”看不见】
Undo > Confirm（撤销比确认对话框更好）【注：Confirm = “你确定要删除吗？“点错了就完了。Undo = 直接删，然后显示”已删除 - 撤销”。撤销比确认好，因为用户点确认是”盲目的”，而撤销是”可以反悔的”】

UX Writing【注：UX Writing = 用户体验文案，指界面上的文字，比如按钮写什么、提示语怎么说、空状态显示什么】

按钮标签公式：

坏：“OK” / “Submit” / “Yes/No”
好：“Save changes” / “Create account” / “Delete 5 items”

【注：好的按钮文案 = 动词 + 结果。比如”Save changes”（保存修改）说清楚了点了这个按钮会发生什么，而”Submit”只是一个技术术语】

错误信息公式（3 要素）：

发生了什么【比如”邮箱格式不对”】
为什么【比如”邮箱地址里需要 @ 符号”】
怎么修【比如”请输入类似 name@example.com 的格式”】

空状态公式：【注：空状态 = 列表是空的、表单是空的那种状态，比如”暂无消息”】 承认空白 + 解释价值 + 提供明确行动【比如：“还没有项目哦。创建你的第一个项目，开始整理你的工作。” = 承认空白（还没有项目）+ 解释价值（整理工作）+ 明确行动（创建第一个项目）】

绝对禁止：

术语不一致（全程用 Delete，不要混 Remove）【注：一致性 = 全程用同一个词。第一次说”删除”，后面也说”删除”，不要说”移除”、“取消”、“丢掉”等同一个意思的不同词】
冗余复制（标题说了 intro 就不要再说）【注：冗余 = 重复。比如大标题已经是”关于我们的服务”，下面的介绍段落开头又说”我们的服务是…”，这就重复了，标题已经说过的不要再重复】
占位符当标签（占位符输入时会消失）【注：placeholder = 输入框里的浅色字，比如”请输入邮箱”，用户开始打字就消失了。标签（label）是输入框外面永远显示的文字，不能用 placeholder 代替 label】

7 个 Reference 参考文件

typography.md（排版参考）

OKLCH 颜色空间详解【注：见上文颜色部分的解释】
调色板结构：Primary / Neutral / Semantic / Surface【注：Primary = 主色，品牌最重要的颜色；Neutral = 中性色（灰白黑），用来放文字和背景；Semantic = 语义色，比如绿色=成功、红色=错误；Surface = 表面色，卡片、弹窗的底色】
WCAG 对比度要求【注：WCAG = 网页内容无障碍指南，规定了”文字和背景必须有足够的颜色对比度”，否则视力不好的人看不清。AA 级别是最低要求，AAA 是最高】
Dark Mode 与 Light Mode 的设计差异【注：暗模式和亮模式不只是颜色反色，很多设计细节都要重新考虑，比如阴影在暗模式下不太适用】

color-and-contrast.md（颜色与对比度）

OKLCH vs HSL（为什么 OKLCH 更好）【注：见上文颜色部分的解释】
Tinted Neutrals（微色感中性色）【注：不像纯灰那样死板，带一点点品牌色的灰色中性色】
Palette Structure（60-30-10 规则）【注：见上文，60%中性色、30%次要色、10%强调色】
Contrast & Accessibility（WCAG AA/AAA）【注：对比度 = 文字颜色和背景颜色的差异程度。WCAG AA 要求普通文字 4.5:1，大字 3:1。AAA 更严格，7:1 和 4.5:1】
Dark Mode 不是反色模式【注：暗模式不是简单地把颜色反色，而是用亮度层次来代替阴影层次】
Alpha 是设计味道（滥用透明度的问题）【注：Alpha = 透明度。滥用 rgba(255,0,0,0.5) 这种半透明颜色会导致：1）对比度不稳定 2）性能问题 3）视觉上不统一】

spatial-design.md（空间设计）

4pt 间距系统【注：见上文，间距的”刻度”，像音乐的音阶一样，越细选择越多】
Self-Adjusting Grid（repeat(auto-fit, minmax(280px, 1fr))）【注：见上文，自动适配屏幕的响应式网格写法】
Container Queries（组件级响应式）【注：见上文，根据组件所在容器大小而非屏幕大小来调整样式】
视觉层次——Squint Test（模糊测试）【注：Squint Test = 眯着眼睛看设计，如果眯眼后还是看不出重点在哪，说明层次不清】
Touch Target 44px 最小值【注：Touch Target = 手机上你要点的地方。苹果和谷歌都规定至少 44×44 像素，太小的话手指点不到】
Optical Adjustments（光学矫正，负 margin 补偿字形空白）【注：字体的每个字母两边都有空白，但视觉上看起来不均匀。比如”A”和”V”的字形斜的，挨在一起时空白看起来比实际小，需要微调位置让视觉上”看起来对齐”】

motion-design.md（动效设计）

100/300/500 时间规则【注：见上文，不同类型的动画应该用不同的时间长度】
Easing 曲线详解（为什么 bounce/elastic 已过时）【注：见上文】
prefers-reduced-motion 支持【注：见上文，有些用户不喜欢动画】
grid-template-rows: 0fr → 1fr 做高度动画【注：见上文，做高度展开/收起动画的现代方法】
感知性能（80ms 阈值——大脑同步感知的窗口）【注：人的大脑会把 80ms 内发生的事情”打包”成同时发生的。所以低于 80ms 的延迟用户感觉是”即时”的】
主动 vs 被动等待时间【注：主动等待 = 用户盯着进度条发呆（感觉很长）；被动等待 = 用户在看有趣的内容同时后台加载（感觉很短）】

interaction-design.md（交互设计）

8 个交互状态清单【注：见上文的 8 个状态】
Focus Ring 正确做法（focus-visible）【注：见上文】
inert 属性处理模态框【注：见上文】
Popover API【注：Popover = 弹出的小气泡提示或菜单，比如你点一个按钮，旁边弹出一个解释气泡。现在浏览器原生支持这个了】
CSS Anchor Positioning API【注：Anchor Positioning = 锚点定位，让一个弹出元素（比如下拉菜单）永远”粘着”它所属的按钮，不管屏幕怎么滚动都不会跑偏】
Dropdown 定位陷阱（overflow: hidden 剪裁问题）【注：见上文，下拉菜单被父容器的 overflow: hidden 剪掉】
Undo > Confirm 原则【注：见上文，撤销比确认对话框更好】
Roving Tabindex 键盘导航模式【注：Tabindex = 控制按 Tab 键时跳到哪个元素的属性。Roving Tabindex = 一组元素（比如菜单项）共用一个 tab 位置，用方向键轮流”占用”Tab】

responsive-design.md（响应式设计）

Mobile-First 写法【注：Mobile-First = 先设计手机版本，再逐步增强成平板和桌面版本。比”先做桌面版再缩小”更好，因为移动端限制更多】
Content-Driven 断点（根据内容决定断点位置）【注：breakpoint = 在某个屏幕宽度时改变布局。不是按照”iPad 是 768px”这种设备尺寸来设置，而是按照”内容在这个宽度开始看起来不对了”来设置】
pointer 和 hover 查询（不是只靠屏幕大小）【注：pointer 查询 = 检测用户是用鼠标还是手指；hover 查询 = 设备支持 hover 吗。触屏手机 hover 没意义，桌面hover有意义】
Safe Area（刘海屏处理）【注：Safe Area = iPhone 等有刘海屏的设备上，安全显示内容的区域，避免内容被刘海挡住】
srcset + sizes 响应式图片【注：srcset = 给浏览器提供多个版本的图片和每个版本的宽度，让浏览器根据屏幕大小和像素密度自动选合适的】
picture 元素做 Art Direction【注：Art Direction = 根据不同情况显示完全不同的图片，不只是大小不一样。比如手机显示竖版图片，桌面显示横版图片，这是构图上的不同选择】

ux-writing.md（UX 文案写作）

按钮标签公式【注：见上文的动词+结果公式】
错误信息模板（3 要素）【注：见上文，发生了什么 + 为什么 + 怎么修】
空状态设计公式【注：承认空白 + 解释价值 + 提供行动】
Voice vs Tone（品牌声音一致，但语气随场景变化）【注：Voice = 品牌的声音，是固定的（比如”专业但亲切”）；Tone = 语气，随情况变化（成功时欢快，错误时认真）】
德语 +30% 文本扩展问题【注：德语翻译一般比英语长 30%，所以 UI 要给翻译留空间，否则德语版会被截断】
术语一致性【注：全程用同一个词表示同一个意思，不换词】
确认对话框的适度使用【注：不要什么都弹出确认框，用户会变麻木。只在真正危险的操作（删东西、付钱等）时才用】

craft.md（构建流程）

Shape → References → Build → Visual Iteration → Present 五步流程。

【注：这个流程是：1) Shape = 先想清楚要做什么（规划） 2) References = 查阅设计参考 3) Build = 写代码 4) Visual Iteration = 在浏览器里看效果、反复调整 5) Present = 展示给用户】

关键点：Visual Iteration 是关键步骤，不能只实现一次就停：

在浏览器里看效果【浏览器里打开实际看】
对比设计简报【和最初的规划对照】
检查 AI Slop Test【检查是不是 AI 味太重】
检查所有状态（empty / error / loading / responsive）【空状态、错误状态、加载状态、不同屏幕大小】
重复直到满意

extract.md（提取设计系统）

从代码中提取设计系统的 6 步法：【注：设计系统 = 一套可复用的设计规范，包括颜色、字体、间距、组件等的标准定义。6 步法是：】

发现设计系统【找到现有的设计规范在哪里】
识别模式（重复 3+ 次才值得提取）【注：同一个东西用了 3 次以上，才值得提炼成可复用的组件】
计划提取【规划哪些要提取、怎么组织】
提取并丰富【做出来，并做得更好】
迁移【把旧代码更新成用新的设计系统】
文档化【写成文档，让别人也会用】

18 个子技能详解

/audit——技术质量审计

做什么： 对代码进行系统性技术检查，生成评分报告。

5 个维度评分（每项 0-4 分）：

Accessibility（A11y）【注：A11y = Accessibility 的缩写（11 个字母），网页无障碍设计】——对比度、ARIA【注：ARIA = 给屏幕阅读器等辅助工具用的 HTML 属性，让它们能正确读出网页内容】、键盘导航、语义 HTML【注：语义 HTML = 用正确的 HTML 标签表达意思，比如标题用 h1-h6、按钮用 button、文章用 article，而不是全部用 div】
Performance【注：Performance = 性能，网页加载和运行的速度】——Layout thrashing【注：Layout thrashing = 浏览器反复重新计算布局，比如循环里每次都读一个元素的宽度再改它的样式，浏览器会很卡】、动画性能、图片优化
Theming【注：Theming = 主题化，支持换皮肤/换颜色】——硬编码颜色【注：硬编码 = 直接写死 ff0000 这种具体颜色，而不是用变量。硬编码的问题是换主题时要改很多地方】，暗模式、Design Token 使用【注：Design Token = 设计变量，比如 —color-primary 而不是具体的 007bff】
Responsive Design【注：Responsive Design = 响应式设计，同一个网页在不同屏幕大小自动调整布局】——固定宽度【注：固定宽度 = 写死 width: 800px，在小屏幕上会溢出出滚动条】、Touch Target【注：Touch Target = 手指点按的目标区域大小，需要够大】、水平滚动
Anti-Patterns（关键）【注：Anti-Pattern = 反模式，看起来好像对但其实是错误做法的东西】——AI Slop 指纹检测【注：Slop = 垃圾，AI Slop = AI 生成的劣质设计风格】

输出：

Audit Health Score（总分 20 分）【注：5 个维度各 4 分，最高 20 分】
P0-P3 严重级别标注【注：P0 = 最高优先，阻塞性问题；P1 = 重要；P2 = 次要；P3 = 优化项】
具体代码位置
推荐的下一步命令

/critique——UX 设计评审

做什么： 从用户体验角度评估设计，结合 LLM 评审 + 自动化检测。

双轨评估：

LLM Design Review（设计总监视角）【注：LLM = 大语言模型，这里指 AI 扮演设计总监的角色来评审】
- AI Slop 检测【检查 AI 味】
- Nielsen 10 启发式评分（0-40 分）【注：Nielsen = 雅各布·尼尔森，可用性专家。10 启发式 = 他提出的 10 条可用性原则，比如”系统状态可见性”、“用户控制自由”等】
- 认知负荷评估（8 项检查清单）【注：认知负荷 = 用户使用界面时需要动多少脑筋。认知负荷太高会让人放弃使用】
- 情感旅程分析【注：情感旅程 = 用户从进入页面到完成任务的整个过程中，情绪怎么变化】
Automated Detection（自动化检测）【注：自动化检测 = 运行代码让机器自动找出问题】
- npx impeccable --json [target] CLI 扫描【注：CLI = 命令行界面，npx 是运行一个工具的命令】
- 25 条反模式规则【见 anti-patterns 部分】

5 种角色测试：【注：Persona = 用户画像，给一个典型用户起名字、设定特征，然后从他们的视角来测试】

Impatient Power User（Alex）【注：Power User = 高手用户，用过很多类似产品，追求效率】——效率专家，找快捷键
Confused First-Timer（Jordan）【注：First-Timer = 第一次用的新手，什么都不懂】——新手，需要引导
Accessibility-Dependent User（Sam）【注：用屏幕阅读器的用户，完全看不到界面】——屏幕阅读器用户
Deliberate Stress Tester（Riley）【注：Stress Tester = 压力测试员，故意用各种奇怪的方式使用产品】——边界条件测试
Distracted Mobile User（Casey）【注：手机用户，经常被打断，一只手操作】——手机单手操作

/polish——最终质量打磨

做什么： 对功能完整的代码进行最后一轮细节打磨。

【注：Polish = 抛光，像最后给玉器抛光一样，把棱角都磨光滑。不是重做，是精修】

20 项检查清单：

像素级对齐【注：每个元素的位置都要精确，不能”差不多”就行】
间距一致性【注：间距要符合间距系统（4pt 刻度），不能这里 10px 那里 13px】
字体层次【注：字体大小、轻重要有明显的层次，不能所有字都一样大】
所有交互状态【注：8 个交互状态（Default/Hover/Focus/Active/Disabled/Loading/Error/Success）都要实现】
过渡平滑度【注：状态变化时的动画要流畅自然】
术语一致性【注：全程用同一个词】
图标一致性【注：所有图标要来自同一个图标库，风格统一】
表单标签和验证【注：标签在输入框外面，验证信息在输入框下面】
错误/空状态/加载状态【注：三种边界情况都要处理】
Touch Target 44px【注：手机上的可点击区域要够大】
对比度 WCAG AA【注：颜色对比度要达标】
无 console 错误【注：console = 浏览器开发者工具的控制台，不能有红色报错】
CLS（布局偏移）【注：CLS = Cumulative Layout Shift，页面加载时内容不能乱跳】
Reduced Motion 支持【注：尊重用户减少动画的设置】

关键原则： 最后一轮，不是第一轮。不能在功能还没完整时就 polish。

/shape——UX/UI 规划

做什么： 在写代码之前先做结构化的 discovery interview，产出设计简报。

【注：Shape = 塑造，在动手画代码之前先把”形状”想清楚。Discovery Interview = 发现式访谈，通过问问题来了解需求】

Discovery Interview 内容：

目的 & 场景（谁用？什么心态？）【注：场景 = 用户在什么情况下用，比如”在地铁上单手刷手机”】
内容 & 数据（真实范围？边界情况？）【注：边界情况 = 比如列表可能有 0 条、1 条、1000 条数据，都要想清楚怎么显示】
设计目标（感觉像什么？）【注：是”高大上的感觉”？还是”亲切友好的感觉”？要有具体的描述】
约束（技术、内容、响应式、无障碍）【注：约束 = 限制条件，比如”必须支持 IE 浏览器”、“必须在 3 秒内加载完”】
反目标（什么不应该像？）【注：反目标 = 确定”绝对不是这个方向”，比如”绝对不像政府官网那种严肃沉闷的风格”】

输出： 设计简报（Design Brief）【注：Brief = 简报，一个规划文档，说清楚要做什么、怎么做、做成什么样】，需要用户确认后再继续。

/optimize——性能优化

做什么： 诊断和修复 UI 性能问题。

核心指标：

LCP < 2.5s（最大内容绘制）【注：LCP = Largest Contentful Paint，页面最大内容（通常是 Hero 图片或标题）加载完成的时间。越短越好，2.5 秒以内是好的】
FID < 100ms / INP < 200ms（首次输入延迟）【注：FID = First Input Delay，用户第一次点击/输入到浏览器响应的延迟。INP = Interaction to Next Paint，新一代的指标，衡量每次交互的延迟】
CLS < 0.1（累积布局偏移）【注：CLS = Cumulative Layout Shift，页面加载过程中内容有没有乱跳。0.1 以下是好的】

优化方向：

图片（WebP/AVIF、srcset、懒加载）【注：WebP/AVIF = 更小更清晰的图片格式；srcset = 根据屏幕选合适的图片；懒加载 = 不在屏幕上的图片先不加载】
JS Bundle（代码分割、tree shaking）【注：Bundle = 把所有 JS 代码打包成一个文件。代码分割 = 拆成多个文件按需加载；tree shaking = 去掉没用的代码】
CSS（关键 CSS 内联、containment）【注：关键 CSS = 首屏必需的样式直接写在 HTML 里，加速显示；containment = 告诉浏览器哪些区域独立，不影响其他区域】
字体（font-display、preload、subset）【注：font-display = 控制字体加载时文字的显示方式；preload = 提前加载字体；subset = 只加载用到的那部分字符（比如只加载英文，不加载中文）】
Layout Thrashing 避免【注：Layout Thrashing = 浏览器反复重新计算布局，导致卡顿】
GPU 加速动画【注：用 transform/opacity 做动画，调动 GPU 处理】
虚拟滚动【注：Virtual Scrolling = 只渲染屏幕上可见的那些列表项，比如 1000 条数据的列表，实际只渲染屏幕上能看到的 10-20 条，大幅提升性能】

/animate——动效设计

做什么： 战略性地添加动画和微交互。

【注：Animate = 加上动画。微交互（Micro-interaction）= 小的反馈性动画，比如按钮按下去轻轻下沉】

分类：

入口动画（页面加载编排、Hero 区域）【注：Entrance Animation = 页面刚出现时元素的出场动画，比如依次淡入】
微交互（按钮反馈、表单验证、toggle）【注：Micro-interaction = 微交互，比如点一个 toggle 开关有滑动效果】
状态过渡（show/hide、expand/collapse）【注：Transition = 状态 A 到状态 B 之间的动画过渡】
导航 & 流（页面过渡、Tab 切换、滚动效果）【注：Navigation Flow = 页面之间切换的过渡动画】
反馈 & 引导（Hover 提示、拖放）【注：Feedback = 操作后的视觉反馈；Guidance = 引导用户发现功能】

技术规范：

Duration：100-150ms / 200-300ms / 300-500ms / 500-800ms【见上文时间规则】
Easing：ease-out-quart/quint/expo（不用 bounce/elastic）【见上文缓动曲线】
只用 transform + opacity【见上文】
必须支持 prefers-reduced-motion【见上文】

/layout——布局改进

做什么： 改善布局、间距和视觉节奏。

【注：Layout = 页面元素怎么排列，比如导航在顶部、内容在中间、侧边栏在右边】

核心：

4pt 间距系统（用 gap 而不是 margin）【注：见上文间距系统】
视觉节奏（紧分组 + 大分隔）【注：Visual Rhythm = 视觉节奏，紧的地方看起来是一组，和其他组之间用大空白分开】
Grid vs Flexbox 选择（2D 用 Grid，1D 用 Flex）【注：Flexbox = 一维布局，适合一行或一列；Grid = 二维布局，适合行和列同时控制。比如导航栏用 Flexbox，整个页面用 Grid】
打破 card grid 单调性【注：不要所有卡片都一模一样的排列】
不包 card 的用间距和对齐创建分组【注：分组不一定要卡片，用空白和对齐线就可以】

/typeset——字体排版改进

做什么： 改进字体选择、层次、大小和可读性。

【注：Typeset = 字体排版，包括选择字体、设置大小、行距等】

核心：

避免默认字体（Inter/Roboto/Arial）【注：见上文，Inter 等是 AI 默认字体】
5 级 type scale（1.25 ratio）【注：Type Scale = 字体大小的阶梯。5 级 = 比如：正文 16px → 小标题 20px → 大标题 25px → 副标题 31px → 主标题 39px，1.25 ratio = 每一级是上一级的 1.25 倍】
Fluid vs Fixed（Marketing 页面 headings 用 clamp，App UI 用固定 rem）【注：Fluid = 自动变化的；Fixed = 固定的。营销页面的标题要大字fluid，App UI 的文字大小要 fixed 以保证空间可预测性】
行宽 45-75ch【注：见上文，行宽限制】
字号不用 px，用 rem【注：px = 绝对单位，16px 永远就是 16px；rem = 相对单位，会跟着用户的浏览器设置走。如果用户把浏览器字号调大了，rem 会跟着变大，px 不会】

/colorize——战略用色

做什么： 给单色或灰度设计添加有策略的颜色。

核心：

2-4 种主色（不要彩虹）【注：整体配色最好 2-4 种主要颜色，不要把所有颜色都用上去】
60-30-10 重量分配【注：见上文，60% 中性、30% 次要、10% 强调】
语义色（Success/Error/Warning/Info）【注：Semantic Color = 有含义的颜色，比如绿色=成功、红色=错误、黄色=警告、蓝色=提示】
OKLCH 调色【注：用 OKLCH 颜色空间来选色】
Accessibility（4.5:1 对比度）【注：见上文，颜色对比度要达标】

/distill——简化复杂性

做什么： 删减不必要的复杂性，揭示本质。

【注：Distill = 蒸馏，像提炼精油一样，去掉杂质，留下精华】

核心：

不是删功能，是删障碍【注：简化不是把功能删掉，而是把”让用户困惑/麻烦”的东西删掉】
Progressive Disclosure（渐进披露）【注：Progressive Disclosure = 先显示核心内容，细节慢慢展开。比如”更多选项”点开才有，不是一开始全摊开】
一个主要动作【注：每个页面/每个区域，应该只有一个最重要的动作，其他都是次要的】
合并相似元素【注：长得差不多、功能差不多的按钮/菜单，可以合并成一个】
视觉降噪【注：Visual Noise = 视觉噪音，画面太乱、太多东西在抢注意力】

/harden——生产级健壮性

做什么： 让界面抵抗边缘情况、错误和国际化问题。

【注：Harden = 硬化，让界面像硬化处理一样，经得起”折腾”——各种奇怪的输入、网络问题、翻译等】

测试维度：

极端输入（超长文本、emoji、RTL、CJK）【注：RTL = Right-to-Left，右到左的文字方向（阿拉伯语、希伯来语）；CJK = Chinese/Japanese/Korean，这些语言有特殊要求】
网络失败（离线、慢、timeout）【注：离线 = 根本没网；慢 = 网速很差；timeout = 请求超时没反应】
API 错误（400/401/403/404/500）【注：HTTP 状态码，400=请求格式不对，401=没登录，403=没权限，404=找不到，500=服务器错误】
i18n（文本扩展 +30-40%）【注：i18n = internationalization 的缩写，国际化，德语比英语长 30-40% 要留空间】
Text overflow（单行 ellipsis、多行 clamp）【注：Text Overflow = 文字超出容器；Ellipsis = 省略号（”…”）；Clamp = 限制行数，超出的部分省略】
Empty State（引导机会不只是”没有东西”）【注：Empty State = 空状态，比如空购物车、空搜索结果等】

/adapt——跨平台适配

做什么： 让设计在不同屏幕尺寸、设备、平台上有好效果。

策略：

Mobile：单栏、底部导航、Touch Target 44px、拇指区【注：拇指区 = 手机下半部分，用拇指容易点到的区域】
Tablet：双栏、Side Panel、混合交互【注：Side Panel = 侧边栏，平板电脑上可以一半显示列表、一半显示详情】
Desktop：多栏、侧导航、键盘快捷键、hover 状态【注：Desktop = 桌面电脑，有鼠标可以 hover 悬停】
Print：分页、黑白、移除交互元素【注：Print = 打印样式】
Email：窄宽（600px）、单栏、内联 CSS【注：Email = 邮件，邮件客户端对 CSS 支持很有限，必须用内联样式，宽度限制 600px】

/bolder——视觉冲击力

做什么： 放大弱的设计，增加影响力和个性。

警告： 最大的陷阱是用 AI 俗套（紫色渐变、玻璃拟态、霓虹灯）假装”大胆”。真正的 Bold 是独特的、有辨识度的。

【注：Bold = 大胆/醒目，不是夸张炫技，而是有辨识度、有个性的设计】

方向：

极端字体（Display 字体、Variable 字体）【注：Variable Font = 变化字体，一个字体文件里可以有无数种粗细/宽窄的变化】
颜色强度（饱和但不 neon）【注：Neon = 霓虹灯色，那种刺眼的荧光色】
空间戏剧性（3-5x 大小差）【注：对比要夸张，主要元素比次要元素大 3-5 倍，不是 1.2 倍】
打破网格【注：不老老实实对齐网格，适当”出格”创造张力】
纹理 & 深度（噪点、网点、双色调）【注：Noise Texture = 噪点纹理，像照片颗粒一样；Halftone = 网点，漫画印刷效果；Duotone = 双色调，用两种颜色处理图片】

/clarify——文案清晰度

做什么： 改进不清晰的 UX 文案、错误信息、微文案。

核心：

具体 vs 模糊（“Enter email” 不是 “Enter value”）【注：模糊的文案用户看了还是不知道要输入什么】
主动 vs 被动【注：主动 = “保存修改”，被动 = “修改已被保存”。主动语气更有力】
解释为什么（当不清楚时）【注：有时候要解释为什么需要这个信息，比如”为什么要留手机号”】
术语一致性【注：全程用同一个词】
不要替用户道歉或幽默（在错误场景）【注：出错了不要再”哎呀抱歉哦～“，直接说问题在哪里、怎么解决】

/delight——愉悦感设计

做什么： 添加乐趣、个性和意外的细节，让界面值得记住。

原则：

Delight 放大，不阻碍（< 1 秒，不延迟核心功能）【注：Delight = 让人开心的细节，但不能为了这个让用户等很久或操作变复杂】
惊喜和发现【注：有一些隐藏的小彩蛋，让用户觉得”有意思”】
匹配品牌（奢侈品牌优雅不浮夸，消费者品牌可以活泼）【注：银行 app 不能太活泼，投资 app 不能太无聊】
随着时间推移保持新鲜【注：不能同一个动画看 100 遍就腻了】

方向：

微交互（按钮按压、hover）【注：微交互 = 小动画反馈，让点击有”手感”】
文案个性（错误信息，空状态）【注：空状态和错误信息是加个性的好地方，比如”购物车空的，像刚毕业的大学生钱包一样”（但要小心不要太 low）】
插画 & 图标【注：定制插画比 stock 图更有辨识度】
彩蛋 & 隐藏惊喜【注：彩蛋 = Easter Egg，比如连续点击 Logo 七次会显示一个隐藏画面】
音效（谨慎）【注：音效要小心，很多人手机静音的】

/quieter——降噪柔和化

做什么： 降低过激设计的视觉强度，保持品质。

核心： 精炼不是无聊，是 Sophistication（精致感）。

【注：Sophistication = 精致/优雅，不是简陋而是讲究、有品位】

方向：

降低饱和度（70-85%）【注：降饱和度 = 让颜色不那么鲜艳，变成莫兰迪色调】
柔和调色板【注：柔和的配色，像水彩画一样】
减少视觉重量（字体粗细、边框）【注：视觉重量 = 某个元素”看起来有多重”。减少粗体使用、去掉多余边框】
简化动效【注：动画变得柔和gentle，不要太夸张】
增加留白【注：留白 = 白空间，让内容周围有呼吸的空间，不要堆得太满】

/overdrive——极限技术实现

做什么： 用技术上限让界面的任何部分感觉 Extraordinary。

【注：Overdrive = 过度驱动，就像汽车踩油门到最大，用各种前沿技术让体验超出用户预期】

这个 Skill 最高风险——必须先提案再确认。

工具箱：

View Transitions API【注：View Transitions = 页面切换的动画 API，让页面 A 可以”变形”成页面 B，而不是简单的淡入淡出】（共享元素变形）【注：Shared Element Transition = 同一个元素（比如一张图片）从页面 A 走到页面 B 时，是同一个元素在”移动”而不是消失再出现】
Spring Physics【注：Spring Physics = 弹簧物理，像真的弹簧一样有弹性、阻尼、质量，让动画更自然】（弹簧物理）
Scroll-Driven Animations【注：Scroll-Driven Animation = 动画跟着滚动条走，比如滚动页面时背景图慢慢放大】（CSS only，滚动驱动）【注：CSS only = 纯 CSS 实现，不需要 JavaScript】
WebGL/Canvas【注：WebGL 和 Canvas = 用显卡绘制图形，可以做 3D、粒子效果、复杂动画】（着色器、粒子系统）【注：Shader = 着色器，GPU 上跑的程序，可以做出火焰、水波、烟雾等效果；Particle System = 粒子系统，大量小粒子组成的视觉效果】
WebGPU【注：WebGPU = 下一代的 WebGL，更强大，但浏览器支持还不太完整】（下一代 GPU 计算）
Virtual Scrolling【注：Virtual Scrolling = 虚拟滚动，只渲染屏幕上能看到的那些项，处理百万级数据不卡】（虚拟滚动，百万行表格）
Web Workers【注：Web Workers = 在后台线程跑 JavaScript，不阻塞主线程】（主线程外的计算）【注：主线程 = 浏览器处理 UI 的地方，卡住主线程界面就会卡顿】
WASM【注：WASM = WebAssembly，用 C/C++/Rust 等语言写代码编译成浏览器能跑的高性能程序】（原生级性能）【注：原生级 = 接近手机/电脑原生 app 的性能水平】

核心原则：

Progressive Enhancement（必须有优雅降级）【注：Progressive Enhancement = 先保证基本功能在所有浏览器上能用，然后增强版在支持的浏览器上才开启】
60fps 目标【注：60fps = 每秒 60 帧，流畅动画的标准。如果低于 30fps 就能感觉到卡】
必须支持 prefers-reduced-motion【注：见上文，减少动画偏好】
测试真机，不只是 DevTools【注：DevTools = 浏览器开发者工具。真机 = 实际的 iPhone、安卓手机。模拟器/开发者工具和真机体验不一样】

/impeccable——主入口

核心母技能，也是用户直接调用的主命令。三个模式：

craft 模式：

/impeccable craft [功能描述]
→ shape + references + build + visual iteration

【注：craft = 手工打造，这个命令会完整走一遍 shape（规划）→ 参考文档 → Build（构建）→ Visual Iteration（视觉迭代）的流程】

teach 模式：

/impeccable teach
→ 一次性收集项目设计上下文
→ 写到 .impeccable.md 文件
→ 追加到 CLAUDE.md

【注：teach = 教导，这个命令会问一些问题来了解你的项目是什么风格、给谁用、想传达什么感觉，然后存起来以后用】

extract 模式：

/impeccable extract [目标]
→ 从代码中发现和提取设计系统模式
→ 组件 / Token / 模式

【注：extract = 提取，把代码里散落的设计规范（颜色、间距、字体、组件）提炼成一套系统的设计系统文件】

anti-patterns Agent 详解

agents/anti-patterns.md 是给 Skill 开发者看的维护指南，不是给普通用户看的，它的作用是维护 impeccable 的自动化检测引擎【注：检测引擎 = 自动扫描代码找出问题的一套程序】。

5 个需要同步的地方

当添加一条新规则时，5 个地方需要更新或重新生成：

位置	内容	如何同步
`src/detect-antipatterns.mjs`	规则元数据 + 检测逻辑	手动编辑
`src/detect-antipatterns-browser.js`	公开网站的浏览器引擎	`bun run build:browser`
`extension/detector/detect.js`	Chrome 扩展引擎	`bun run build:extension`
`extension/detector/antipatterns.json`	扩展的规则列表 UI	`bun run build:extension`
`public/js/generated/counts.js`	首页显示的检测数量	`bun run build`

【注：这个表格说的是：当你想在检测引擎里加一条新规则时，需要同步更新这 5 个地方，保证网站、浏览器扩展、命令行工具显示的数量都是对的】

规则 Schema

{
  id: 'icon-tile-stack',           // kebab-case，唯一
  category: 'slop',                 // 'slop'（AI 俗套）或 'quality'（真实问题）
  name: 'Icon tile stacked above heading',  // 人类可读
  description: '...',               // 1-2 句话，用于 CLI/扩展/tooltip
  skillSection: 'Typography',       // 对应的 SKILL.md 章节
  skillGuideline: 'large icons with rounded corners above every heading'  // 匹配 DON'T 行
}

【注：Schema = 数据结构，定义每条规则长什么样，包含哪些字段。kebab-case = 像这样写的命名（icon-tile-stack），用横线连接】

25 条反模式规则

分为两类：

slop（AI 色）：【注：Slop = AI 垃圾，AI 味太重的设计】

AI 调色板（cyan/purple gradient）【注：青色+暗色背景、紫→蓝渐变，AI 调色板典型代表】
渐变文字【注：文字颜色是渐变的】
侧边条纹边框【注：左边一条彩色边，AI 最爱】
图标堆叠标题【注：圆形图标 + 下面标题 = AI feature card 模板】
玻璃拟态【注：Glassmorphism = 半透明模糊效果，像磨砂玻璃】（glassmorphism）【注：比如一个卡片有 50% 透明度再加模糊背景】
Hero metric 布局【注：大数字 + 小标签 = AI dashboard 模板】
相同的 card grid【注：一排一模一样的卡片】

quality（质量问题）：【注：Quality = 真实的用户体验问题，不管是谁做的都要避免】

WCAG 对比度【注：颜色对比度不达标】
行长度【注：文字行太长了难读】
触摸目标【注：太小了手指点不到】
跳过标题级别【注：h1 之后直接跳到 h3，跳过了 h2】
文字对齐【注：两端对齐如果字词间距拉太开很难看】

总体工作流

用户说 "/impeccable craft 做一个 Dashboard"
        ↓
    /impeccable SKILL.md
        ↓
Context Gathering Protocol（检查 .impeccable.md 或运行 teach）
        ↓
调用 /shape 做 Discovery Interview → 设计简报
        ↓
用户确认设计简报
        ↓
加载 reference 文件（spatial/typography/color/motion...）
        ↓
Build（结构 → 布局/间距 → 字体/颜色 → 交互状态 → 边界情况 → 动效 → 响应式）
        ↓
Visual Iteration（在浏览器里看效果，迭代修正）
        ↓
Present 给用户
        ↓
用户不满意 → 继续迭代或调用其他 /audit /polish /critique 等专项命令

安装方式

# Clone 仓库
git clone https://github.com/pbakaus/impeccable.git /tmp/impeccable
 
# 复制到项目（Claude Code）
cp -r /tmp/impeccable/.claude /你的项目/
 
# 或者复制到全局
cp -r /tmp/impeccable/.claude/* ~/.claude/

【注：Clone = 下载代码到本地；cp -r = 递归复制整个文件夹】

安装后在 Claude Code 中对这个项目说话时，直接使用 /audit、/polish、/impeccable craft 等命令即可。

核心价值总结

不只是设计指南：是系统性的 AI 设计调教方法论【注：方法论 = 不是给你一堆规则让你死记硬背，而是一套思考方式和工作流程】
反模式识别：明确告诉你什么是”AI 做的”样子，以及怎么避免【注：反模式 = 看起来好像对、但其实是错误的做法。比如全用卡片包裹内容看起来整齐但很 AI 味】
渐进式修复：18 个专项命令，每个专注一个方向，可以逐步迭代【注：渐进式 = 一点一点来，今天调排版、明天调颜色、后天加动效】
上下文驱动：不做上下文收集就不做设计——这是最核心的规矩【注：上下文 = 给谁用、做什么用、想什么感觉。不问清楚就开始画 UI，做出来的一定是通用的、AI 味的】
量化评估：audit 和 critique 都有评分系统，能看到改进前后的变化【注：量化 = 打分、给数字。可以看到从 12 分进步到 17 分，而不是模糊的”变好了一点点”】

附录：术语表（给完全小白的速查）

术语	简单解释
UI 界面	你在屏幕上看得到的所有元素：按钮、菜单、文字、图片
前端	浏览器里跑的代码（HTML + CSS + JavaScript）
设计 Token	一个有名字的变量，存着设计值，比如 `--color-primary: #007bff`
WCAG	网页无障碍标准，让残障人士也能用网页
A11y	Accessibility（无障碍）的缩写，11 个字母所以叫 A11y
ARIA	给屏幕阅读器读的 HTML 属性
Flexbox	CSS 布局方式，适合一行或一列排列
Grid	CSS 布局方式，适合行和列同时控制
Container Query	根据”所在容器”大小决定样式，而不是屏幕大小
Breakpoint	响应式设计里，布局发生变化的屏幕宽度
Touch Target	手机上手指点击的区域，必须 ≥44px
Safe Area	iPhone 刘海屏/圆角屏的安全显示区域
Modal / Dialog	弹出来的对话框，背景通常会变暗
Tooltip	鼠标悬停时出现的小提示气泡
Skeleton Screen	加载时显示的灰色占位块，像骨架一样
Optimistic UI	先乐观地显示结果，再异步确认，不让用户干等
CLS	页面加载时内容乱跳的程度，越低越好
LCP	页面主要内容加载完成的时间，越短越好
Tree Shaking	构建时去掉没用的代码，减小文件体积
Lazy Loading	懒加载，不在屏幕上的内容先不加载
WebP / AVIF	比 JPEG/PNG 更小更清晰的图片格式
Prograssive Enhancement	先保证基本功能能用，再增强高级效果
Shadow DOM	组件内部的 DOM 结构，外部样式影响不到
Semantic HTML	用正确的 HTML 标签表达意思（标题用 h1-h6，按钮用 button）
Design System	一套设计规范和组件库，确保所有产品长一个妈样

逸尘的AI知识库

探索

Impeccable Design Skill设计

Impeccable Design Skill 完整介绍

概述

整体架构

核心母技能：impeccable/SKILL.md

Context Gathering Protocol（上下文收集协议）【注： Protocol = 协议，就是一套规定的流程和规矩】

三大使用模式

14 项设计规范（Frontend Aesthetics Guidelines）【注：Guidelines = 指南/准则】

排版 Typography【注：Typography = 字体排版，包括选择什么字体、字有多大、行距多少这些】

颜色与主题 Color & Theme

布局与空间 Layout & Space

视觉细节 Visual Details

动效 Motion【注：Motion = 动画效果，比如按钮按下去有弹性、页面切换有滑动的过程】

交互 Interaction

UX Writing【注：UX Writing = 用户体验文案，指界面上的文字，比如按钮写什么、提示语怎么说、空状态显示什么】

7 个 Reference 参考文件

typography.md（排版参考）

color-and-contrast.md（颜色与对比度）

spatial-design.md（空间设计）

motion-design.md（动效设计）

interaction-design.md（交互设计）

responsive-design.md（响应式设计）

ux-writing.md（UX 文案写作）

craft.md（构建流程）

extract.md（提取设计系统）

18 个子技能详解

/audit——技术质量审计

/critique——UX 设计评审

/polish——最终质量打磨

/shape——UX/UI 规划

/optimize——性能优化

/animate——动效设计

/layout——布局改进

/typeset——字体排版改进

/colorize——战略用色

/distill——简化复杂性

/harden——生产级健壮性

/adapt——跨平台适配

/bolder——视觉冲击力

/clarify——文案清晰度

/delight——愉悦感设计

/quieter——降噪柔和化

/overdrive——极限技术实现

/impeccable——主入口

anti-patterns Agent 详解

5 个需要同步的地方

规则 Schema

25 条反模式规则

总体工作流

安装方式

核心价值总结

附录：术语表（给完全小白的速查）

关系图谱

目录