How to Create and Review UX Specifications and Interface Designs in Claude Code Game Studios

Use the /ux-design slash command to interactively author UI specifications and /ux-review to validate them against game design documents and accessibility requirements before advancing through the pre-production gate.

In the Donchitos/Claude-Code-Game-Studios repository, interface design is a formal gated process within Phase 4 (Pre-Production). The workflow centers on two specialized slash commands that enforce structured documentation standards while integrating accessibility compliance directly into the authoring loop.

Core UX Commands

The system provides two dedicated slash commands to manage the interface design lifecycle.

Authoring with /ux-design

The /ux-design <screen|hud|flow|interaction-patterns> command initiates an interactive, section-by-section authoring session. When invoked, the ux-designer agent automatically loads context from existing GDDs, the player-journey document, and design/accessibility-requirements.md to guide decision-making.

The command creates files under design/ux/ with paths such as design/ux/hud.md or design/ux/screens/inventory.md.

Validating with /ux-review

The /ux-review <path-or-all> command validates completed specifications against the GDDs, declared accessibility tier, and the interaction-pattern library. It produces a markdown table of checks with ✅, ⚠️, or ❌ statuses and a verdict of APPROVED, NEEDS REVISION, or MAJOR REVISION.

Required Document Structure

According to .claude/rules/design-docs.md, every UX specification must contain eight mandatory sections: Player Need, Layout Zones, States, Interaction Map, Data Requirements, Events, Accessibility, and Localization. The ux-designer agent enforces these sections automatically during the authoring session, ensuring the document is complete enough for downstream agents like ui-programmer.

The Collaborative Authoring Loop

Every /ux-design session follows the standard Question → Options → Decision → Draft → Approval protocol defined in the Claude-Code engine. The agent prompts you for each design aspect and requires explicit confirmation before writing to disk.

/ux-design hud

> ux-designer: Loading GDDs, player-journey, and accessibility tier…
> Question: What HUD philosophy do you prefer?
> Options:
>   A) Diegetic (low presence)
>   B) Persistent minimal (always visible)
>   C) Full tactical (all info always on)
> Decision → B
> Drafted "HUD Philosophy" section…
> May I write this to design/ux/hud.md? (yes/no)

Validating and Iterating Designs

Once authoring completes, rigorous validation ensures compliance before production begins.

Running the Review Check

Execute /ux-review with a specific file path or all to scan the entire design/ux/ directory:

/ux-review design/ux/hud.md

> ux-review: Scanning design/ux/hud.md…
| Check                | Status | Notes |
|----------------------|--------|-------|
| GDD alignment        | ✅     | All required elements present |
| Accessibility tier   | ⚠️     | Color-blind indicator missing |
| Visual budget        | ✅     | ≤ 8 % screen coverage |
Verdict: NEEDS REVISION

Resolving BLOCKING Issues

Any accessibility violations or missing required sections appear as BLOCKING items in the review table. For example, if the inventory screen lacks a keyboard path, the review flags this under the accessibility check as shown in docs/examples/session-ux-pipeline.md. You must resolve these by re-running /ux-design to edit the problematic sections, then re-run /ux-review until the verdict returns APPROVED.

Pre-Production Gate Integration

The UX specifications must achieve an APPROVED status before the pre-production gate passes. The gate check /gate-check pre-production verifies that all required UX documentation is validated and records the pass in production/stage.txt, unlocking the Production phase.

# After achieving APPROVED status on all UX specs

/gate-check pre-production

> Gate check PASSED. Stage advanced to Production.

Reusable Interaction Patterns

The system maintains a shared pattern catalog at design/ux/interaction-patterns.md, populated via /ux-design interaction-patterns. Subsequent specs can reference these patterns by name, guaranteeing consistency across screens and enabling the team-ui hand-off to reuse proven implementations.

Summary

• Use /ux-design to author UI specs interactively with automatic enforcement of the eight required sections defined in .claude/rules/design-docs.md.
• Validate with /ux-review to check against GDDs, accessibility tiers from design/accessibility-requirements.md (Basic, Standard, Comprehensive, or Exemplary), and visual budgets before proceeding.
• Resolve BLOCKING items such as missing keyboard alternatives or color-blind cues by editing specs and re-reviewing until the verdict is APPROVED.
• Pass the gate only after all UX specs are approved, advancing production/stage.txt to the Production phase.
• Reference interaction patterns from design/ux/interaction-patterns.md to maintain consistency across the interface.

Frequently Asked Questions

What files does /ux-design create?

The command generates markdown files under the design/ux/ directory. Specific paths include design/ux/hud.md for heads-up displays, design/ux/screens/inventory.md for screen specifications, and design/ux/interaction-patterns.md for the reusable pattern library.

How does the review check accessibility compliance?

The /ux-review command reads design/accessibility-requirements.md to determine the project's accessibility tier. It validates that each UI element satisfies the corresponding requirements; missing keyboard alternatives or color-blind indicators trigger BLOCKING status in the review table.

Can I review multiple UX specs simultaneously?

Yes. Use /ux-review all to validate every specification in the design/ux/ directory at once, or provide a specific path like /ux-review design/ux/hud.md to audit a single document.

What is the difference between NEEDS REVISION and MAJOR REVISION?

NEEDS REVISION indicates minor issues such as missing non-blocking accessibility cues or formatting inconsistencies. MAJOR REVISION signals fundamental misalignment with GDDs, incorrect interaction patterns, or missing mandatory sections that require substantial redesign before re-review.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}