目录概述与核心理念快速入门四大设计模式命令完整参考核心工作流Live 实时迭代模式设计制品管理工艺底线Hooks 自动检测最佳实践与反模式1. 概述与核心理念1.1 什么是 ImpeccableImpeccable 是一个面向 Claude Code 的前端设计技能包将 AI 的设计能力从够用提升到卓越。它适用于网站— 落地页、营销站、产品首页应用 UI— 仪表盘、编辑器、管理后台、设置页组件— 表单、按钮、卡片、空状态、引导流程设计系统— 设计令牌、组件库、设计规范不适用于后端代码或非 UI 任务。1.2 三条核心原则原则含义全力以赴 (Go all out)不妥协、不走捷径。交付物必须完整。大胆梦想 (Dream big and bold)独特、美丽、出众、高度启发性的作品。工具迭代 (Iterate with tools)利用截图、浏览器预览等工具反复打磨直到达到标准。1.3 命令速查表命令类别一言描述/impeccable shape构建编码前规划 UX/UI/impeccable init构建创建 PRODUCT.md/impeccable document构建生成 DESIGN.md/impeccable extract构建提取可复用令牌和组件/impeccable critique评估UX 设计评审/impeccable audit评估技术质量审计/impeccable polish精炼发布前最终质量检查/impeccable bolder精炼增强平淡设计/impeccable quieter精炼降低激进设计/impeccable distill精炼精简至本质/impeccable harden精炼生产就绪加固/impeccable onboard精炼设计引导流程/impeccable animate增强添加有目的的动效/impeccable colorize增强添加战略性色彩/impeccable typeset增强改善字体排版/impeccable layout增强修复间距和层级/impeccable delight增强添加个性和记忆点/impeccable overdrive增强突破常规极限/impeccable clarify修复改善 UX 文案/impeccable adapt修复适配不同设备/impeccable optimize修复优化 UI 性能/impeccable live迭代浏览器实时变体迭代2. 快速入门2.1 首次使用在 Claude Code 中通过/impeccable前缀调用/impeccable不带参数运行时Impeccable 会分析项目上下文给出智能化的 2-3 条推荐命令。例如项目没有PRODUCT.md→ 推荐/impeccable init项目有代码但没有DESIGN.md→ 推荐/impeccable document从未做过设计评审 → 推荐/impeccable critique开发服务器正在运行 → 推荐/impeccable live2.2 基础配置大多数命令在首次运行时Impeccable 会自动通过context.mjs加载项目上下文无需手动配置。但对于 Live 模式需要确保项目有运行的开发服务器支持 HMR或项目是静态 HTML 文件2.3 命令格式/impeccable 命令 [目标]目标可以是文件路径、URL、组件名或页面路由。例如/impeccable critique src/pages/index.astro /impeccable polish src/components/Hero.tsx /impeccable audit public/index.html3. 四大设计模式每个界面都有一个访客成功模式。选择正确的模式是设计决策的第一步。3.1 Persuade说服访客要做出决定并行动设计就是产品。适用场景落地页、营销页面、活动页、定价页。核心目标赢得注意力和行动。用真实的图像传达信息遵循已确立的世界观而非品类惯例。3.2 Operate操作访客要完成任务。适用场景应用 UI、仪表盘、编辑器、管理后台、设置、工具。核心目标可扫描性、一致性、原生预期和真实使用场景优先于表达。品牌存在于精确的细节中。3.3 Read阅读访客要理解内容。适用场景文档、文章、指南、帮助页面、更新日志。核心目标为理解而结构化然后让阅读体验值得停留。3.4 Experience体验访客置身于作品之中。适用场景作品集、画廊、展示页。核心目标让作品从第一个视口引导一切界面退居幕后。重要提示模式由被请求的界面决定而非产品。一个工具的落地页仍然是 Persuade一个时尚品牌的文档仍然是 Read。4. 命令完整参考Impeccable 提供 18 个子命令按功能分为六大类4.1 构建类 (Build)shape [feature]— 规划 UX/UI在编写代码之前进行 UX/UI 规划。分三个阶段发现访谈1-2 轮结构化提问了解目的、用户、成果、约束确定设计方向通过概念工作坊选择视觉世界撰写 Brief输出精炼的设计简报shape只规划不实现。完成后应使用 writing-plans 制定实施计划。init— 初始化产品上下文捕获持久化的产品真相生成PRODUCT.md。包含平台web / ios / android / adaptive用户画像和使用场景产品目的和定位运营上下文能力、约束和术语品牌承诺已有证据和资产产品原则无障碍和包容性需求首次使用 Impeccable 时强烈建议先运行此命令。document— 生成设计系统文档从现有代码中提取设计令牌和组件生成DESIGN.md和.impeccable/design.json。两种模式扫描模式默认从 CSS 变量、Tailwind 配置、组件库中自动提取种子模式适用于尚无代码的项目通过工作坊确定视觉方向extract [target]— 提取可复用令牌和组件识别重复模式、硬编码值和不一致变体将其提取为设计系统中的可复用令牌和组件。4.2 评估类 (Evaluate)critique [target]— UX 设计评审执行完整的 UX 设计评审包含双评估机制评估 A设计总监视角包括设计特异性、认知负荷、情感旅程、Nielsen 启发式评分和评估 B自动化检测器扫描 浏览器可视化两个评估必须在独立的子代理中并行执行Nielsen 10 项启发式评分每项 0-4 分满分 40设计特异性评估判断界面是否为该产品定制还是品类可互换的认知负荷分析基于 8 项清单评估心理负担5 种角色测试Alex高效用户、Jordan新手、Sam无障碍用户、Riley压力测试、Casey移动端分心用户持久化快照评审结果保存到.impeccable/critique/目录支持趋势追踪输出 P0-P3 优先级问题和建议的后续命令。audit [target]— 技术质量审计从 5 个维度进行可测量的代码级审计每项 0-4 分满分 20维度检查内容无障碍 (A11y)对比度、ARIA、键盘导航、语义 HTML、alt 文本性能布局抖动、动画性能、资源优化、包大小主题化硬编码颜色、暗色模式、令牌一致性响应式设计固定宽度、触摸目标、横向滚动、文本缩放实现完整性设计系统一致性、反模式检测注意critique关注设计质量用户体验audit关注技术质量代码实现。两者互补。4.3 精炼类 (Refine)polish [target]— 发布前最终质量检查系统性打磨整个用户路径建立系统基准读取 DESIGN.md分类问题收集证据使用功能读取之前的 critique 快照分类修复优先级 1功能性缺陷、数据丢失、误导状态优先级 2缺失的加载/空/错误/成功/禁用状态优先级 3流程、层级、响应式偏移优先级 4视觉和动效不一致优先级 5代码和资源清理bolder [target]— 增强平淡的设计放大设计的某一部分使其匹配周围部分的表达水平。核心原则范围至上只触碰被命名的目标其他一切保持不变使用系统已有的语言放大系统已有的主题动机和字体比例骨骼测试去掉文案后结构本身是否仍能传达核心信息quieter [target]— 降低过于激进的设计减少视觉强度但保留个性。安静不等于无聊而是精致和舒适。关键手段降低饱和度到 70-85%用着色的灰色替代纯灰色减少装饰元素缩短动效距离和时间保留核心信息的视觉锚点distill [target]— 精简至本质去除复杂性保留核心。移除视觉噪音、冗余内容和嵌套结构。harden [target]— 生产就绪加固处理真实世界的边缘情况极端文本长度100 字符的名称特殊字符emoji、RTL、CJK国际化德语比英语长 30%、阿拉伯语 RTL、日期/数字格式网络错误状态offline、timeout、API 错误码空状态、加载状态、权限状态大数据集1000 条目并发操作和竞态条件onboard [target]— 设计引导流程设计首次使用体验、空状态和激活流程。4.4 增强类 (Enhance)animate [target]— 添加有目的的动效用动效解释状态、关系和层级。核心要求确定一个焦点时刻作为动效核心选择表达意义的材质不只是 transform opacity遵循时间规范100-150ms 即时反馈500-800ms 焦点入场出口快于入口尊重prefers-reduced-motion内容在默认状态下始终可见colorize [target]— 为单色 UI 添加战略性色彩不只是在各处撒颜色。选择色彩策略Restrained克制中性色 单一强调色Committed投入一种饱和色占据表面 30-60%Full palette全调色板3-4 个有命名的角色色Drenched浸染表面就是颜色本身typeset [target]— 改善字体排版修复字体层级、字体配对和排版比例。避免常见的 AI 默认字体选择。layout [target]— 修复间距和视觉层级处理间距节奏、网格对齐和视觉层级。delight [target]— 添加个性和记忆点在值得奖励的时刻注入产品个性成功确认、等待状态、空状态引导、错误恢复。核心原则愉悦感必须来自产品机制本身而非通用的装饰。overdrive [target]— 突破常规极限将界面的某个部分推向技术上非凡的领域。例如百万行数据的虚拟滚动表格从触发按钮变形而来的对话框View Transitions API实时流式验证的表单Canvas/WebGL 渲染的数据可视化滚动驱动的电影级动画重要此命令会先提出 2-3 个方向供你选择不会直接实施。4.5 修复类 (Fix)clarify [target]— 改善 UX 文案修复标签、错误信息和引导文案使用产品的语言。控件命名其动作错误命名问题和恢复方式。adapt [target]— 适配不同设备处理响应式断点、触摸目标、文本缩放和设备特定行为。适用于 web原生平台使用adapt.native.md。optimize [target]— 诊断和修复 UI 性能分析并修复渲染性能、包大小和加载速度问题。4.6 迭代类 (Iterate)live— 实时视觉变体模式在浏览器中选择元素获取 AI 生成的 HTMLCSS 变体通过 HMR 热替换实时预览。详见第 6 章。4.7 其他管理命令命令说明/impeccable hooks on|off|status管理设计检测 Hook/impeccable doctor诊断和修复项目 Impeccable 制品的漂移pin / unpin为常用命令创建独立快捷方式5. 核心工作流5.1 标准设计流程/impeccable init → 捕获产品上下文 (PRODUCT.md) /impeccable shape 目标 → 规划 UX/UI 设计简报 /impeccable document → 提取/建立设计系统 (DESIGN.md) [实施阶段] /impeccable critique → 设计评审 /impeccable audit → 技术审计 /impeccable polish → 发布前打磨5.2 新建视觉世界 (New Work Flow)当需要创建新界面或更换视觉标识时确定已有的真相— 读取 DESIGN.md、代码、令牌和组件判断是重构、扩展还是新建通过提问明确方向— 根据模式Persuade/Operate/Read/Experience提出 2-3 个相关问题选择发明程度扩展现有界面继承视觉系统在现有世界中创建完整界面运行概念种子脚本创建或替换视觉世界7 个具体视觉系统候选 → 概念种子 → 方向决策确定方向— 撰写方向契约Thesis / Own-World / Story / First Viewport / Form可视化方向— 在构建前生成设计预览图并获得批准全力构建— 构建选定的方向不妥协检查和完成— 运行完成评审代理5.3 方向决策机制Impeccable 使用独特的概念种子机制从产品的文化世界导出 7 个具体的视觉系统候选运行concept-seed.mjs脚本随机分配一个方向防止用户总选最安全的选项同时提供 2-3 个候选方向作为替代用户可按需重新抽选或指定自己的方向始终提供品类标准作为安静的默认退出选项6. Live 实时迭代模式Live 模式是 Impeccable 最具特色的功能在浏览器中直接选择和迭代 UI 元素。6.1 工作流程用户/impeccable live → live.mjs 启动辅助服务器 → 打开应用页面 用户在浏览器中 1. 点击 Impeccable 图标激活选择模式 2. 点击任意 UI 元素选中它 3. 在动作栏中选择操作bolder, typeset, colorize 等 4. 可选在元素上添加注释和草图 5. 点击 Go 提交生成请求 Claude后台 1. 读取元素的 HTML/CSS 和用户注释 2. 提取身份锁identity lock——当前表面的颜色、字体、布局 3. 生成 3 个在品牌内的变体带可调参数 4. 将变体写入源文件 5. 浏览器通过 HMR 自动刷新 用户在浏览器中 1. 按 1/2/3 键切换变体 2. 拖动参数滑块实时调整 3. 点击 Accept 确认变体 4. 或点击 ✕ 放弃 Accept 后 → live-accept.mjs 将选中的变体持久化到源文件 → 清理临时标记 → 参数值烘焙到最终 CSS6.2 身份锁 (Identity Lock)Live 模式的核心约束所有变体必须读起来像同一个品牌。每个变体从 6 个轴中选择一个不同的主轴层级 (Hierarchy)布局拓扑 (Layout topology)字体系统 (Typographic system)色彩策略 (Color strategy)密度 (Density)结构分解 (Structural decomposition)6.3 变体参数每个变体可附带 0-4 个可调参数由元素大小决定预算元素大小建议参数数叶子/微小单个按钮、图标0小型标签输入、简单卡片0-1中型段落组件、导航簇目标 2大型英雄区、完整页面区域2-3最多 4三种参数类型range滑块驱动 CSS 变量--p-idsteps分段选择驱动 data 属性data-p-idtoggle开关同时驱动 CSS 变量和 data 属性6.4 Steer 模式Live 模式还支持Steer——通过浏览器中的全局栏发送页面级方向指令无需选中具体元素。支持语音输入Web Speech API。6.5 首次配置首次运行live需要配置.impeccable/live/config.json。Impeccable 会根据框架自动建议配置框架filesinsertBeforeVite / React (SPA)[index.html]/bodyNext.js (App Router)[app/layout.tsx]/bodySvelteKit[src/app.html]/bodyAstro[root layout .astro]/body多页面站点[public/**/*.html]/body如果项目有 CSP内容安全策略需要允许http://localhost:8400。7. 设计制品管理Impeccable 维护几个关键制品文件7.1 PRODUCT.md位置项目根目录内容持久化的产品真相——用户、目的、定位、约束、品牌承诺。不包含视觉设计内容。7.2 DESIGN.md位置项目根目录内容持久化的视觉设计决策。遵循 DESIGN.md 规范包含--- name: 项目名称 colors: primary: #b8422e typography: display: fontFamily: Cormorant Garamond, Georgia, serif components: button-primary: backgroundColor: {colors.primary} ---8 个规范章节按顺序Overview概述 创意北极星Colors角色色 命名规则Typography字体配对、层级、比例Layout网格、间距、响应式Elevation Depth阴影词汇、深度策略Shapes圆角、边框、剪裁Components按钮、卡片、输入框等Dos and Donts视觉约束7.3.impeccable/design.jsonDESIGN.md 的机器可读扩展包含色调渐变tonal ramps阴影/动效令牌断点完整组件 HTML/CSS 片段用于 Live 面板渲染7.4 表面简报 (Surface Briefs)某个特定路由或组件的策略存储为独立的简报文件。包含范围、访客模式、受众、任务、约束、选定的方向、未解决的决策。7.5 制品健康检查使用/impeccable doctor检查所有制品的漂移状态。不要在设计任务中作为副作用修复漂移。8. 工艺底线 (Craft Floor)工艺底线是 Impeccable 的质量标准——在每个构建完成后必须检查的事项。8.1 必须验证项目标准对比度正文 ≥4.5:1大文字 ≥3:1深度阴影有偏移和柔和模糊间距紧凑组合宽松分离标题上方空间大于下方字体正文宽度 65-75ch展示最大 6rem字距下限 -0.04em动效一个精心设计的时刻不是分散的效果状态hover, disabled, loading, error, empty文案控件命名其动作错误命名问题和恢复方式覆盖每个 Brief 要求都存在且可在数秒内找到8.2 默认禁止这些是品类的默认模式不是绝对禁令。当 Brief 明确要求时可以使用。但当方向是自由的选择它们意味着你没有真正做决定页面骨架相同尺寸的图标标题文字卡片作为页面结构大数字小标签支撑数据强调色的英雄指标模板每个段落上方的紧凑大写引导词无信息量的章节编号01/02/03用于不需要中断或保护焦点任务的模态框表面习惯渐变文字装饰性玻璃和模糊效果超过 1px 的彩色边框迷你图表、进度环和柔和阴影的圆角矩形占位技术感的等宽字体因品类默认选择亮色/暗色——应从使用场景出发9. Hooks 自动检测9.1 设计检测器 HookImpeccable 可以在每次 UI 文件编辑后自动运行检测器/impeccable hooks on # 启用 /impeccable hooks off # 禁用 /impeccable hooks status # 查看状态检测器会扫描 HTML/CSS 文件识别设计反模式梯度文字、无意义的引导词、卡片嵌套等。9.2 忽略规则可以通过.impeccable/critique/ignore.md配置需要忽略的发现。10. 最佳实践与反模式10.1 推荐工作流新项目init→shape→document→ 实施 →critique→polish现有项目改进critique→ 根据结果选择适当命令 →polish快速迭代live在浏览器中实时调整发布前auditpolish10.2 品牌字体自查以下字体是训练数据默认值选择它们需要额外理由Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter作为展示字体, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans10.3 常见反模式反模式正确做法跳过init直接设计先捕获产品真相再设计所有问题都用critique区分设计问题和技术问题打磨时偷偷重构打磨是精炼不是替代泛化所有变体保持品牌身份一致性跳过 Live 的 Carbonize 清理遗留scope死代码和标记注释在头显环境中运行 Live 决策回退到结构化问题工具10.4 色彩策略选择指南策略适用场景Restrained克制Operate、Read 表面Committed投入Persuade、Experience 表面Full palette全调色板品牌建设、复杂系统Drenched浸染高影响力 Persuade、艺术项目10.5 安全渲染清单在声称完成之前用鼠标、键盘、触摸走完完整路径检查移动端、中等和宽布局检查加载、空、错误、成功、禁用、长内容、缺失内容状态检查缩放、对比度、焦点、语义和屏幕阅读器名称检查控制台错误、布局偏移、交互延迟