ux-review

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys workflow

已在上方解析，按原样使用。没有代码块 → 使用 .claude/docs/config-resolution.md 中的默认值。

UX 评审

概述

在 UX 设计文档进入实现流程前对其进行验证。 在 /team-ui 流程中，作为 UX 设计与视觉设计／实现之间的质量关卡。

运行此技能：

• 使用 /ux-design 完成 UX 规格说明后
• 移交给 ui-programmer 或 art-director 前
• 预制作转入制作的关卡检查前（该检查要求关键屏幕已有经过评审的 UX 规格说明）
• 对 UX 规格说明进行重大修订后

评审结论级别：

• APPROVED — 规格说明完整、一致，且已可用于实现
• NOT ASSESSED — 一个或多个评审维度没有可供检查的标准，或无法读取规格说明；请指出具体项目
• NEEDS REVISION — 发现具体缺漏；移交前需修正，但无需全面重新设计
• MAJOR REVISION NEEDED — 范围、玩家需求或完整性方面存在根本问题；需要大幅返工

NOT ASSESSED 的级别高于 APPROVED，低于两个需要修订的结论。 无法评估某个维度的评审，并不能证明规格说明已可用于实现；但已发现的缺漏比无人能检查的缺漏更具可操作性，因此不得将其排在这些结论之前。当无法读取规格说明文件、某个检查清单维度没有可供对照的权威来源，或无障碍等级尚未确定（见下文）时，使用此结论。

---

阶段 1：解析参数

• 具体文件路径（例如 /ux-review design/ux/inventory.md）：验证该文档
• all：查找 design/ux/ 中的所有文件并逐一验证
• hud：专门验证 design/ux/hud.md
• patterns：专门验证 design/ux/interaction-patterns.md
• 无参数：询问用户要验证哪份规格说明

对于 all，先输出摘要表（文件 | 结论 | 主要问题），然后给出每份文件的完整详情。

文件适用的检查清单（指定的文件路径，或 all 下的每个文件）：以 /ux-design 写入的 > **Template**: 标题行为准——UX Spec → 阶段 3A，HUD Design → 阶段 3B，Interaction Pattern Library → 阶段 3C。没有该行的文件按名称分类——hud.md → 3B，interaction-patterns.md → 3C，其他文件 → 3A——并在报告中说明采用了哪份检查清单以及原因。

---

阶段 2：加载交叉引用上下文

验证任何规格说明前，先加载以下内容：

1. 输入与平台配置：读取 project.yaml 中的 platform 块（platform.targets、platform.primary_input、platform.gamepad_support、platform.touch_support）；如果 project.yaml 中没有 platform 块，则回退到 .claude/docs/technical-preferences.md 的 ## Input & Platform 部分。对于支持的输入方式：从 project.yaml 读取时，根据配置推导——如果 targets 中包含 PC 或 Web，则支持键盘／鼠标；如果 gamepad_support 为 Full 或 Partial，则支持游戏手柄；如果 touch_support 为 Full 或 Partial，则支持触控；此外还包括 primary_input。回退到 technical-preferences.md 时，则使用其中明确列出的 Input Methods 字段。这是阶段 3A 中输入方式覆盖检查的权威来源，而非规格说明自身的标题。如果两处都未配置，则回退到规格说明标题。
2. design/accessibility-requirements.md 中确定的无障碍等级（如果存在）
3. 交互模式库 design/ux/interaction-patterns.md（如果存在）
4. 规格说明标题中引用的 GDD（读取其中的 UI Requirements 部分：使用 Grep 工具查找标题（模式 ^#，内容模式），再使用 Read 工具通过 offset 和 limit 读取对应范围）
5. 玩家旅程图 design/player-journey.md（如果存在），用于验证情境到达情况

---

阶段 3A：UX 规格说明验证检查清单

针对基于 ux-spec.md 的文档执行所有检查。

完整性（必需章节）

• 文档标题包含状态、作者、平台目标
• 目的与玩家需求 — 包含从玩家视角出发的需求陈述（而非开发者视角）
• 玩家到达时的情境 — 描述玩家的状态和此前的活动
• 导航位置 — 展示屏幕在层级结构中的位置
• 进入与退出位置 — 记录所有进入来源和退出目的地
• 布局规范 — 定义各区域，并包含组件清单表
• 状态与变体 — 至少记录加载、空数据/已填充和错误状态
• 交互映射 — 覆盖所有目标输入方式（检查标题中的平台目标）
• 数据要求 — 每个显示的数据元素都有来源系统和负责人
• 触发的事件 — 每个玩家操作都有对应事件，或说明为何为空
• 转场与动画 — 至少指定进入/退出转场
• 输入方式完整性清单 — 为平台目标行中的每种输入方式提供一个区块；任何未勾选的项目都要列在未决问题下
• 无障碍要求 — 包含屏幕级要求
• 本地化注意事项 — 文本元素的最大字符数
• 验收标准 — 至少包含 5 条具体且可测试的标准

质量检查

玩家需求清晰度

• 目的从玩家视角撰写，而非系统/开发者视角
• 玩家到达时的目标明确无歧义（“玩家到达时想要 ___”）
• 玩家到达时的情境具体（而非仅写“他们打开了背包”）

状态完整性

• 记录了错误状态（而不只是正常流程）
• 记录了空状态（无数据的情形）
• 如果屏幕会异步获取数据，则记录了加载状态
• 任何带计时器或会自动消失的状态都记录了持续时间

输入方式覆盖范围

• 如果平台包含 PC：完整说明仅使用键盘的导航方式
• 如果平台包含主机/游戏手柄：记录方向键导航和面部按钮映射
• 使用游戏手柄时，没有任何交互需要类似鼠标的精细操作
• 定义了焦点顺序（键盘的 Tab 顺序、游戏手柄的方向键顺序）

数据架构

• 没有将任何数据元素的负责人标为“UI”（游戏状态不得由 UI 持有）
• 为所有实时数据指定更新频率（不能只写“实时”——要说明触发更新的条件）
• 为所有数据元素指定空值处理方式（数据不可用时显示什么？）

无障碍

• 符合或超过 accessibility-requirements.md 中的无障碍等级
• 如果是基础等级：不得仅用颜色传达信息
• 如果是标准等级或更高：记录焦点顺序，并指定文本对比度
• 如果是全面等级或更高：为关键状态变化添加屏幕阅读器播报
• 色觉障碍检查：任何使用颜色编码的元素都有非颜色替代方式

GDD 一致性

• 标题中引用的每项 GDD UI 要求都在本规范中有所说明
• 没有任何 UI 元素在缺少对应 GDD 要求的情况下显示或修改游戏状态
• 本规范未遗漏任何 GDD UI 要求（交叉检查所引用的 GDD 章节）

模式库一致性

• 所有交互组件都引用模式库（或注明其为新模式）
• 如果模式库中已有某种模式行为，则不从头重新定义
• 本规范中设计的任何新模式都已标记，需添加到模式库

本地化

• 所有文本密集型元素都注明了字符数限制警告
• 所有对布局至关重要的文本都已标记，需预留 40% 的扩展空间

验收标准质量

• 标准足够具体，未看过设计文档的 QA 测试人员也能执行测试
• 包含性能标准（屏幕在 X 毫秒内打开）
• 包含分辨率标准
• 无需阅读其他文档即可评估每项标准

阶段 3B：HUD 验证清单

针对基于 hud-design.md 的文档运行所有检查。

完整性

• 已定义 HUD 理念
• 信息架构表涵盖 GDD 中包含 UI 要求的所有系统
• 已定义布局区域，并为所有目标平台设定安全区域边距
• 每个 HUD 元素都有完整规范（区域、可见性触发条件、数据来源、优先级）
• 按游戏情境划分的 HUD 状态至少涵盖：探索、战斗、对话／过场、暂停
• 信息层级为每个 HUD 元素指定优先级（必须保留／建议保留／可以隐藏／始终隐藏）
• 已定义视觉预算（同时显示的元素数量上限、屏幕占比上限）
• 平台适配涵盖所有目标平台
• 可由玩家调整的元素均提供调节选项
• 验收标准——至少 5 项具体且可测试的标准

质量检查

• 没有 HUD 元素覆盖中央游戏区域，除非有隐藏该元素的可见性规则
• 所有 GDD 中出现的信息项都已纳入 HUD，或明确归类为“隐藏／按需显示”
• 所有采用颜色编码的 HUD 元素都有色盲适配方案
• “反馈与通知”部分中的 HUD 元素已定义队列／优先级行为
• 符合视觉预算：同时显示的元素总数未超出预算

GDD 对齐

• design/gdd/systems-index.md 中所有 UI 类别的系统都已在 HUD 中体现（或说明未体现的理由）

---

阶段 3C：模式库验证清单

• 模式目录索引为最新（与文档中的实际模式一致）
• 已指定所有标准控件模式：按钮变体、切换开关、滑块、下拉菜单、列表、网格、模态框、对话框、轻提示、工具提示、进度条、输入框、标签栏、滚动
• 已包含当前 UX 规范所需的所有游戏专属模式
• 每个模式都包含：适用场景、不适用场景、完整状态规范、无障碍规范、实现说明
• 已提供动画标准表
• 已提供声音标准表
• 各模式之间不存在行为冲突（例如，所有导航模式中的“返回”行为一致）

---

阶段 4：给出结论

## UX Review: [Document Name]
**Date**: [date]
**Reviewer**: ux-review skill
**Document**: [file path]
**Checklist**: [3A / 3B / 3C — from its Template line, or assumed from the file name]
**Platform Target**: [from header]
**Accessibility Tier**: [from header or accessibility-requirements.md]

### Completeness: [X/Y sections present]
- [x] Purpose & Player Need
- [ ] States & Variants — MISSING: error state not documented

### Quality Issues: [N found]
1. **[Issue title]** [BLOCKING / ADVISORY]
   - What's wrong: [specific description]
   - Where: [section name]
   - Fix: [specific action to take]

### GDD Alignment: [ALIGNED / GAPS FOUND]
- GDD [name] UI Requirements — [X/Y requirements covered]
- Missing: [list any uncovered GDD requirements]

### Accessibility: [COMPLIANT / GAPS / NON-COMPLIANT / NOT ASSESSED]
- Target tier: [tier]
- [list specific accessibility findings]

> **If `design/accessibility-requirements.md` is absent there is no committed
> tier, so this dimension has no criterion.** Report
> `Accessibility: NOT ASSESSED — no committed tier (design/accessibility-requirements.md absent)`
> and do NOT report it as COMPLIANT — a gate compared against an absent standard
> passes the way an assertion that can never fail passes. The same rule lives in
> `/team-ui` Phase 4 and is mirrored here so the two cannot drift. If the spec's own
> header states a tier, carry it forward as an **assumption** and say plainly that
> it was assumed rather than committed. Recommend `/ux-design accessibility` to
> establish the tier.

### Pattern Library: [CONSISTENT / INCONSISTENCIES FOUND / N/A]
- [findings]

> **For a HUD design there is no Pattern Library checklist to run it against (Phase 3B has none), so Pattern Library is N/A, excluded from the dimension count.**
> Report `Pattern Library: N/A — no pattern library checklist for this document
> type`.
>
> For a UX spec, this dimension does have a checklist — it is checked against
> `design/ux/interaction-patterns.md`. If that file is absent: N/A only where
> the workflow tier does not require the library (`minimal`) — report
> `Pattern Library: N/A — interaction pattern library not required at this
> tier`. At any tier that requires or recommends it (`standard`, `full`), report
> `Pattern Library: NOT ASSESSED — design/ux/interaction-patterns.md not found`
> instead: the library is missing, not out of scope, and NOT ASSESSED counts it
> against the verdict as the unresolved item it is.

### Verdict: APPROVED / NOT ASSESSED / NEEDS REVISION / MAJOR REVISION NEEDED
**Blocking issues**: [N] — must be resolved before implementation
**Advisory issues**: [N] — recommended but not blocking
**Dimensions not assessed**: [N] — [name each, and what would make it checkable]

[For APPROVED]: This spec is ready for handoff to `/team-ui` Phase 2
(Visual Design).

[For NOT ASSESSED]: [N] of the four review dimensions could not be evaluated:
[name them]. The spec may well be sound — this review cannot say either way for
those dimensions. [For each: the one input that would make it checkable.]
Handoff to `/team-ui` is not recommended on this result.

[For NEEDS REVISION]: Address the [N] blocking issues above, then re-run
`/ux-review`.

[For MAJOR REVISION NEEDED]: The spec has fundamental gaps in [areas].
Recommend returning to `/ux-design` to rework [sections].

---

阶段 5：协作流程

此技能为只读——不会编辑或写入文件，仅报告发现。

给出结论后：

• 对于 APPROVED：建议运行 /team-ui，开始协调实现工作
• 对于 NOT ASSESSED：指出各维度缺少的输入，并主动提供帮助以生成这些内容（未提交的层级可使用 /ux-design accessibility；缺少 UI 要求时则提供 GDD 路径）。不要针对同一组缺失输入重新执行审查并给出不同结论——只有新增输入才能改变结论
• 对于 NEEDS REVISION：主动提供帮助以修复具体缺漏（“需要我帮你起草缺少的错误状态吗？”）——但不要自动修复；等待用户指示
• 对于 MAJOR REVISION NEEDED：建议返回 /ux-design，重新处理指定部分

绝不要阻止用户继续推进——结论仅供参考。记录风险、展示发现，并由用户决定是否无视顾虑继续推进。若用户选择基于 NEEDS REVISION 规格继续推进，则需自行承担文档所述风险。