/ux-review

name: ux-review
description: "Validates a UX spec, HUD design, or interaction pattern library for completeness, accessibility compliance, GDD alignment, and implementation readiness. Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict with specific gaps."
argument-hint: "[file-path or 'all' or 'hud' or 'patterns']"
user-invocable: true
allowed-tools: Read, Glob, Grep
model: sonnet
agent: ux-designer

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
• **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

---

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.

---

Phase 2: Load Cross-Reference Context

Before validating any spec, load:

1. **Input & Platform config**: Read `.claude/docs/technical-preferences.md` and extract `## Input & Platform`. This is the authoritative source for which input methods the game supports — use it to drive the Input Method Coverage checks in Phase 3A, not the spec's own header. If unconfigured, 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) 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
• [ ] 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**

• [ ] Error state is documented (not just happy path)
• [ ] Empty state is documented (no data scenario)
• [ ] Loading state is documented if the screen fetches async data
• [ ] Any state with a timer or auto-dismiss is documented with duration

**Input Method Coverage**

• [ ] If platform includes PC: keyboard-only navigation is fully specified
• [ ] If platform includes console/gamepad: d-pad navigation and face button

mapping documented

• [ ] No interaction requires mouse-like precision on gamepad
• [ ] Focus order is defined (Tab order for keyboard, d-pad order for gamepad)

**Data Architecture**

• [ ] No data element has "UI" listed as the owner (UI must not own game state)
• [ ] Update frequency is specified for all real-time data (not just "realtime" —

what triggers update?)

• [ ] Null handling is specified for all data elements (what shows when data is

unavailable?)

**Accessibility**

• [ ] Accessibility tier from `accessibility-requirements.md` is matched or exceeded
• [ ] If Basic tier: no color-only information indicators
• [ ] If Standard tier+: focus order documented, text contrast ratios specified
• [ ] If Comprehensive tier+: screen reader announcements for key state changes
• [ ] Colorblind check: any color-coded elements have non-color alternatives

**GDD Alignment**

• [ ] Every GDD UI Requirement referenced in the header is addressed in this spec
• [ ] No UI element displays or modifies game state without a corresponding GDD

requirement

• [ ] No GDD UI Requirement is missing from this spec (cross-check the referenced

GDD sections)

**Pattern Library Consistency**

• [ ] All interactive components reference the pattern library (or note they are

new patterns)

• [ ] No pattern behavior is re-specified from scratch if it already exists in

the pattern library

• [ ] Any new patterns invented in this spec are flagged for addition to the

pattern library

**Localization**

• [ ] Character limit