UX 设计手册 是做什么的？
构建 对业务正确、易于使用且一致 的用户界面。Mantine 提供了组件，本手册告诉你 何时 使用哪个、屏幕需要 哪些状态，以及 如何检查 结果。只阅读你任务所需的页面。
优先级
当多个来源不一致时，优先级较高的胜出：
- 业务需求：规格说明书、工单或负责人的指示。切勿不经沟通就擅自更改。
- 产品自有规则：
AGENTS.md/CLAUDE.md、产品的 UX 和设计文档、现有的组件。 - 本手册。
- Mantine 文档和默认值。
如果 2 和 3 不一致，遵循 2。如果你认为 2 或 1 是错误的，仍然执行它，并提交一份 UX 提案。
在开始 UI 工作之前，查找产品的 UX 规则（在仓库文档中搜索 "UX"、"UI"、"design"、"panel"）。如果没有找到，请使用 产品简介模板 起草一份，并在计划或 PR 中提出草案，每个猜测都标注为 [假设]。
确定变更等级
| 等级 | 变更范围 | 你的操作 |
|---|---|---|
| S | 对现有屏幕的小改动：一个字段、一个按钮、一条消息、一列 | 阅读涉及组件的页面。运行对应的检查清单。如果布局发生变化，请截图。 |
| M | 新增屏幕、对话框或表单，或对现有屏幕进行大规模改动 | 先编写一份简短的 UX 规格说明。构建它。执行 可视化检查。使用 评审标准 进行自我审查。 |
| L | 跨屏幕的新流程、新功能区域或导航变更 | 先制作一份 调研笔记，提供 2-3 个方案。构建安全方案 A。然后将每个屏幕视为 M 等级处理。 |
每个等级的详细内容和交付物：工作流程。
查找对应页面
| 你需要决策 … | 阅读 |
|---|---|
| 页面结构、层级、间距、响应式布局 | decisions/layout |
| 按钮、主要 vs 次要、图标按钮、操作菜单 | decisions/actions |
| Modal vs Drawer vs Popover vs 内联、工具提示 | decisions/overlays |
| 应用导航、标签页、面包屑、步骤条、分页、链接 vs 按钮 | decisions/navigation |
| 表格、列表、卡片、状态标签、日期、长文本 | decisions/data-display |
| Toast、警告、横幅、内联消息 | decisions/feedback |
| 选择输入：复选框、开关、单选按钮、分段控件、选择框、组合框、芯片 | decisions/selection |
| 表单、标签、验证、必填字段 | patterns/forms |
| 保存按钮、自动保存、未保存的更改 | patterns/saving |
| 暂无内容、无结果 | patterns/empty-states |
| 等待数据或任务完成 | patterns/loading |
| 高级选项、“显示更多”、按需显示详细信息 | patterns/progressive-disclosure |
| 功能介绍、首次运行、操作提示 | patterns/feature-onboarding |
| 后端不可用、离线、部分失败、缺少权限 | patterns/degraded-experiences |
| 删除、重置、撤销、覆盖 | flows/destructive-actions |
| 标签、按钮文本、错误文本、空状态文本 | writing |
| 键盘、焦点、标签、对比度、ARIA | accessibility |
| 查找 Mantine API、主题令牌、版本 | mantine |
| 规则背后的原因 | principles |
始终遵循
- 使用产品现有组件和 Mantine，而不是自己编写。每个任务使用一个组件。
- 为每个数据视图提供 加载、空和错误 状态。为每个操作提供 待处理状态和结果。
- 每个视图保持 一个主要操作。次要操作应更低调。罕见操作放在菜单中。
- 当前不可用的操作 保持可见并说明原因，以用户可通过键盘和触摸访问的文本形式呈现，而不仅仅在工具提示中。优先使用不可用外观（
data-disabled）而非disabled属性，并且永远不要禁用提交按钮：actions。 - 对于任何会销毁数据的操作，请确认或允许撤销。切勿在发生错误时丢失用户的输入。
- 每个输入都有可见标签。意义绝不仅仅由颜色传达。一切都可通过键盘到达。
- 在手机宽度和桌面宽度、浅色和深色主题下检查结果：可视化检查。
- 本手册中的示例使用英文字面字符串。请使用产品的国际化方案。
当你觉得可以做得更好时
你可以而且应该提出更好的流程和组件。规则是 构建安全的默认方案，附上提案：
- 按照规格说明的要求构建，使用本手册中的模式。
- 将你的想法作为 UX 提案 添加到计划或 PR 中，采用 固定格式。
- 仅在规格说明会导致数据丢失、泄露机密、阻碍依赖键盘或屏幕阅读器的用户，或存在自相矛盾时，才 在构建前 停下来提问。
报告
在 PR 或报告中以 UX 笔记 部分结束每个 UI 任务：
## UX 笔记
- 等级: M — 新建“模组”选项卡
- 状态: 加载 ✓ 空 ✓ 错误 ✓ 已禁用并附带原因 ✓
- 截图: 1280 浅色/深色, 390 浅色/深色 (已附上)
- 评审标准: 全部通过；不适用: 销毁操作（无）
- 假设: [假设] 模组列表较短 (< 50)，所以不用分页
- UX 提案: 1 个 (见下文)