ux-review skill

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:

to have reviewed UX specs)

• 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

• After major revisions to a UX spec

Verdict levels:

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

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

completeness; needs significant rework

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

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

that one document

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

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

(platform.targets, platform.primaryinput, platform.gamepadsupport, platform.touchsupport); 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 gamepadsupport is Full or Partial; touch if touchsupport is Full or Partial; plus primaryinput. 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.

1. Input & Platform config: Read the platform block from project.yaml

(if it exists)

1. The accessibility tier committed to in design/accessibility-requirements.md

it exists)

1. The interaction pattern library at design/ux/interaction-patterns.md (if

context-arrival validation

1. The GDDs referenced in the spec's header (read their UI Requirements sections)
2. The player journey map at design/player-journey.md (if it exists) for

Phase 3A: UX Spec Validation Checklist

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

Completeness (required sections)

developer-perspective)

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

documented

• [ ] 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

in header)

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

explanation

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

• [ ] 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

inventory")

• [ ] 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

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

mapping documented

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

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

Data Architecture

what triggers update?)

• [ ] 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" —

unavailable?)

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

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

requirement

• [ ] 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

GDD sections)