UI 设计
当一个Agent被要求编写一个界面时，它确实会写。但这个技能填补了界面编写之前和之后的两端空白。首先，确定这个界面的用途和它应有的外观。然后，验证所构建的东西是否真正完成了任务。
以下所有内容都遵循两条规则。在编写第一个文件之前，明确客户成果。在声称产品可以工作之前，驱动运行中的产品。
首先选择深度
| 变更类型 | 执行阶段 |
|---|---|
| 文案、颜色、单个属性 | 1, 7，然后查看结果 |
| 单个组件、单个状态 | 1, 4, 6, 7, 9 |
| 一个界面、一个表单、一个流程 | 0 到 10，简要执行 |
| 新界面，或“让它现代化” | 0 到 10 完整执行，且第3阶段需批准后才能进入第7阶段 |
| “审计这个” | 使用 ui-review。不要开始编辑 |
| “帮我找一个组件……” | 使用 ui-find |
在开始之前，用一句话说明你选择了哪个深度。只有当你所做的变更无法触及某个阶段所保护的内容时，才能跳过该阶段。
0. 预检：先阅读项目，再提问
按以下顺序阅读，并在第一个能解答问题的文件处停止：
- 项目根目录下的
DESIGN.md。一个已经存在的设计系统优先级高于本技能中的所有默认项和你自己的任何品味。 遵循它。如果当前工作涉及该文件未涵盖的内容，请将该内容添加到该文件中，而不是在样式表中凭空创造。 PRODUCT.md、README.md、.claude/、已有的需求文档。- 正在使用的技术栈、样式系统和组件库。
- 最接近的现有界面，以及覆盖它的测试。
与产品自身系统矛盾的界面是一个待发现的问题，而不是启动第三个系统的许可。
1. 设计系统
references/design-system.md 包含了格式和进入它的两条路径。
| 项目现状 | 你的操作 |
|---|---|
存在 DESIGN.md | 阅读它，遵循它，用一句话说明 |
| 代码中有真实的设计系统：设计令牌、主题文件、Tailwind 配置 | 通过从代码中读取值（而不是猜测）将其编纂到 DESIGN.md 中 |
| 有真实产品或品牌，但没有书面系统 | 从真实事物中编纂：渲染它，读取计算出的样式值，记录下来 |
| 一无所有 | 从第3阶段开始，根据用户选择的方向编写一个 |
永远不要编写一个声明了产品未使用的值的 DESIGN.md。 编纂的系统是已有内容的记录。新系统是一个提案，并且在用户选择之前都被标记为“提案”。
在基于该文件构建之前，对其进行门禁检查：
pnpm dlx @google/design.md lint DESIGN.md
这是一个真实发布的包。它能捕获损坏的令牌引用、缺少的 primary、从未定义的排版，以及任何低于 4.5:1 对比度底线的组件颜色组合。在第7阶段之前修复它报告的所有问题。
2. 客户成果
references/product-thinking.md 包含了方法。业务成果、客户及其任务，以及最小可用版本。每项各用两行描述。
将成果写成可观察的结果：
一个拥有40个进行中工单的调度员，能够在不离开列表的情况下看到哪个工单迟到并重新分配。
然后是可以在浏览器中逐一检查的验收标准。“看起来不错”不是标准。“在 375px 宽度下，每个工单的状态及其重新分配控件都能在不横向滚动的情况下触及”才是。
在没有证据的情况下，写出你的假设并标记它。永远不要编写不是由项目参与者提供的用户画像、引述或转化数据。
3. 方向及用户选择
references/directions.md 包含了方法和词汇表。
提出三个方向，而不是一个。单一的提议只是模型默认审美披着合理解释的外衣。每个方向需要包含：名称、主色调色相、字体搭配、信息密度以及一个令人印象深刻的点，共四行。
然后停止，并使用交互式提问工具将它们提交给用户。这是一个批准关卡：不要在没有用户确认的情况下，仅凭假设就进行构建。如果用户说“你选”，则选一个，用一句话说明选哪个以及原因，然后继续。
一旦用户同意，用所选方向的实际值编写或更新 DESIGN.md，并进行门禁检查。
4. 用户旅程及其状态
references/journey-and-states.md。
列出这个界面真正拥有的所有状态：空状态、单个项目、多个项目、最密集的真实情况、加载中、部分失败、错误、无权限。一个仅基于单一数据生成屏幕的组件会隐藏所有其他状态，而这正是完成的界面在实际用户使用时失败的最常见原因。
5. 编写组件前先查找
运行 ui-find，或直接运行其脚本：
node .claude/skills/ui-design/scripts/find-components.js <搜索词> --limit 15
首先搜索项目自身的组件。对产品中已有的组件进行二次实现是一个缺陷。只有在列出已查阅的候选组件并说明每个为何不适合之后，才能从头编写一个组件。
6. 原型，还是真实产品
用一句话询问用户，除非用户已经表明。两条路径都构建真实的 HTML 和 CSS；区别在于文件存放的位置和它的连接方式。
| 路径 | 适用时机 | 文件存放位置 |
|---|---|---|
| 原型 | 新界面、重新设计、需要说服干系人，或用户主动要求 | 位于 mock/ 下的独立页面，使用真实的设计令牌和样本数据，并明确声明其为样本 |
| 直接构建 | 对现有产品内部进行修改，或用户要求直接构建 | 产品自身的文件目录 |
原型需要被批准，然后使用产品的组件重新构建。在构建之前说明这一点，这样就不会有人期望原型文件会被发布上线。
7. 构建
构建第4阶段中确定的所有状态，而不仅仅是愉快路径。使用产品自身的令牌和组件。
在进行第一次UI编辑之前（即使是小修改），每次都必须阅读 references/gates.md 和 references/craft.md。
gates.md 是底线：每个模型都会犯的默认错误，以及应该如何做。craft.md 是在这之上的层次。用阴影而非边框来表现深度。同心圆角。300ms 以下的缓动退出。仅在首次触发的入场动画，而非重复交互。使用表格数字。连接界面的两个部分，让用户感知到它们是一体的。
单独并首先构建最重要的界面或核心界面。在构建其余部分之前，用全新的视角对其进行审查：一个不记得先前决策的子Agent能发现你无法发现的问题。然后构建其余部分。
8. 运行并观察
不是代码审查。启动应用程序，在浏览器中打开它，并像用户一样从真实的入口点开始使用它。
references/playwright.md 包含了操作步骤以及在应用程序无法启动时的处理方法。
查看截图。阅读文件列表不等于观察。
9. 审查与修复
对你构建的内容运行 ui-review。它会测量实时渲染效果，遍历用户旅程，根据 DESIGN.md 检查结果，并按照危害程度对发现的问题进行排序。
按严重性顺序修复。你无法根据第2阶段确定的成果来证明其合理性的修改，是无人要求的工作范围。说明你忽略了什么以及原因。
然后参考 references/regression.md：识别在接触代码之前已经正常工作的用户旅程，并将你的更改引起的问题与已经存在的问题区分开。
10. 报告
- 客户成果是什么，以及是否达成。
- 选择的方向是什么，以及由谁选择。
- 按文件列出构建或更改了什么。
- 通过什么方式、在哪些宽度、哪些状态下验证了什么。
- 哪些尚未验证，以及原因。
- 已修复的发现，以及遗留的发现及其原因。
- 仍然只是假设的假设。
诚实原则，高于上述所有阶段
- 永远不要报告你未执行过的度量或未渲染过的界面。
- 标明每一个临时替代物。例如，用于替代真实数据的固定数据、用于替代应用页面的静态页面、用于替代品牌字体的本地字体。
- 当应用程序无法启动或访问时，请说明情况，并将所有关于用户旅程的声明标记为未验证。不要像你亲眼看到它运行那样来描述源代码。
- 永远不要凭空编造指标、推荐信、Logo墙或客户数量。如果缺少真实数据，请留下一个带标签的空位，并说明它是空的。
- 没有实际功能的表单必须在其界面本身中说明。一个显示“已发送”但没有实际发送操作的页面是缺陷，而不是占位符。
- 自己走一遍用户旅程能发现卡点，但这并不能衡量真实客户的行为。
本技能借鉴的内容及其来源
NOTICE 记录了这些信息。组件来源及其许可证信息在 sources.json 中；scripts/check-sources.js 用于验证该文件，tests/run.sh 用于测试脚本。