/ux-review

name: ux-review
description: "Validate a UX spec, HUD design or pattern library — accessibility, GDD alignment, readiness. APPROVED / NOT ASSESSED / NEEDS REVISION / MAJOR REVISION NEEDED."
argument-hint: "[file-path or 'all' or 'hud' or 'patterns']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash(bash "*/.claude/skills/ux-review/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet

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

Resolved above — use as-is. No block → defaults in `.claude/docs/config-resolution.md`.

UX Review

Overview

Validates UX design documents before they enter the implementation pipeline. Acts as the quality gate between UX Design and Visual Design/Implementation in the `/team-ui` pipeline.

**Run this skill:**

• After completing a UX spec with `/ux-design`
• Before handing off to `ui-programmer` or `art-director`
• Before the Pre-Production to Production gate check (which requires key screens

to have reviewed UX specs)

• After major revisions to a UX spec

**Verdict levels:**

• **APPROVED** — spec is complete, consistent, and implementation-ready
• **NOT ASSESSED** — one or more review dimensions had no criterion to check

against, or the spec could not be read; name which

• **NEEDS REVISION** — specific gaps found; fix before handoff but not a full redesign
• **MAJOR REVISION NEEDED** — fundamental issues with scope, player need, or

completeness; needs significant rework

**`NOT ASSESSED` ranks above APPROVED and below the two revision verdicts.** A review that could not evaluate a dimension has not shown the spec is implementation-ready; but a gap somebody found is more actionable than one nobody could look for, so it must not displace them. Emit it when the spec file cannot be read, when a checklist dimension has no source of truth to compare against, or when the accessibility tier is uncommitted (below).

---

Phase 1: Parse Arguments

• **Specific file path** (e.g., `/ux-review design/ux/inventory.md`): validate

that one document

• **`all`**: find all files in `design/ux/` and validate each
• **`hud`**: validate `design/ux/hud.md` specifically
• **`patterns`**: validate `design/ux/interaction-patterns.md` specifically
• **No argument**: ask the user which spec to validate

For `all`, output a summary table first (file | verdict | primary issue) then full detail for each.

**Which checklist a file gets** (a file path, or each file under `all`): its `> **Template**:` header line, which `/ux-design` writes — `UX Spec` → Phase 3A, `HUD Design` → 3B, `Interaction Pattern Library` → 3C. A file without that line is classified by name — `hud.md` → 3B, `interaction-patterns.md` → 3C, anything else → 3A — and the report says which checklist it assumed, and why.

---

Phase 2: Load Cross-Reference Context

Before validating any spec, load:

1. **Input & Platform config**: Read the `platform` block from `project.yaml` (`platform.targets`, `platform.primary_input`, `platform.gamepad_support`, `platform.touch_support`); if `project.yaml` has no `platform` block, fall back to the `## Input & Platform` section of `.claude/docs/technical-preferences.md`. For the set of supported input methods: when reading from `project.yaml`, derive it — keyboard/mouse if `PC` or `Web` is in `targets`; gamepad if `gamepad_support` is Full or Partial; touch if `touch_support` is Full or Partial; plus `primary_input`. When falling back to `technical-preferences.md`, use its explicit Input Methods field instead. This is the authoritative source for the Input Method Coverage checks in Phase 3A — not the spec's own header. If neither source is configured, fall back to the spec header. 2. The accessibility tier committed to in `design/accessibility-requirements.md` (if it exists) 3. The interaction pattern library at `design/ux/interaction-patterns.md` (if it exists) 4. The GDDs referenced in the spec's header (read their UI Requirements sections: find the headings with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit) 5. The player journey map at `design/player-journey.md` (if it exists) for context-arrival validation

---

Phase 3A: UX Spec Validation Checklist

Run all checks against a `ux-spec.md`-based document.

Completeness (required sections)

• [ ] Document header present with Status, Author, Platform Target
• [ ] Purpose & Player Need — has a player-perspective need statement (not

developer-perspective)

• [ ] Player Context on Arrival — describes player's state and prior activity
• [ ] Navigation Position — shows where screen sits in hierarchy
• [ ] Entry & Exit Points — all entry sources and exit destinations documented
• [ ] Layout Specification — zones defined, component inventory table present
• [ ] States & Variants — at minimum: loading, empty/populated, and error states

documented

• [ ] Interaction Map — covers all target input methods (check platform target

in header)

• [ ] Data Requirements — every displayed data element has a source system and owner
• [ ] Events Fired — every player action has a corresponding event or null

explanation

• [ ] Transitions & Animations — at least enter/exit transitions specified
• [ ] Input Method Completeness Checklist — a block for each input method in

the Platform Target line; any unticked item is listed under Open Questions

• [ ] Accessibility Requirements — screen-level requirements present
• [ ] Localization Considerations — max character counts for text elements
• [ ] Acceptance Criteria — at least 5 specific testable criteria

Quality Checks

**Player Need Clarity**

• [ ] Purpose is written from player perspective, not system/developer perspective
• [ ] Player goal on arrival is unambiguous ("The player arrives wanting to ___")
• [ ] The player context on arrival is specific (not just "they opened the

inventory")

**Completeness of States**

• [ ] E