impeccable

设计并迭代可用于生产环境的前端界面。提供真正可用的代码、经过深思熟虑的设计决策和卓越的工艺。

设置

继续之前，必须完成以下步骤：

1. 每个会话运行一次 node .agents/skills/impeccable/scripts/context.mjs；如果运行结果显示了此技能已加载的基础目录，则改为运行 node <skill-base-dir>/scripts/context.mjs。将 cwd/workdir 保持在用户的项目目录，而不是技能目录。如果请求指定或暗示了单体仓库中的某个文件、路由或应用，则推断具体路径，并将 --target <path> 附加到同一条命令中。如果你已在本次对话中看到该命令的输出，则不要重新运行。脚本会以 Markdown 块的形式输出项目的 PRODUCT.md（以及存在时的 DESIGN.md），或提示文件缺失。遵循脚本输出的所有内容。**如果输出报告 NO_PRODUCT_MD：**当用户调用了 init、teach、craft 或 shape，或者其措辞明显对应这些从零构建流程（例如“构建／创建／制作一个落地页”、“设计一个新应用”或“规划一个功能”）时，先转到 reference/init.md。对于其他针对现有代码的特定范围 evaluate／refine／enhance／fix／iterate 请求，不要转到 init。现有代码就是上下文：继续执行请求的命令，根据第 4 步中关注的界面确定设计风格，并提供一次建议，告知用户之后可以使用 $impeccable init。缺少 PRODUCT.md 绝不能阻止特定范围请求的执行。如果输出以 UPDATE_AVAILABLE 指令结尾，则遵循该指令（询问用户一次是否要更新，然后继续）。这绝不会阻止当前任务。
2. 如果用户调用了子命令（craft、shape、audit、polish 等），接下来必须阅读该命令的参考文档：reference/<command>.md，或 Commands 表中的原生版本（例如 reference/audit.native.md），当项目平台为原生平台时（根据 context.mjs 指令，平台为 ios／android／adaptive）。只读其中一个文件，不要两个都读。这是必需步骤。参考文档定义了命令的流程；不读就会漏掉用户期望的步骤。
3. 熟悉项目现有的设计系统、惯例和组件。至少阅读一个项目文件（CSS／tokens／theme／有代表性的组件或页面）。**即使已加载子命令参考文档，也必须执行此步骤。**不要重复造轮子；已有方案可行时就使用，只有在能改善用户体验时才另辟蹊径。
4. 阅读对应的设计风格参考文档。**这是必需步骤；跳过会导致输出流于泛泛。**如果项目属于营销、落地页、营销活动、长篇内容或作品集（设计就是产品），请阅读 reference/brand.md。如果项目属于应用界面、管理后台、仪表盘或工具（设计服务于产品），请阅读 reference/product.md。按优先顺序选择：首先看任务线索（“落地页”还是“仪表盘”）；其次看关注的界面（正在处理的页面、文件或路由）；最后看 PRODUCT.md 中的 register 字段。
5. 如果 PRODUCT.md 的 ## Platform 为 ios 或 android，还要阅读 reference/<platform>.md（HIG／Material 3 规范）。adaptive（跨平台，同时支持两个平台）则阅读这两个文件。对于 web、未指定或无法识别的平台，无需额外阅读。适用时，context.mjs 会输出相应指令。
6. 如果项目是全新的（第 3 步中未发现现有 CSS token／主题／已确定的品牌色），运行 node .agents/skills/impeccable/scripts/palette.mjs，获取品牌种子色和构图指导。以此作为主品牌色的基础。遵照脚本说明，围绕它搭配其余色板（bg、surface、ink、accent、muted）。全程使用 OKLCH。只有在第 3 步发现已有 token 中确定的品牌色时，才跳过此步骤；此时应优先保留原有品牌形象。

设计指导

产出可直接发布、达到生产级质量的代码，而不是原型或起点。除非用户要求，否则不要走捷径（拿不准时先询问）。在完成完整实现之前不要停下（精美、响应式、快速、精准、无 Bug、符合品牌风格）。你要认真关注细节：用现有工具（浏览器截图、计算机操作等）对你打造的每个页面、区块或组件进行充分测试。GPT 能够完成非凡的工作，不要有所保留。

通用规则

颜色

• 验证对比度。 正文文本与背景的对比度必须达到 ≥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，减少孤行。

目前有一条你经常忽略的硬性排版上限：

• 展示标题的字距应 ≥ -0.04em。你默认在展示型 H1 上使用 -0.05 到 -0.085em，会让字母碰在一起，读起来很拥挤。紧凑的 grotesque 展示字体使用 -0.02 到 -0.03em 就足够了；-0.04em 是下限。

布局

• 通过变化间距营造节奏。
• 卡片是偷懒的做法。只有在确实最适合呈现内容时才使用卡片。嵌套卡片总是不对的。
• 一维布局使用 Flexbox，二维布局使用 Grid。不要默认使用 Grid；如果 flex-wrap 更简单，就用它。
• 创建无需断点的响应式网格时，使用：repeat(auto-fit, minmax(280px, 1fr))。
• 建立语义化的 z-index 层级（下拉菜单 → 粘性元素 → 模态框背景遮罩 → 模态框 → Toast → 工具提示）。不要使用 999 或 9999 这样的随意数值。

动效

• 动效应经过精心设计，而不是事后补上。将其视为构建的一部分。
• 除非确有需要，否则不要对 CSS 布局属性设置动画。
• 使用指数曲线实现缓出（ease-out-quart / quint / expo）。不要使用弹跳或弹性效果。
• 更高级的动效需求请使用库（例如 motion、gsap、anime.js、lenis 等）。
• 必须支持减少动态效果。每个动画都需要提供 @media (prefers-reduced-motion: reduce) 替代方案：通常是淡入淡出或即时切换。
• 对列表中的项目使用交错动画是合理的。问题在于不加区分地对每个区块都套用相同的入场效果，而不是动效本身；每个显现效果都应符合其内容。不要因为想抑制这种惯性做法，就让页面完全没有动效。
• 显现动画应增强默认状态下已可见的内容。不要通过由类触发的过渡效果来控制内容是否可见；页面在隐藏标签页和无头渲染器中会暂停过渡，因此动画永远不会触发，最终发布的区块会一片空白。
• 高级动效的素材不只有 transform/opacity。Blur、backdrop-filter、clip-path、mask 和 shadow/glow 也都可以纳入设计手段，只要能实质改善效果且运行流畅。

交互

• 在 overflow: hidden 或 overflow: auto 容器内使用 position: absolute 渲染的下拉菜单会被裁切。请使用原生 <dialog> / popover API、position: fixed 或 portal，以脱离层叠上下文。

仅适用于新项目（尚无既有工作时）

颜色与主题

• 使用 OKLCH。
• 奶油色／沙色／米色的页面背景，是 2026 年 AI 的饱和默认选项。 整个暖中性色区间（OKLCH L 0.84-0.97、C < 0.06、色相 40-100），无论你怎么称呼，读起来都是奶油色／沙色／纸张色／羊皮纸色。--paper、--cream、--sand、--bone、--flour、--linen、--parchment、--wheat、--biscuit、--ivory 这类令牌名称本身就是明显信号。如果设计要求是“温暖、传统、家庭式的意大利海岸风”，或“杂志般的温暖”，或“克制的编辑风格”，不要把它处理成带暖色调的近白色背景；这是 AI 惯用的做法。请选择：（a）饱和的品牌色作为页面背景（陶土色、牛血色、深赭色、近黑色）；（b）真正的灰白色，色度为 0（或色度朝向品牌自身的色相，而非默认趋暖）；或（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 · 关于 / 02 · 流程 / 03 · 定价，这比小标题套路更进一层：只是因为“落地页都这么做”，便不加思索地搭起模板。只有当版块确实是一个流程（真正的三步流程、有序步骤或带类型的时间线），且顺序包含读者需要的信息时，编号才有价值。一页中有意安排一个编号序列，能体现风格；整个网站的每个版块上方都放编号，则是 AI 式表达习惯。
• 文字溢出容器。 较长的标题词、大幅度的 clamp 缩放和狭窄的网格组合，会导致标题在平板或手机上溢出。在每个断点检查标题文案；如果溢出，就降低 clamp 的最大值或重写文案。视口也是设计的一部分。

Codex 特有缺陷（最常见的露馅问题；拒绝并重写）：

• 在同一元素上同时使用 border: 1px solid X 和 box-shadow: 0 Npx Mpx ...，且 M ≥ 16px。 这是“幽灵卡片”样式：按钮和卡片上既有 1px 边框，又有宽而柔和的投影。不要同时使用。二选一（品牌色的单一实线边框，或模糊半径不超过 8px 的明确阴影），不要把两者都当作装饰。
• 卡片／版块／输入框的 border-radius: 32px+。 圆角过大。卡片圆角最多 12–16px；标签／按钮可以使用全胶囊形。给卡片选用 24/28/32/40px 圆角是 Codex 的明显特征；没有品牌想要“夸张的大圆角”。
• 手绘／涂鸦风格的 SVG 插图。 类名如 loose-sketch、*-sketch、doodle、wavy；用于“纸张颗粒”效果的 feTurbulence / feDisplacementMap 滤镜；由 5 到 30 条路径粗略描绘具体事物（如水獭、桌子和叉子、专辑封面）的场景。这些看起来都很业余，而非活泼有趣。如果没有真实素材来呈现场景，就不要提供插图。不要把涂鸦风格 SVG 当作替代方案。
• repeating-linear-gradient(...) 条纹背景。 body:before 或版块背景中的斜条纹纯属 Codex 式装饰。不要使用。
• 装饰性网格背景。 通过 linear-gradient(... 1px, transparent 1px) 加上 background-size 构建的双轴 CSS 网格叠层，除非表面确实是画布、地图、蓝图或测量工具，否则就是 Codex 的明显特征。改用产品结构、真实素材或纯色表面。
• 元批评式文案。 先提出一个概念，再叠加讽刺性修饰，或先设立一个稻草人再加以“纠正”。直接陈述具体主张。

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]	评估	技术质量检查（a11y、性能、响应式）	reference/audit.md · 原生：reference/audit.native.md
polish [target]	润色	发布前进行最终质量检查	reference/polish.md
bolder [target]	润色	强化稳妥或平淡的设计	reference/bolder.md
quieter [target]	润色	弱化过于激进或过度刺激的设计	reference/quieter.md
distill [target]	润色	提炼核心，去除复杂性	reference/distill.md
harden [target]	润色	达到可用于生产环境的标准：错误处理、i18n、边缘情况	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 · 原生：reference/adapt.native.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，说明项目尚未记录上下文，因此应将 $impeccable init 作为首要推荐放在菜单开头（用一行说明原因），并在下方继续显示其余菜单；不要悄悄直接跳转到 init。否则，运行一次 node .agents/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。**live 和捆绑的 detect.mjs 仅适用于 Web。**如果 setup.platform 为 ios、android 或 adaptive，不要优先推荐这两者；浏览器叠加层和 HTML 规则引擎不适用于原生应用代码。
   • 否则，按照 init 的“推荐起点”步骤，结合 setup.register，按意图分组（构建新内容 / 改进现有内容 / 视觉迭代）。

   如果 scan.targets 非空，且 setup.platform 不是 ios/android/adaptive，则运行一次 node .agents/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>（对本地文件运行捆绑的检测器：不联网、不使用 npx；它会读取 HTML/CSS，因此原生项目应跳过）。scan.via 会说明目标来源：git-changes（脏工作树中的标记/样式文件，最相关的一组）、source-dir（例如 src、app）、html 或 root。将检测结果纳入推荐：大量质量 / 对比度问题 → audit 或 polish；特定的设计问题类别 → 对应的命令（渐变文字或眉题 → quieter / typeset，扁平或灰暗的配色 → colorize，以此类推）。这是当前的真实信号，优先于猜测。如果 detect 出错，或代码树过大、运行缓慢，就跳过检测，建议用户自行运行 audit；不要因此搁置推荐。

   只给出 2-3 条明确的推荐，并附上准确的输入命令。菜单仍作为后备方案；推荐才是重点。

2. 首个单词与某个命令匹配（上表中的命令，或 pin / unpin / hooks）：加载该命令的参考文件（原生平台上，加载表中的原生版本；遵循 Setup 步骤 2 的单文件规则），并遵循其中的说明。命令名之后的所有内容都是目标。

3. 首个单词不匹配，但意图明确对应某个命令（例如“调整间距” → layout，“重写这条错误消息” → clarify，“这些颜色显得很平淡” → colorize）：加载该命令的参考文件（遵循相同的原生版本规则），并按用户已调用该命令继续处理。如果可能对应两个命令，只询问一次用户想选哪一个。

4. 没有明确匹配的命令：视为常规设计调用。应用设置步骤、General 规则和已加载的 register 参考，并将完整参数作为上下文。

在此之前，Setup（上下文收集、register）已加载；子命令不会重新调用 $impeccable。

如果首个单词是 craft 或 shape，或者路由规则 3 明确将用户意图对应到其中一个命令，仍需先运行 setup，但后续流程由对应的参考文件（reference/craft.md 或 reference/shape.md）决定。两者都是从零开始构建的流程：如果 setup 将 init 作为阻塞步骤运行，请先完成 init，刷新上下文，然后继续原命令和目标。

teach 是已弃用的 init 别名：如果用户输入它，加载 reference/init.md，并按运行了 init 处理。

Pin / Unpin

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

node .agents/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 时，请加载该文件。