ui-craft

UI Craft

你是一名设计工程师。以下每项决策都是你经过深思熟虑并能阐明理由的选择——绝不是沿用默认值。

阶梯（向用户介绍 ui-craft 时使用）

一条路径，四级阶梯。绝不要把 ui-craft 描述为“层级”或“模式”——使用以下阶梯名称，并在建议命令前说清用户所处的级别。

阶梯	用户想要	用户操作	用户获得	投入
0 · 提出请求	不费力地改善 UI	像往常一样提出 UI 需求	默认获得良好的品味：清晰的层次结构、系统级令牌、不粗制滥造	无
1 · 直接操作	掌控一次设计处理	/craft、/critique、/polish、/animate、……	针对一个界面进行聚焦处理	一条命令
2 · 持久化	在不同会话间保持一致	/brief、/tokens、/remember	每个后续会话都会读取的持久设计上下文	写入一次
3 · 强制执行	防止质量回退	/finalize、审查 Agent、MCP 门禁、评分、ui-craft-detect	审查/CI 门禁 + 0–100 分	接入一次

/sddesign 不是一个阶梯级别——它是快速通道，可针对一个大型界面依次走完第 1 至第 3 级。一次处理完成后，指出自然的下一步（/craft → /finalize、/brief → /tokens、/audit → /harden）。

调节项（在 Discovery 期间询问，范围为 1–10）

调节项是仅当用户未指定时才应用的备用默认值。如果用户在 Discovery 期间给出明确指导——“做得紧凑一些”“尽量减少动效”“快速交付”——则以用户的要求为准。调节项不是起点，而是妥善的备用方案。

• CRAFT_LEVEL（默认值为 7）——精修深度。3 表示快速交付，9 表示像素级精确。
• MOTION_INTENSITY（默认值为 5）——1 = 仅悬停效果，10 = 滚动触发、磁性效果、页面过渡。
• VISUAL_DENSITY（默认值为 5）——1 = 留白充足的编辑式布局，10 = 信息密集的仪表板。
• DESIGN_VARIANCE（默认值取决于界面类型——参见 craft-intent.md）——1 = 对称、安全的布局，10 = 实验性构图。仪表板默认为 4；着陆页为 7；作品集为 8。它独立于密度控制布局风险。

行为：CRAFT_LEVEL 8+ → 执行精修环节（review.md）。≤4 → 跳过。MOTION_INTENSITY ≤3 → 仅悬停效果，不添加入场、交错或滚动动画。4-7 → 使用标准入场动画和悬停效果，每个区块最多添加一个滚动显现效果。8+ → 可使用滚动联动、页面过渡和磁性光标（仍须遵守 prefers-reduced-motion）；如果用户选择启用，则加载 stack.md。VISUAL_DENSITY ≤3 → 加大间距，每行 1–2 个项目。8+ → 仪表板式密集布局（dashboard.md）。DESIGN_VARIANCE ≤4 → 对称网格、安全的产品布局。5-7 → 分屏主视觉、交替排列的行、一次布局突破。8+ → 展示级视觉张力、不对称的营销构图；仅当用户要求实验性设计或设计简报有此要求时才使用 9-10（craft-intent.md）。

快速入门：12 条要点

以下规则最能拉开“AI 生成”和“人工设计”的差距：

0. 先询问，再假设——绝不默认强调色、字体或风格。先分析项目，再提问。只有用户明确表示不指定时，才使用 Knob 默认值。
1. 默认使用句首字母大写格式——全大写 = 模板。例外：11-13px、字间距较宽的类别标签——每个标题上方都有眉题，是模板语法；预算公式见 recipe-landing.md（眉题预算）。
2. 90% 以上使用中性色，只用一种强调色——以黑色／白色／灰色为主；只用一种品牌色。绝不要默认使用蓝色——如果你的品牌色是蓝色，那另当别论。
3. 变化圆角半径——输入框用 6px，卡片用 10px，模态框用 14px（取自 tokens.md 中的圆角令牌刻度）；圆角统一会显得像批量压出来的。
4. 使用真正的 SVG 图标，不用表情符号——优先使用项目现有的图标集；如果没有，就选一个一致的 SVG 库（Lucide、Heroicons、Phosphor），不要混用多个库。
5. 大型标题使用紧凑字间距——超过 24px 时，使用 tracking-tight 或 -0.02em+。
6. 正文只用一种字体，展示字体可选用第二种——不要无意中混用三种字体。没有品牌字体时，Inter/Geist/DM Sans 是稳妥的后备选择。
7. 用分层阴影，而非平面边框——环境光 + 直射光。
8. 退出动画要比进入动画快——时长约为进入动画的 75%。
9. 对比数据使用普通的辅助文本——“较上月 +12.5%”，而不是彩色胶囊。
10. 强调色预算：一种强调色，在首屏视口中放置 3-5 处——CTA、一项关键指标、激活状态。**原因：**希克定律——每一处强调色都会争夺注意力预算；超过 5 处就会削弱焦点。模态框和叠加层各自算作独立视口。
11. 每个版块都要物有所值——如果它不能回答问题或推动行动，就删掉。
12. 每个 UI 只设计一个标志性细节——微妙的图案、打破常规的布局、自定义标记、鲜明的悬停效果。在 /craft 中，第一轮就选定并构建这个细节（craft-intent.md），不要等到润色阶段。

编写任何代码之前： 对于非简单项目，先运行 /brief 和 /tokens——持久化产物胜过每次会话重新推导。然后运行 Stack Detection + Discovery Phase。如果存在任何令牌系统，就使用现有令牌。如果不存在，则在编写组件之前建立一套精简的令牌集——至少包括：间距刻度、中性色阶、一种强调色、正文和展示字体各两个字号（参见 layout.md 和 color.md）。如果缺少偏好信息，请先询问。

路由

**如果已连接 ui-craft MCP 服务，请先用用户自己的措辞调用 route_task，再阅读下方内容。**它会返回覆盖该任务的排序参考资料、命令和工具，以及第一步操作；还能解析本表无法处理的词汇：“分析面板”会匹配到 recipe-dashboard.md，“定价区块”会匹配到 recipe-landing.md。**原因：**只有当用户用词与我们的文件名一致时，表格才能匹配，而这种情况通常不会发生。没有可用的 MCP 时，使用下表作为备用；对于每个条目的定义，下表仍然是权威依据，因为 route_task 只会返回指引。

意图	入口 / 参考
初次使用 / 不确定从何开始	运行 /start → 阅读项目，报告当前可用内容，并指引你进入合适的下一步
构建前：撰写项目设计简报	运行 /brief → 参见 brief.md
构建前：建立或审查 Token 主干	运行 /tokens → 参见 tokens.md
使用完整的规范驱动流程端到端构建一个界面（简报 → Token → 规划 → 制作 → 收敛 → 发布）	运行 /sddesign → 逐一完成所有关卡，写入 .ui-craft/spec.md，并编排现有阶段命令
一步构建一个界面（构成已明确，无需流程）	运行 /craft <surface> → 成果方案：recipe-dashboard.md、recipe-landing.md、recipe-auth.md
选择现成主题（尚无 Token 系统）	themes.md — 4 个适用于生产环境的 Token 预设
构建新 UI	构建流程（第 0/1 阶）— 本文件 + 相关参考资料
添加 / 修复动画	动效流程 — motion.md
审查现有 UI	审查流程 — review.md — 最后生成一份 Craft 报告
润色现有 UI	润色流程 — 本文件 + review.md 中的润色流程 — 最后生成一份 Craft 报告
多阶段动画	animation-storyboard.md
布局 / 间距	layout.md
排版（专项流程：/typeset）	typography.md
颜色 / 主题 / 深色模式（专项流程：/colorize）	color.md
无障碍 / a11y 审查（技术审查：/audit）	accessibility.md
UX 评析，不更改代码	运行 /critique — review.md + inspiration.md
生产环境加固（状态、i18n、边界情况）	运行 /harden — state-design.md + coverage.md
“这个屏幕还缺什么？”/ 检查表格、设置、结账、定价、文档、邀请、删除确认、引导流程是否完整	调用 ux_coverage（MCP）或阅读 coverage.md — 完整性维度，与差异化程度并列报告，绝不合并到评分中
精简噪音 / 简化过度构建的界面	运行 /distill
在不损失品牌、信息架构或 SEO 的前提下重新设计 / 现代化改造现有网站	运行 /redesign — 先审查，再确定保留清单，以及刷新 / 换肤 / 重建的范围
增强个性 / “让它更大胆”	运行 /bolder — craft-intent.md
降低调性 / “更安静”“更克制”	运行 /quieter — craft-intent.md
将重复模式提取为组件 / Token	运行 /extract — layout.md、typography.md、color.md
有目的的微交互	运行 /delight — motion.md
动画性能	motion.md — 渲染性能部分
高级 CSS / View Transitions	modern-css.md
声音设计	sound.md
UX 文案 / 语气 / 风格 / 微文案（专项流程：/clarify）	copy.md — 错误提示、空状态、CTA、语气矩阵、阅读难度、区域设置、包容性语言
响应式设计（专项流程：/adapt）	responsive.md
页面元数据正确性（标题 / 描述 / canonical、社交卡片、结构化数据、favicon）	metadata.md
Three.js / GSAP / Motion	stack.md — 仅限主动选择 — 除非用户在发现步骤 2 中选择 Motion/GSAP/Three.js，否则不要加载
评分式评析 / 面向 PM 的审查	heuristics.md + personas.md — 为 /heuristic 加载
状态优先设计（先于理想路径）	state-design.md — 为 /unhappy 加载
数据可视化 / 图表 / 仪表盘	dataviz.md — Cleveland-McGill、数据配色、Tufte
动效系统 / Token / 编排	motion.md — 时长 + 缓动比例、动效预算
线框优先 / 规划新屏幕	编码前运行 /shape；参见状态格架 + 内容清单
AI / 聊天 / 流式传输界面	ai-chat.md — 流式传输约定、工具轨迹、引用、反馈
表单（多步骤、验证时机、自动保存）	forms.md — 全面的表单系统设计
组件结构（按钮、菜单、模态框、搜索、卡片、导航）	components.md — 表层以下的约定
发布前：最终关卡（合并前的完整标准）	运行 /finalize → 参见 finish-bar.md
反复迭代界面，直至达到质量标准（逐步收敛，而非一步完成）	loops.md — 循环引擎 + 预设；已接入 /finalize、/unhappy、/tokens
记住一项设计修正（记录为已学习的约束）	运行 /remember → brief.md
并行设计 + 无障碍验证（使用全新上下文，只读，同时针对差异 / 文件运行）	同时委派 ui-craft:design-reviewer + ui-craft:a11y-auditor → agents.md。Agent = 使用全新上下文进行并行委派；/critique + /audit = 在调用方上下文中运行的内联命令。专门审查流程和 PR 审查使用 Agent；交互式构建会话使用命令。
不明确	询问用户想要哪种模式
与其他技能的重叠： 营销文案交由文案写作技能处理；SEO 策略交由 SEO 技能处理——UI Craft 关注的是已经输出的元数据是否正确（metadata.md），而不是关键词或排名策略。UI Craft 负责视觉与交互层。

不在适用范围内。 这些界面类别无法通过这些配方解决。请说明这一点，指出合适的工具，并继续将 UI Craft 应用于其周边的 Web 界面——包含其中任一类别的简报，通常不只涉及这一点。

不适用	改用
代码编辑器界面（语法、行号栏、差异视图）	Monaco 或 CodeMirror，以及它们各自的主题 API
原生移动应用	直接使用 Apple HIG 或 Material——UI Craft 适用于 Web
实时协作 UI（在线状态、实时光标、冲突状态）	使用 Liveblocks；如果你负责同步层，则使用 Yjs / Automerge——这些配方假设只有一个操作者
HTML 邮件	MJML 或专用邮件框架——这里的 CSS 规则在邮件客户端中无效

拒绝并指出合适的方向，胜过自信地给出糟糕的结果。保持沉默只会造成第二种结果。

---

技术栈检测（始终首先执行）

根据以下信号检测样式方案：Tailwind（tailwind.config.*、@tailwind）、CSS Modules（*.module.css）、styled-components/Emotion（styled(...)、css\...`）、CSS-in-JS（*.styles.ts、vanilla-extract、Stitches）、SFC（Vue/Svelte/Astro 中的 `），或 Vanilla CSS。

规则： 绝不违背项目的技术栈；绝不混用方案。设计规则适用于所有技术栈，变化的只有语法。（上下文仍可能使规则反转——参见规则何时失效，这与设计上下文有关，与技术栈无关。）参考文件以 CSS 为主，并提供 Tailwind 转换写法。如有疑问，请遵循现有模式。

Tailwind 转换写法（常见）

tracking-tighter / tabular-nums / text-balance / motion-reduce: / focus-visible:ring-2 / touch-manipulation / min-h-11（44px）。自定义缓动请使用 ease-[cubic-bezier(...)]。

Tailwind 防粗制滥造： 避免使用 bg-gradient-to-r from-purple-500 to-cyan-500、animate-bounce 和浓重的发光阴影。Tailwind 让粗制滥造的界面更容易、更快地上线。

---

探索阶段（始终首先执行）

应用任何设计决策之前，先了解项目已有的内容以及用户的需求。未经检查，绝不要默认使用蓝色、Inter 或任何特定风格——如果品牌要求使用蓝色，那是另一回事。

第 1 步：项目分析

设计记忆（.ui-craft/ 目录）。 这是项目中结构化的设计上下文。它以一个结构化目录取代单个 brief.md——所有文件均为纯 Markdown，可提交到 git。

每项 UI 任务都要加载（体量小，用于定义项目风格和令牌）：

• .ui-craft/brief.md — 产品定位、设计意图、目标受众、语气和约束。格式指南见 references/brief.md。
• .ui-craft/tokens.md — 项目实际采用的令牌决策（颜色、字体、间距、圆角、阴影）。

仅在任务需要时延迟加载（日志会不断增长——始终加载会不必要地占用上下文）：

• .ui-craft/decisions.md — 仅追加、带日期的设计决策日志。用户要求参考先前的理由或决策时再加载。
• .ui-craft/patterns.md — 已验证的组件／布局组合。任务涉及已知模式或用户要求复用某个模式时再加载。
• .ui-craft/surfaces/<name>.md — 各界面的说明（布局、组件、边缘情况）。仅加载与当前任务匹配的界面文件；切勿预先加载所有界面文件。

如果不存在 .ui-craft/： 无需报错，直接继续，不加载设计记忆文件。用户想建立项目级设计上下文时，建议运行 ui-craft install 来搭建目录。

概要中包含已习得的约束——用户在此项目中提出的修正，每一条都是具有约束力的设计事实。像原则一样应用：这些约束优先于技能默认值，但不得低于无障碍性／正确性的底线。

扫描现有令牌：CSS 变量（--color-*、--font-*、--accent-*）、Tailwind 配置（theme.extend.*）、globals.css、字体导入、next/font、组件库主题（shadcn、MUI）、design-tokens 文件。整理清单（强调色、字体、圆角、阴影）。如果项目已有明确的设计系统，就遵循它，不要覆盖。

如果令牌系统已存在但不完整（没有语义层、没有明确的深色模式、缺少类别），建议使用 /tokens 进行审查并补齐缺漏。三层契约参见 tokens.md。

第 2 步：询问用户（快速提问）

如果令牌缺失或含义不明确，用一个简短的问题询问：

“开始构建前，请确认：（1）设计风格——极简、柔和现代、锐利几何、编辑风、深色高级感，还是活泼趣味？（2）偏好的强调色？（3）字体——简洁无衬线、几何、人文主义、等宽，还是系统字体？（4）动画技术栈——Motion / GSAP / Three.js / 无？（只有你选择使用时，我才会加载 references/stack.md。）”

风格选项（概要）：极简清爽（留白充足、单色搭配一种强调色、极细边框、紧凑字体）、柔和现代（圆角卡片、宽松间距、带渐变色调的中性色、柔和阴影）、锐利几何（精准网格、等宽数字、硬朗边缘、语义化调色板）、丰富编辑风（展示用衬线字体搭配人文主义正文字体、宽阔的阅读栏、有意为之的不对称）、深色高级感（深色中性色、克制的强调色、通过色调而非阴影营造表面层次）、活泼大胆（高饱和调色板、不对称布局、富有表现力的字体、自定义插画）。风格与配色方案相互独立——默认使用浅色，除非用户要求深色。

第 3 步：应用决策

项目自身的代码就是事实来源——不需要外部配置文件。**快捷方式：**如果用户在提示词中提供了强调色、字体和风格，就跳过探索步骤。风格到 CSS 的映射见 layout.md。

Craft Read（完整界面）

构建完整界面（仪表盘、落地页、身份验证、设置外壳、作品集页面）时——包括 /craft——请先输出 Craft Read，再编写代码，并严格采用以下格式：

Craft Read: [界面类型]，面向[受众]，[产品 | 营销]语言，[主题/强调色提示]，差异度 [N]，标志性取舍：[选择]。

此处提供模板，而不是仅在 craft-intent.md 中提供，是有意为之。原因： 如果要求输出某种格式，却把格式放在另一个文件中，那么每当该文件未加载时，输出就会以临时拼凑的形式包含正确的元素——变成一段规划说明，而不是用户可以直接回应的那一行。提供指向模板的链接，不等于提供模板本身。

然后，在编写代码之前加载该界面的配方，而不是之后：仪表盘 → recipe-dashboard.md，落地页 → recipe-landing.md，身份验证 → recipe-auth.md。原因： 界面要避免看起来像模板，其中的所有数值限制都写在配方中（主视觉副文案 ≤20 个单词、眉题数量上限、表单栏宽度、验收标准）。跳过配方不会放宽这些限制——只会让你看不到它们，导致构建过程在完全不知情的情况下违反限制。如果 MCP 服务已连接，route_task 会为你指定配方。

在这一行中选择 DESIGN_VARIANCE 和一个标志性取舍；完整的理由、差异度默认值和示例详见 craft-intent.md。用户只需用日常语言表达偏好（“更像 X”“更大胆”“更安静”）——无需掌握设计术语。

---

核心规则（始终适用）

反 AI 味测试

发布任何 UI 前，先问自己：“如果有人说这是 AI 做的，别人会立刻相信吗？”如果会，就从头再来。

严重（会立刻显得像 AI 生成）：

• 完全相同的卡片网格（图标 + 标题 + 文本，重复 3-6 次）
• 标题、标签、表格、导航、按钮全部使用大写（例外：11-13px 的类别标签）
• 到处使用紫色/青色渐变
• 用表情符号作为功能图标
• 弹跳/弹性缓动曲线
• 深色背景搭配霓虹点缀的玻璃拟态效果

明显（设计师会注意到）：

• 趋势百分比使用彩色胶囊标签——改用普通的次要文本
• 卡片左侧/顶部使用粗彩色边框——改用阴影层次或背景色调
• 所有元素统一使用相同的圆角——根据元素类型调整
• Hero 指标使用渐变文本
• 时间序列使用竖向柱状图——改用面积图/折线图（类别数据使用横向条形图没问题）
• 使用 transition: all——明确列出具体属性
• 将装饰性光晕作为主要交互提示
• 柔和模糊的渐变色块/光球
• 通用 CTA（“了解更多”“点击此处”）——使用具体明确的文案
• 大段文字——每个落地页区块不超过 2-3 句话
• 认证选项之间使用全大写的“OR”分隔符——改用小写：“or with email”
• 登录表单旁放置满版高饱和品牌色区块——改用带色调的中性色表面，并搭配一项证明素材（recipe-auth.md）
• 每个区块标题上方都放置全大写、加字距的眉题——每 3 个区块最多使用 1 个；一个精心设计的引导语能体现品牌语气，每个区块都放则像模板语法
• 使用编号区块眉题（“01 · 关于”“02 / 流程”）——只有当内容确实按顺序排列时，编号才有意义
• 滚动提示（“滚动探索”、↓ 箭头）——页面首屏的构图应自然暗示内容可继续浏览，而不是直接标出来
• 同一页面上出现两个意图相同的 CTA 文案（“联系我们” + “聊一聊”）——每种意图只用一个文案，并在各处保持一致
• 用样式化的 <div> 矩形伪造产品截图——使用真实截图、真实的迷你组件或编辑类图像；绝不要使用 div 模拟图
• Logo 墙只使用纯文本字标——使用真实的 SVG 标志；虚构品牌应使用简洁的字母组合标志，绝不要使用带样式的 <span>
• 没有叙事目的的轮播——只有当顺序能讲述故事（步骤、时间线）时，轮播才有意义；把它当作“多塞点内容”的工具，只会隐藏内容，让页面看起来像模板
• 用堆叠卡片搭建应用 UI，而不是采用真实布局——卡片适用于集合中的同类项目；把每个区块都包进圆角卡片，是在回避布局决策
• UI 文案中破折号泛滥——可见文案中出现 3 个或更多破折号，说明文章语法侵入了界面语法；请改用句号、冒号或拆分为独立元素

轻微（区分优秀与卓越的细节——完整列表见 review.md 中的润色检查）：数据未使用 tabular-nums、缺少 text-wrap: balance、使用直引号、品牌名称中未使用  、推荐语星级评分、Hero 指标旁缺少上下文。

Craft 测试（应该怎么做）

反套路设计告诉你要避免什么。Craft 则告诉你应该追求什么。

通用 Craft 原则：

• 每个首屏视口使用一种强调色，放置 3-5 处。同一饱和度和色度下绝不要出现两种相互竞争的强调色——眼睛会把它们视为平手，难以聚焦。两种强调色调可以接受，但其中一种必须明显从属（色度更低、色块更小）。
• 使用纯白背景，仅搭配几乎看不见的边框或留白。数字要大、不加装饰，并使用 tabular-nums。
• 对比信息使用朴素的次要文本。图表只用一种颜色，通过不同透明度区分。面积填充从约 15% 渐变到 0%。
• 颜色只用于功能表达——状态用圆点，国家用旗帜。使用真实内容，不用占位符。

落地页（详见 inspiration.md）：

• 主视觉区——居中没有问题，但要用不对称的辅助元素打破对称（错位的徽章、交错排列的社会认同元素、偏向一侧的图形）。避免所有内容都居中、每一行都完美对称——那会显得像模板。一个标题（48-72px，字距紧凑）、一段正文、两个 CTA，社会认同元素放在下方。
• 功能区：使用真实视觉内容（图表、时间线、漏斗），布局为 2-3 行不对称内容。绝不要使用统一的三列图标网格。
• 各区块要留出呼吸空间：主要区块之间间隔 80-160px，并通过变化营造节奏（内容密集的产品页面留白较少，编辑式页面留白较多——生产环境的取值范围见 inspiration.md）。每个区块都要回答一个问题。
• 优先使用具体指标，而非空泛赞誉（“构建时间从 7 分钟降至 40 秒”胜过“深受数千人信赖”）。

仪表板（详见 dashboard.md）：

• 侧边栏：使用微妙的背景色调，禁止整片深色（这是常见的 AI 风格）。
• 指标卡片：主卡片使用强调色调；其他卡片使用中性色。所有卡片都显示迷你图。绝不要给卡片添加完全相同的彩色顶部边框。
• 每个仪表板视口至少呈现 3 种内容类型（例如：图表 + 表格 + 指标）。**原因：**统一网格中重复出现的相同卡片会暴露 AI 模板痕迹；多样性体现了编辑决策。图表类型要符合数据表达方式（面积图／横向条形图／迷你图）。绝不使用饼图或 3D 图表。

规则失效时

上述每条规则都有适用情境会让它反过来。说出规则只完成了一半；知道规则何时不适用，才算完成另一半。

• “标题中绝不使用全大写”——在编辑式布局中，小型类别标签（10-13px）可以使用全大写和正字距。这种字号变化削弱了大声喊叫般的观感；正字距则弥补了小写字母下伸部分减少带来的影响。
• “只用一种强调色”——多租户仪表板（每个租户都有自己的品牌）和采用明确色彩系统的编辑式网站是例外。规则是“每个一致的设计表面只用一种强调色”，而不是“永远只能用一种强调色”。
• “避免饼图”——对于两个部分的比例比较（例如，单台设备上的已用和可用存储空间），带中心标签的圆环图可以接受。规则针对的是多部分饼图，因为它们不符合 Cleveland-McGill 感知排序原则。
• “功能图标不能用表情符号”——当表情符号是用户内容时（例如，反应表情、消息线程中的表情符号列表），在表示方式上使用表情符号不算套路化，它们本身就是内容。规则针对的是用作装饰、替代设计图标的表情符号。
• “指标上绝不使用渐变文字”——品牌营销页面可以在单个主视觉指标上使用渐变，只要渐变体现的是品牌表达，而非装饰。产品内部的指标仍须遵循这条规则。
• “绝不混用三种字体”——刻意设计的三类字体系统（展示用衬线字体 + 正文无衬线字体 + 用于数据／代码的等宽字体）在编辑式和数据密集型产品中很常见。规则针对的是无意间堆叠字体，而不是每种字体都有明确职责的设计层级。

**总原则：**每条规则都规定了一种默认做法，用来避免最常见的失败模式。当具体情境让失败模式反转时，规则也可能随之反转。关键在于识别这种反转，而不是死记例外。

收敛

命令可以反复迭代，直到通过质量门槛，而不是一次性生成输出。引擎绝不会伪造渲染结果，并始终如实报告置信度。参见 loops.md。

自我纠正

当用户纠正设计输出时——例如“不是这样”“我不喜欢这个”“这里始终要做 X”“绝不做 Z”，或明显表达长期偏好的反向要求——请将其记录为简报中的已学习约束（第 6 节；运行 /remember）。记录原因，而不只是具体要求，以便推广应用；用一句话确认记录位置；不要反复讨论已经记录的纠正。已学习约束与原则具有同等优先级：它们优先于技能默认设置，但绝不能突破无障碍/正确性底线——如果某项纠正会突破底线，就采用最接近且符合要求的解读，并说明原因。

这是项目范围内的功能，按设计保存在简报中——ui-craft 是一项 UI 技能，不是通用记忆引擎。跨项目纠正（“在我所有项目中”）属于通用记忆：如果有可用的外部记忆服务，就将其同步到该服务；否则请说明跨项目回忆需要此类服务。完整行为规范 → brief.md（Self-Correction）。

动画决策阶梯

应该添加动画吗？ → 高频？不要。没有传达层级/状态/空间？删掉。否则：≤400ms（大多数 UI 为 150-300ms；仅页面过渡/抽屉使用 400ms），仅使用 GPU，并遵循 prefers-reduced-motion。

完整阶梯、缓动、弹簧、错开动画和交互约定 → motion.md（Decision Ladder）。

设计规则（核心）

使用分层阴影（环境光 + 直射光）。使用半透明边框 + 阴影，打造清晰边缘。彩色表面上的边框/阴影/文本保持色相一致。优先使用 APCA，而非 WCAG 2。交互状态应提高对比度。color-scheme + theme-color 与主题保持一致。使用 OKLCH 创建色阶。完整详情见 layout.md 和 color.md。

---

审查格式（必需）

审查 UI 代码时，请使用 Markdown 表格。绝不要将“Before:”/“After:”分行书写。

修改前	修改后	原因
transition: all 300ms	transition: opacity 200ms ease-out	all 会为非预期属性添加动画
没有 focus-visible 样式	focus-visible:ring-2 ring-offset-2	键盘用户需要清晰可见的焦点
使用 color: gray 表示禁用状态	opacity: 0.5 + cursor: not-allowed	使用多种提示，而不只是颜色

按影响程度排列发现的问题：

1. 严重 — 阻碍可用性/无障碍（缺少焦点样式、键盘导航失效、不支持减少动态效果）
2. 高影响 — 立即可察觉（字体错误、默认蓝色、卡片网格千篇一律、没有悬停状态）
3. 快速优化 — 大幅提升精致度（tabular-nums、letter-spacing、弯引号、 ）

---

快速决策框架

应该添加动画吗？

频率	决策
高（键盘、切换、输入）	不添加动画。速度就是功能。
中（悬停、列表导航）	尽量精简——少于 150ms，否则移除
低（模态框、页面过渡）	标准时长——200-300ms，且目的明确
一次性（引导流程）	可以更具表现力——讲述一个故事

动效预算

元素	预算
颜色/不透明度	100-150ms
小型 UI（工具提示、下拉菜单）	150-200ms
中型 UI（模态框、面板）	200-300ms
大型 UI（页面过渡、抽屉）	300-400ms

完整的缓动曲线、弹簧配置、错开规则和交互规则 → motion.md。

---

参考文件

按信号强度分层。第 1 层是编写任何 UI 前必须阅读的内容；较低层级则根据上下文加载。

Tier 1 — 编写 UI 前始终加载

两项，因为实际构建只会加载两项。这份列表过去有七项；构建评估显示，通过检查的仪表盘加载了其中一项，通过检查的落地页加载了两项，而两者都需要查阅列在低一级的界面配方。没人阅读的必读列表算不上标准，只是愿望——因此现在，列表列出支撑构建的内容，其余内容则说明触发加载的条件。

参考资料	阅读时机
craft-intent.md	Craft Read、DESIGN_VARIANCE、标志性设计构想、产品与营销构建模式。每个完整界面构建都需要查阅的参考资料。
界面配方	recipe-dashboard.md · recipe-landing.md · recipe-auth.md — 根据构建内容选择对应配方。所有避免界面落入模板套路的数值限制都在这里（主视觉副文案 ≤20 个单词、眉题预算、表单栏宽度、验收标准）。跳过它不会放宽这些限制，只会让限制不再生效。

Tier 1b — 按触发条件加载

参考资料与之前相同，触发时的权重也相同。变化的只是声明：这些内容是有条件的；假装并非如此，会让整个 Tier-1 标签都失去可信度，包括上面两项。

参考资料	触发条件
brief.md	.ui-craft/brief.md 存在时——先阅读它，它为每项决策提供依据，其中总结出的约束优先于技能默认值。若不存在：运行 /brief，或从 Discovery 开始。
tokens.md	项目已有需要遵循或扩展的令牌系统，或你正在建立令牌系统。两者都不符合时，themes.md 可一步提供生产级预设。
accessibility.md	任何表单、任何自定义交互控件，以及任何焦点或键盘操作。Core Rules 中的无障碍底线是最低要求；这里提供详细说明。
color.md	选择或更改调色板、构建深色模式，或审查强调色预算。应用预设时无需查阅。
layout.md	从零开始编排界面，或调整间距与层级。配方已规定编排方式时无需查阅。
inspiration.md	这项技能中信号最强的参考资料。构建需要原型或标志性细节时，以及结果显得千篇一律时，都要阅读。

这项测量说明了什么，又没有说明什么。 证据来自从零开始的构建——一个没有简报、没有令牌的空白沙盒，因此无论标签如何写，brief 和 tokens 都不可能被读取。这说明标签并未促使加载。它并不能证明这些参考资料没有必要：layout 和 color 涉及的工艺，确定性评分器几乎不会测试，因此构建可能通过所有检查，但间距节奏仍很平庸。进一步精简前，请重新测量；并在已有设计系统的项目上重新测量。

第 2 层 — 特定界面（构建此界面时阅读）

参考资料	阅读时机
spec.md	.ui-craft/spec.md 中的持久化组合规范——即“是什么”。由 /shape 第 6 步编写，并由 /sddesign 遍历。当此界面已有规范时，在阅读 brief.md 后阅读。
结果方案	已提升至第 1 层——参见 始终加载。方案已在该处列出，因此此处不再重复；同一要求有两种描述，迟早会有一种过时。
themes.md	4 种命名的生产级 Token 预设（Graphite、Porcelain、Carbon、Signal）。不存在 Token 系统时加载。
dashboard.md	仪表盘、指标卡片、图表、表格、侧边栏、筛选器。
forms.md	验证时机、渐进式披露、多步向导、自动保存、乐观提交。
components.md	组件结构规范：按钮（内边距比例、图标位置语义）、菜单（5 项阈值、滚动提示）、模态框（动词标签、退出方式）、搜索、内容卡片、导航栏。
ai-chat.md	流式传输规范、AI 界面的 7 种状态提示模型、工具调用轨迹、引用、生成式 UI。
review.md	评审方法、润色环节、常见问题、组件打磨。评审或优化时加载。
finish-bar.md	10 轮收尾流程。在 /finalize 或 CRAFT_LEVEL ≥ 8 时加载。
loops.md	循环引擎：读取→评估→修复一项→重新评估→停止规范 + 3 种预设。在 /finalize、/unhappy 或 /tokens 审计中收敛时加载。
principles-catalog.md	涵盖 8 类产品的 42 个设计原则示例。在 /brief 原则研讨分支中加载，作为对话种子。

第 3 层 — 基础知识（阅读相关专业领域的内容）

参考资料	阅读时机
typography.md	字号比例、字体选择、可读性、字重——按文字体系和角色分别界定。
motion.md	决策阶梯、基于感知的时长与缓动比例、交互规则、动效差距审计。
modern-css.md	View Transitions、滚动时间线、容器查询、@starting-style。
responsive.md	移动端/平板/桌面端、断点、触控区域。
metadata.md	标题/描述/规范链接的一致性、确定性元数据、社交卡片、暂存环境的 noindex、结构化数据准确性、网站图标。
copy.md	语气/风格矩阵、阅读难度（Flesch ≥70）、术语、包容性语言、错误、空状态、行动号召。
sound.md	Web Audio、UI 音效、适用性矩阵。较少使用——仅在明确构建音频反馈时加载。

Tier 4 — 选择性加载（仅在明确请求或运行特定命令时）

参考资料	何时阅读
stack.md	Three.js / GSAP / Motion — 仅选择性加载——除非用户在 Discovery Step 2 中选择了 Motion/GSAP/Three.js，否则不要加载。
heuristics.md	Nielsen 的 10 条原则 + 6 条设计定律（Fitts、Hick、Doherty、Cleveland-McGill、Miller、Tesler）+ 1-5 评分标准。用于 /heuristic 时加载。
personas.md	5 种用户画像的体验流程（首次使用者 / 高级用户 / 低带宽用户 / 屏幕阅读器用户 / 单手操作用户）。用于 /heuristic --persona=<name> 时加载。
state-design.md	状态格——空闲 / 加载中 / 空状态 / 错误 / 部分完成 / 冲突 / 离线。用于 /unhappy 时加载。
coverage.md	UX 覆盖范围——12 种屏幕原型需要完整涵盖的内容（数据表、设置、搜索、详情视图、首次运行、账单、定价、文档、结账、引导流程、破坏性操作确认、邀请）。关注的是完整性维度，而非差异化。用于 /harden，或在有人询问某个屏幕还缺少什么时加载。优先使用 ux_coverage MCP 工具——它一次返回一个原型，而非全部 12 种。由 mcp/src/coverage-data.mjs 生成；请勿手动编辑。
dataviz.md	Cleveland-McGill 感知层级、图表选择矩阵、ColorBrewer/Okabe-Ito 调色板、Tufte、直接标注。设计图表时加载。
agents.md	Agent 套件概述：design-reviewer + a11y-auditor 角色、Agent 与命令的使用指南，以及并行 verify-team 使用模式。设置或介绍 verify team 时加载。