用途
ui-ux-design-principles 是一套关于用户（USER）体验决策的工程规范（canon），是设计原则三部曲中的第三部：
- software-design-principles：一个代码单元如何编写（SOLID、DRY、整洁代码）。
- architectural-design-principles：系统如何成形（分层、十二要素、适应度函数）。
- ui-ux-design-principles：产品如何呈现、如何行为、如何被导航，并保持可测试。
项目的 design-guide.{md,json} 与 ia.md 是本规范在每个项目中的实例化，就像 architecture.json 实例化分层规则一样。它仅使用 Markdown，不含脚本：被查阅，而非被调用。与架构规范类似，它把每条规则指向其执行方式（E2E/Playwright 层、针对 design-guide.json 的设计一致性检查、a11y 检查）。没有测试守护的规则是建议性的；有检查守护的规则才属于构建的一部分。
何时使用
- consort UX Designer 导入它来编写 design-guide.{md,json} + ia.md，并定义一致性门禁。
- Driver 在构建必须遵循设计指南的 UI 时导入它。
- 你在评审面向用户的变更，需要共享词汇（启发式、层级、无障碍）而非个人品味。
- 你在选择 UI 的构建方式，需要可测试性规则（框架选择、稳定接缝）。
UX 评审清单（promote/merge 前强制）
在宣布设计完成前确认每一行。当范围合理时留空是可以的；未考虑过的行则是一种坏味道。
| 属性 | 规则 | 执行方式 |
|---|---|---|
| 反馈 | 每个改变数据的操作都显示成功与失败反馈；无静默失败 | E2E 断言可见的确认 |
| 无障碍 | 可键盘导航、语义化 HTML、足够对比度、带标签的控件 | E2E 层的 a11y 检查（axe / 等效工具） |
| 视觉层级 | 主要操作最突出；引导视线 | 设计一致性（令牌）+ 评审 |
| 一致性 | 复用 design-guide 令牌 + 标准组件；一项工作一种模式 | 针对 design-guide.json 的设计一致性 |
| 信息架构 | 屏幕、导航、主要流程在样式之前定义 | ia.md 存在 + E2E 流程可追溯 |
| 可测试接缝 | 交互元素暴露稳定选择器（data-testid / role） | E2E 通过接缝而非脆弱的 CSS 定位元素 |
| 加载 / 延迟 | 任何超过约 200ms 的操作显示加载状态；反馈不引起布局偏移 | E2E + 设计一致性 |
没有负责人或没有检查的属性：在合并前解决。
参考主题
- 可用性启发式：Nielsen 的十条，精简版，每条附违规坏味道。
- 视觉层级：字号阶梯、间距、颜色、对比度、对齐：引导视线。
- 无障碍：WCAG 要点、语义化 HTML、ARIA、键盘、焦点、对比度。非可选。
- 交互与反馈：可供性、反馈规则、加载状态、错误预防/恢复、渐进式披露。
- 信息架构：屏幕、导航、流程、心智模型。ia.md 的来源。
- 设计系统与令牌：令牌作为事实来源、一致性、组件复用、design-guide.md / .json 的关系。
- 可测试 UI：可测试框架、稳定接缝、确定性渲染、边界层渲染、E2E 层的设计一致性。
硬性规则
- 无静默失败，无未确认的成功。每个改变数据的操作都显示可见的成功与失败反馈；反馈绝不引起布局偏移。
- 无障碍非可选。可键盘导航、对屏幕阅读器友好、足够对比度、带标签的控件，由 a11y 检查守护。
- 一致性优先于新颖性。复用 design-guide 令牌与标准组件；一项工作一种模式。design-guide.json 是事实来源。
- 视觉层级引导视线。最重要的操作最突出；重要性映射到字重、字号、位置。
- 信息架构先于像素。屏幕、导航与流程在样式之前定义（ia.md）。
- UI 构造即可测试。现代框架、确定性渲染、稳定接缝；渲染位于边界层。见 testable-ui。
- 渐进式披露。展示用户当下所需；将复杂性推迟到意图之后。
组合关系
- consort：UX Designer 编写 design-guide.{md,json} + ia.md 并设定一致性契约；Test Strategist 针对它编写 E2E 场景 + a11y 检查（见 test-strategy）；Driver 构建遵循该规范的 UI。
- architectural-design-principles：testable-ui 共享边界层规则（模板化是一种边界适配器）与适应度函数模型。
- software-design-principles：整洁代码命名同样适用于组件与模板片段。