--- 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 context: fork 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. The accessibility tier committed to in `design/accessibility-requirements.md` (if it exists) 2. The interaction pattern library at `design/ux/interaction-patterns.md` (if it exists) 3. The GDDs referenced in the spec's header (read their UI Requirements sections) 4. 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 warnings present for all text-heavy elements - [ ] Any layout-critical text has been flagged for 40% expansion accommodation **Acceptance Criteria Quality** - [ ] Criteria are specific enough for a QA tester who hasn't seen the design docs - [ ] Performance criterion present (screen opens within Xms) - [ ] Resolution criterion present - [ ] No criterion requires reading another document to evaluate --- ## Phase 3B: HUD Validation Checklist Run all checks against a `hud-design.md`-based document. ### Completeness - [ ] HUD Philosophy defined - [ ] Information Architecture table covers ALL systems with UI Requirements in GDDs - [ ] Layout Zones defined with safe zone margins for all target platforms - [ ] Every HUD element has a full specification (zone, visibility trigger, data source, priority) - [ ] HUD States by Gameplay Context covers at minimum: exploration, combat, dialogue/cutscene, paused - [ ] Visual Budget defined (max simultaneous elements, max screen %) - [ ] Platform Adaptation covers all target platforms - [ ] Tuning Knobs present for player-adjustable elements ### Quality Checks - [ ] No HUD element covers the center play area without a visibility rule to hide it - [ ] Every information item that exists in any GDD is either in the HUD or explicitly categorized as "hidden/demand" - [ ] All color-coded HUD elements have colorblind variants - [ ] HUD elements in the Feedback & Notification section have queue/priority behavior defined - [ ] Visual Budget compliance: total simultaneous elements is within budget ### GDD Alignment - [ ] All systems in `design/gdd/systems-index.md` with UI category have representation in HUD (or justified absence) --- ## Phase 3C: Pattern Library Validation Checklist - [ ] Pattern catalog index is current (matches actual patterns in document) - [ ] All standard control patterns are specified: button variants, toggle, slider, dropdown, list, grid, modal, dialog, toast, tooltip, progress bar, input field, tab bar, scroll - [ ] All game-specific patterns needed by current UX specs are present - [ ] Each pattern has: When to Use, When NOT to Use, full state specification, accessibility spec, implementation notes - [ ] Animation Standards table present - [ ] Sound Standards table present - [ ] No conflicting behaviors between patterns (e.g., "Back" behavior consistent across all navigation patterns) --- ## Phase 4: Output the Verdict ```markdown ## UX Review: [Document Name] **Date**: [date] **Reviewer**: ux-review skill **Document**: [file path] **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] - Target tier: [tier] - [list specific accessibility findings] ### Pattern Library: [CONSISTENT / INCONSISTENCIES FOUND] - [findings] ### Verdict: APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED **Blocking issues**: [N] — must be resolved before implementation **Advisory issues**: [N] — recommended but not blocking [For APPROVED]: This spec is ready for handoff to `/team-ui` Phase 2 (Visual Design). [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]. ``` --- ## Phase 5: Collaborative Protocol This skill is READ-ONLY — it never edits or writes files. It reports findings only. After delivering the verdict: - For **APPROVED**: suggest running `/team-ui` to begin implementation coordination - For **NEEDS REVISION**: offer to help fix specific gaps ("Would you like me to help draft the missing error state?") — but do not auto-fix; wait for user instruction - For **MAJOR REVISION NEEDED**: suggest returning to `/ux-design` with the specific sections to rework Never block the user from proceeding — the verdict is advisory. Document risks, present findings, let the user decide whether to proceed despite concerns. A user who chooses to proceed with a NEEDS REVISION spec takes on the documented risk.