impeccable

设计和迭代生产级前端界面。真实的可用代码，经过深思熟虑的设计选择，卓越的工艺。

设置

在继续之前，你必须执行以下步骤：

1. 每个会话运行一次 node .claude/skills/impeccable/scripts/context.mjs。如果你已经在本对话中看到过它的输出，则不要重新运行。该脚本要么将项目的 PRODUCT.md（以及存在的 DESIGN.md）作为 markdown 块打印出来，要么告诉你它缺失。按照它打印的内容操作。如果它报告 NO_PRODUCT_MD，则停止并在执行任何其他操作之前遵循 reference/init.md。 如果输出以 UPDATE_AVAILABLE 指令结尾，则遵循它（询问用户一次是否更新，然后继续）。它永远不会阻塞当前任务。
2. 如果用户调用了子命令（craft、shape、audit、polish……），你接下来必须阅读 reference/<command>.md。这是非可选的。该参考定义了命令的流程；没有它，你将跳过用户期望的步骤。
3. 熟悉代码中任何现有的设计系统、约定和组件。至少阅读一个项目文件（CSS / 令牌 / 主题 / 一个代表性组件或页面）。即使你在步骤2中加载了子命令参考，这也是必需的。 不要重新发明轮子；在有效时使用已有的东西，在UX胜出时进行扩展。
4. 阅读匹配的注册参考。这是非可选的；跳过它会产生通用输出。 如果项目是营销、落地页、活动、长文内容或作品集（设计即产品），阅读 reference/brand.md。如果是应用UI、管理后台、仪表盘或工具（设计服务于产品），阅读 reference/product.md。按首次匹配选择：（1）任务提示（“落地页” vs “仪表盘”）；（2）焦点表面（正在处理的页面、文件或路由）；（3）PRODUCT.md 中的 register 字段。
5. 如果项目是全新的（在步骤3中未找到现有的CSS令牌/主题/已提交的品牌颜色），运行 node .claude/skills/impeccable/scripts/palette.mjs 以接收品牌种子颜色和构图指导。这是你主品牌颜色的锚点。根据脚本的说明，围绕它组成调色板的其余部分（背景、表面、文字、强调色、柔和色）。全程使用 OKLCH。仅当步骤3在现有令牌中找到了已提交的品牌颜色时跳过此步骤；在这种情况下，保持身份优先。

设计指导

生成可交付的生产级代码，而不是原型或起点。除非用户要求，否则不要走捷径（如有疑问，请询问）。不要停止，直到完成完整的实现（美观、响应式、快速、精确、无错误、符合品牌）。你认真对待细节：每个页面、部分或组件都使用可用的工具（浏览器截图、计算机使用等）进行实战测试。Claude 能够完成非凡的工作。不要保留。

通用规则

颜色

• 验证对比度。 正文文本必须达到 ≥4.5:1 与其背景的对比度；大文本（≥18px 或加粗 ≥14px）需要 ≥3:1。占位符文本需要相同的 4.5:1，而不是默认的浅灰色。最常见的失败：在接近白色的浅色背景上的浅灰色正文文本。如果对比度接近，将正文颜色向色阶的深色端移动；浅灰色“为了优雅”是AI设计难以阅读的最大原因。
• 彩色背景上的灰色文本看起来褪色。使用背景本身色调的更深色，或文本颜色的透明度。

排版

• 将正文行长度限制在 65–75ch。
• 不要搭配相似但不相同的字体（两种几何无衬线体，两种人文无衬线体）。在对比轴上搭配（衬线 + 无衬线，几何 + 人文）或使用同一字体的多个字重。
• 主标题/展示标题上限：clamp() 最大值 ≤ 6rem（约96px）。超过此值，页面在喊叫，而不是在设计。
• 展示标题字母间距下限：≥ -0.04em。更紧会导致字母粘连；局促，而不是“设计”。
• 在 h1–h3 上使用 text-wrap: balance 以实现均匀的行长；在长散文中使用 text-wrap: pretty 以减少孤行。

布局

• 变化间距以创造节奏。
• 卡片是懒惰的答案。仅在它们确实是最佳交互方式时使用。嵌套卡片总是错误的。
• 一维使用 Flexbox，二维使用 Grid。当 flex-wrap 更简单时，不要默认使用 Grid。
• 对于无断点的响应式网格：repeat(auto-fit, minmax(280px, 1fr))。
• 构建语义化的 z-index 层级（下拉菜单 → 粘性元素 → 模态背景 → 模态框 → 提示 → 工具提示）。永远不要使用像 999 或 9999 这样的任意值。

动效

• 动效应有目的性，而不是事后才考虑。将其视为构建的一部分。
• 除非确实需要，否则不要动画化 CSS 布局属性。
• 使用指数曲线缓出（ease-out-quart / quint / expo）。不要弹跳或弹性效果。
• 对于更高级的动效需求，使用库（例如 motion、gsap、anime.js、lenis 等）。
• 减少动效不是可选项。每个动画都需要一个 @media (prefers-reduced-motion: reduce) 替代方案：通常是淡入淡出或即时过渡。
• 在一个列表中错开项目是合理的。标志是统一的反射（每个部分应用相同的入场效果），而不是动效本身；每个揭示应适合它所揭示的内容。抑制反射绝不是发布一个完全没有动效的页面的理由。
• 揭示动画必须增强已经可见的默认状态。不要将内容可见性依赖于类触发的过渡；过渡在隐藏标签页和无头渲染器上暂停，因此揭示永远不会触发，部分内容以空白形式呈现。
• 高级动效素材不仅仅是 transform/opacity。模糊、backdrop-filter、clip-path、mask 和阴影/发光也是调色板的一部分，当它们实质性地改善效果并保持流畅时。

交互

• 使用 position: absolute 渲染的下拉菜单，如果放在 overflow: hidden 或 overflow: auto 容器内，将被裁剪。使用原生 <dialog> / popover API、position: fixed 或 portal 来逃逸堆叠上下文。

仅限新项目（当没有先前工作时）

颜色与主题

• 使用 OKLCH。
• 奶油色/沙色/米色正文背景是2026年饱和的AI默认值。 整个暖中性色带（OKLCH L 0.84-0.97, C < 0.06, hue 40-100）无论你叫什么名字，都读作奶油色/沙色/纸色/羊皮纸。像 --paper、--cream、--sand、--bone、--flour、--linen、--parchment、--wheat、--biscuit、--ivory 这样的令牌名称本身就是标志。如果需求是“温暖、传统、家庭-海岸-意大利”或“杂志温暖”或“编辑克制”，不要将其转化为接近白色的暖色调背景；那是AI的做法。选择：（a）饱和的品牌颜色作为正文（赤陶色、牛血色、深赭色、近黑色），（b）色度为零的真正米白色（或色度朝向品牌自己的色调，而不是默认的暖色），或（c）明显属于品牌自己的较深中间色调中性色。品牌中的“温暖”由强调色 + 排版 + 图像承载，而不是由正文背景承载。
• 着色中性色：向品牌色调添加 0.005–0.015 色度。不要默认向暖色或冷色着色，“因为品牌感觉那样”；那是跨项目单一文化的做法。
• 选择主题时：深色与浅色永远不是默认值。不是深色“因为工具看起来酷炫深色”。不是浅色“为了安全”。在选择之前，写一句物理场景的描述：谁使用这个，在哪里，在什么环境光下，在什么情绪下。如果句子没有强制答案，说明不够具体。添加细节直到它强制答案。
• 在选择颜色之前，先选择颜色策略。承诺轴上的四个步骤：
  • 克制：着色中性色 + 一个强调色 ≤10%。产品默认；品牌极简主义。
  • 承诺：一种饱和颜色承载 30–60% 的表面。身份驱动页面的品牌默认。
  • 完整调色板：3–4 个命名角色，每个都有意使用。品牌活动；产品数据可视化。
  • 浸透：表面本身就是颜色。品牌英雄页、活动页。

绝对禁止

匹配并拒绝。如果你即将编写以下任何内容，请用不同的结构重写该元素。

• 侧条纹边框。 在卡片、列表项、标注或警告上使用大于 1px 的 border-left 或 border-right 作为彩色强调。永远不是有意的。用完整边框、背景色调、前导数字/图标或什么都不用重写。
• 渐变文本。 background-clip: text 与渐变背景结合。装饰性，从未有意义。使用单一纯色。通过字重或大小强调。
• 默认玻璃态。 装饰性地使用模糊和玻璃卡片。罕见且有目的，或不用。
• 英雄指标模板。 大数字、小标签、支持统计、渐变强调。SaaS 陈词滥调。
• 相同的卡片网格。 相同大小的卡片，带有图标 + 标题 + 文本，无限重复。
• 每个部分上方的小写大写跟踪眉毛。 2023 时代的踢脚线（小写大写文本，宽跟踪，“关于”“流程”“定价”在每个标题上方）现在是饱和的 AI 脚手架；无论需求如何，它在 55-95% 的生成中出现，这是标志的定义。一个命名的踢脚线作为有意的品牌系统是声音；每个部分上的眉毛是 AI 语法。选择不同的节奏。
• 默认脚手架的数字部分标记（01 / 02 / 03）。 在每个部分上方放置 01 · About / 02 · Process / 03 · Pricing 是眉毛比喻更深一层：因为“落地页这样做”而使用它，并且你通过反射搭建脚手架。数字只有在部分实际上是序列（真正的三步流程、有序流程、类型化时间线）并且顺序携带读者需要的信息时才应出现。一个页面上一个有意编号的序列是声音；整个网站上每个部分的编号眉毛是 AI 语法。
• 文本溢出其容器。 长标题词加上大的 clamp 比例加上窄网格导致平板/手机上的标题溢出。在每个断点测试标题副本；如果溢出，减少 clamp 最大值或重写副本。视口是设计的一部分。

AI 垃圾测试

如果有人看到这个界面能毫无疑问地说“AI 做的”，那就失败了。跨注册失败是上面的绝对禁止。注册特定失败存在于每个参考中。

类别反射检查。 在两个高度运行；第二个捕获第一个遗漏的。

• 一阶： 如果有人仅从类别就能猜出主题 + 调色板，那就是第一个训练数据反射。重写场景句子和颜色策略，直到答案从领域来看不明显。
• 二阶： 如果有人从类别加反参考（“不是 SaaS 奶油色的 AI 工作流工具 → 编辑排版”、“不是海军蓝和金色的金融科技 → 终端原生深色模式”）就能猜出美学家族，那就是更深一层的陷阱。第一个反射被避免了；第二个没有。重写直到两个答案都不明显。品牌注册的反射拒绝美学通道列表捕获了当前饱和的家族。

命令

命令	类别	描述	参考
craft [feature]	构建	塑造，然后端到端构建一个功能	reference/craft.md
shape [feature]	构建	在编写代码之前规划 UX/UI	reference/shape.md
init	构建	设置项目上下文：PRODUCT.md、DESIGN.md、实时配置、下一步	reference/init.md
document	构建	从现有项目代码生成 DESIGN.md	reference/document.md
extract [target]	构建	将可复用令牌和组件提取到设计系统中	reference/extract.md
critique [target]	评估	带有启发式评分的 UX 设计评审	reference/critique.md
audit [target]	评估	技术质量检查（可访问性、性能、响应式）	reference/audit.md
polish [target]	优化	发布前的最终质量检查	reference/polish.md
bolder [target]	优化	放大安全或平淡的设计	reference/bolder.md
quieter [target]	优化	调低激进或过度刺激的设计	reference/quieter.md
distill [target]	优化	剥离到本质，移除复杂性	reference/distill.md
harden [target]	优化	生产就绪：错误、国际化、边界情况	reference/harden.md
onboard [target]	优化	设计首次运行流程、空状态、激活	reference/onboard.md
animate [target]	增强	添加有目的的动画和动效	reference/animate.md
colorize [target]	增强	为单色 UI 添加战略性颜色	reference/colorize.md
typeset [target]	增强	改进排版层次和字体	reference/typeset.md
layout [target]	增强	修复间距、节奏和视觉层次	reference/layout.md
delight [target]	增强	添加个性和令人难忘的点缀	reference/delight.md
overdrive [target]	增强	超越常规限制	reference/overdrive.md
clarify [target]	修复	改进 UX 文案、标签和错误消息	reference/clarify.md
adapt [target]	修复	适配不同设备和屏幕尺寸	reference/adapt.md
optimize [target]	修复	诊断并修复 UI 性能	reference/optimize.md
live	迭代	视觉变体模式：在浏览器中选择元素，生成替代方案	reference/live.md

加上三个管理命令：pin <command>、unpin <command> 和 hooks <on|off|status|...>，详见下文。

路由规则

1. 无参数：用户在问“我该做什么？”使菜单具有上下文感知能力，而不是静态的。设置已经运行了 context.mjs；如果它报告了 NO_PRODUCT_MD，你已经处于初始化（设置）中，所以完成它并跳过此步骤。否则运行 node .claude/skills/impeccable/scripts/context-signals.mjs 一次并读取其 JSON，然后以 2-3 个最高价值的下一步命令 开头，每个命令附带一行从信号中提取的理由，然后是完整菜单（上表，按类别分组）。永远不要自动运行命令；推荐是用户确认的建议。

   推理信号；没有需要遵守的分数：

   • setup.hasDesign 为 false 而 setup.hasCode 为 true → document（捕获视觉系统）。
   • critique.latest 为 null → 项目从未被评审过；对于已设置且有真实表面的项目，提供 /impeccable critique <surface> 是一个强默认。
   • critique.latest 具有低 score 或非零 p0 / p1 → polish（它将那个快照读作待办事项），或者如果快照看起来过时则重新运行 critique。
   • git.changedFiles 指向一个表面 → 将 audit 或 polish 的范围限定到这些文件，并命名它们。
   • devServer.running 为 true → live 可用于浏览器内迭代；如果为 false，不要以 live 开头。
   • 否则按意图分组，完全按照 init 的“推荐起点”步骤（构建新内容 / 改进已有内容 / 视觉迭代），并根据 setup.register 定制。

   如果 scan.targets 非空，运行 node .claude/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces> 一次（捆绑的检测器针对本地文件：无网络，无 npx）。scan.via 告诉你它们是什么：git-changes（脏树中的标记/样式文件，最相关的集合）、source-dir（例如 src、app）、html 或 root。将命中结果纳入你的选择：许多质量/对比度命中 → audit 或 polish；特定的垃圾家族 → 匹配的命令（渐变文本或眉毛 → quieter / typeset，平坦或灰色调色板 → colorize，等等）。这是一个真实的、当前的信号，优于猜测。如果检测出错或树很大且慢，跳过它并建议用户自己运行 audit；永远不要因此阻塞建议。

   保持 2-3 个有针对性的选择，并附上确切的命令输入。菜单仍然是后备；推荐是主导。

2. 第一个词匹配命令（上表或 pin / unpin / hooks）：加载其参考文件并遵循其指令。命令名称之后的所有内容都是目标。

3. 第一个词不匹配，但意图明显映射到一个命令（例如“修复间距” → layout，“重写此错误消息” → clarify，“颜色感觉平淡” → colorize）：加载该命令的参考并像被调用一样继续。如果两个命令都可能适合，询问一次哪个。

4. 没有明确的命令匹配：一般设计调用。应用设置步骤、通用规则和加载的注册参考，将完整参数作为上下文。

设置（上下文收集、注册）此时已加载；子命令不会重新调用 /impeccable。

如果第一个词是 craft，设置仍然首先运行，但 reference/craft.md 拥有流程的其余部分。如果设置将 init 作为阻塞项调用，完成 init，刷新上下文，然后恢复原始命令和目标。

teach 是 init 的已弃用别名：如果用户输入它，加载 reference/init.md 并像他们运行了 init 一样继续。

Pin / Unpin

Pin 创建一个独立快捷方式，使 /<command> 直接调用 /impeccable <command>。Unpin 移除它。脚本写入项目中存在的每个 harness 目录。

node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>

有效的 <command> 是上表中的任何命令。简洁地报告脚本的结果。成功时确认新快捷方式，出错时逐字传递 stderr。

Hooks

/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> 管理此项目的设计检测器钩子。钩子在直接 UI 文件编辑后自动运行检测器，并将发现作为系统提醒呈现。完整流程在 reference/hooks.md 中；当用户使用任何参数调用 /impeccable hooks 时加载它。