hud

design/ux/hud.md

patterns

design/ux/interaction-patterns.md

main-menu

inventory

design/ux/[argument].md

AskUserQuestion

• "What are we designing today?"
  • Options: "A specific screen or flow (I'll name it)", "The game HUD", "The interaction pattern library", "I'm not sure — help me figure it out"

main-menu

• Game concept: Read

  design/gdd/game-concept.md

  — if missing, warn:

  "No game concept found. Run

  /brainstorm

  first to establish the game's foundation before designing UX." Continue anyway if the user asks.

design/player-journey.md

• Which journey phase(s) does this screen appear in?
• What is the player's emotional state on arrival at this screen?
• What player need is this screen serving in the journey?
• What critical moments (from the journey map) does this screen deliver?

"No player journey map found at

design/player-journey.md

. Designing without it means we'll be making assumptions about player context. Consider running a player journey session after this spec is drafted."

"Player journey map not yet created. Template available at

.claude/docs/templates/player-journey.md

. Run

/ux-design

Phase 2b or create it manually to establish player context for this screen."

.claude/docs/technical-preferences.md

## Input & Platform

• Input Methods — e.g., Keyboard/Mouse, Gamepad, Touch, Mixed
• Primary Input — the dominant input for this game
• Gamepad Support — Full / Partial / None
• Touch Support — Full / Partial / None
• Target Platforms — for safe zone and aspect ratio decisions

[TO BE CONFIGURED]

"Input methods aren't configured yet. What does this game target?" Options: "Keyboard/Mouse only", "Gamepad only", "Both (PC + Console)", "Touch (mobile)", "All of the above"

(Run

/setup-engine

to save this permanently so you won't be asked again.)

Designing: [Screen/Flow Name]

• Mode: [UX Spec / HUD Design / Pattern Library]
• Journey phase(s): [from player-journey.md, or "unknown — no journey map"]
• GDD requirements feeding this spec: [count and names, or "none found"]
• Related screens already specced: [list, or "none yet"]
• Known patterns available: [count, or "no pattern library yet"]
• Accessibility tier: [from requirements doc, or "not yet defined"]
• Input methods: [from technical-preferences.md, or "asked above"]

design/ux/[filename].md

[filename]

• Read the file in full
• For each expected section, check whether the body has real content (more than a

  [To be designed]

  placeholder) or is empty/placeholder
• Present a section status summary to the user:

"Found existing UX spec at

design/ux/[filename].md

. Here's what's already done:

Section	Status
Overview & Context	[Complete / Empty / Placeholder]
Player Journey Integration	...
Screen Layout & Information Architecture	...
Interaction Model	...
Feedback & State Communication	...
Accessibility	...
Edge Cases & Error States	...
Open Questions	...

I'll work on the [N] incomplete sections only — existing content will not be overwritten."

• Skip Section 3 (skeleton creation) — the file already exists
• In Phase 4 (Section Authoring), only work on sections with Status: Empty or Placeholder
• Use

  Edit

  to fill placeholders in-place rather than creating a new skeleton

Status: In Design Author: [user + ux-designer] Last Updated: [today's date] Journey Phase(s): [from context] Template: UX Spec

Status: In Design Author: [user + ux-designer] Last Updated: [today's date] Template: HUD Design

Status: In Design Author: [user + ux-designer] Last Updated: [today's date] Template: Interaction Pattern Library

Context  ->  Questions  ->  Options  ->  Decision  ->  Draft  ->  Approval  ->  Write

1. Context: State what this section needs to contain and surface any relevant constraints from context gathered in Phase 2.
2. Questions: Ask what is needed to draft this section. Use

   AskUserQuestion

   for constrained choices, conversational text for open-ended exploration.
3. Options: Where design choices exist, present 2-4 approaches with pros/cons. Explain reasoning in conversation, then use

   AskUserQuestion

   to capture the decision.
4. Decision: User picks an approach or provides custom direction.
5. Draft: Write the section content in conversation for review. Flag provisional assumptions explicitly.
6. Approval: Use

   AskUserQuestion

   :
   • "Does this capture the [section name] correctly?"
   • Options: "Yes — write it to the file", "Small changes needed (describe below)", "Major rethink needed" Do not proceed to step 7 until the user selects "Yes".
7. Write: Use

   AskUserQuestion

   : "May I write the [section name] section to

   [filepath]

   ?"
   • Options: "Yes, write it", "Wait — one more change" Once confirmed, use

     Edit

     to replace the

     [To be designed]

     placeholder with approved content.

production/session-state/active.md

• "What player goal does this screen serve? What is the player trying to DO here?"
• "What would go wrong if this screen didn't exist or was hard to use?"
• "Complete this sentence: 'The player arrives at this screen wanting to ___.' "

• "When in the game does a player first encounter this screen?"
• "What were they just doing immediately before reaching this screen?"
• "What emotional state should the design assume? (calm, stressed, curious, time-pressured)"
• "Do players arrive at this screen voluntarily, or are they sent here by the game?"

• "Is this screen accessed from the main menu, from pause, from within gameplay, or from another screen?"
• "Is it a top-level destination (always reachable) or a context-dependent one (only accessible in certain states)?"
• "Can the player reach this screen from more than one place in the game?"

• "What are all the ways a player can reach this screen?" (List each trigger: button press, game event, redirect from another screen, etc.)
• "What can the player do to exit? What happens when they do?" (Back button, confirm action, timeout, game event)
• "Are there any exits that are one-way — where the player cannot return to this screen without starting over?"

• Ask the user to list every piece of information this screen must communicate.
• Then ask them to rank the items: "What is the single most important thing a player needs to see first? What is second? What can be discovered rather than immediately visible?"
• Present the resulting hierarchy for approval before moving to zones.

• Based on the information hierarchy, propose rough screen zones (header, content area, action bar, sidebar, etc.).
• Offer 2-3 zone arrangements with rationale for each. Reference platform and input context gathered from game concept.
• Use

  AskUserQuestion

  to capture the choice:
  • "Which zone arrangement fits best?"
  • Options: [the 2-3 named arrangements you just presented] + "None — build a custom arrangement"

• For each zone, list the UI components it contains. For each component, note:
  • Component type (button, list, card, stat display, input field, etc.)
  • Content it displays
  • Whether it is interactive
  • If it uses an existing pattern from the library (reference by pattern name)
  • If it introduces a new pattern (flag for later addition to the library)

• Offer to generate an ASCII wireframe based on the zone layout and component list.
• Use

  AskUserQuestion

  : "Want an ASCII wireframe as part of this spec?"
  • Options: "Yes, include one", "No, I'll attach a separate file"
• If yes, produce the wireframe in conversation first. Ask for feedback before writing it to file.

• "What does this screen look like the very first time a player sees it, when there is no data yet? (empty state)"
• "What happens when something goes wrong — an error, a failed action, a missing resource? (error state)"
• "Is there ever a loading wait on this screen? If so, what does it show? (loading state)"
• "Are there any player progression states that change what this screen shows? For example, locked content, premium content, or tutorial-mode overlays?"
• "Does this screen behave differently on any supported platform? (platform variant)"

• The action (tap, click, press, hold, scroll, drag)
• The platform input(s) that trigger it (mouse click, gamepad A, keyboard Enter)
• The immediate feedback (visual, audio, haptic)
• The outcome (navigation target, state change, data write)

technical-preferences.md

• "For each action, should the game fire an analytics event, trigger a game-state change, or both?"
• "Are there any actions that should NOT fire an event — and is that a deliberate choice?"

• "How does this screen appear? (fade in, slide from right, instant pop, scale from button)"
• "How does it dismiss? (fade out, slide back, cut)"
• "Are there any in-screen state transitions that need animation? (loading spinner, success state, error flash)"
• "Is there any animation that could cause motion sickness — and does the game have a reduced-motion option?"

• Screen enter transition
• Screen exit transition
• At least one state-change animation if the screen has multiple states

• "Where does this data come from? Which system owns it?"
• "Does this screen need to write data back, or is it read-only?"
• "Is any of this data time-sensitive or real-time? (health bars, cooldown timers)"

design/accessibility-requirements.md

• Keyboard-only navigation path through all interactive elements
• Gamepad navigation order (if applicable)
• Text contrast and minimum readable font sizes
• Color-independent communication (no information conveyed by color alone)
• Screen reader considerations for any non-text elements
• Any motion or animation that needs a reduced-motion alternative

"Accessibility tier not yet defined — consider WCAG-AA as a baseline. Run

/gate-check

to see whether this blocks any phase gates." Then continue to the next section without stopping.

• "Which text elements on this screen are the longest? What is the maximum character count that fits the layout?"
• "Are there any elements where text length is layout-critical — e.g., a button label that must stay on one line?"
• "Are there any elements that display numbers, dates, or currencies that need locale-specific formatting?"

/story-done

- [ ] Screen opens within [X]ms from [trigger]
- [ ] [Element] displays correctly at [minimum] and [maximum] values
- [ ] [Navigation action] correctly routes to [destination screen]
- [ ] Error state appears when [condition] and shows [specific message or icon]
- [ ] Keyboard/gamepad navigation reaches all interactive elements in logical order
- [ ] [Accessibility requirement] is met — e.g., "all interactive elements have focus indicators"

• 1 performance criterion (load/open time)
• 1 navigation criterion (at least one entry or exit path verified)
• 1 error/empty state criterion
• 1 accessibility criterion (per committed tier)
• 1 criterion specific to this screen's core purpose

AskUserQuestion

• "Do these acceptance criteria cover what would make this screen 'done' for your QA process?"
• Options: "Yes — these are solid", "Add one more criterion", "Remove or rephrase one"

• "Nearly HUD-free — atmosphere requires unobstructed immersion (e.g., Hollow Knight, Firewatch)"
• "Minimal but present — only critical information visible, everything else contextual (e.g., Dark Souls)"
• "Information-dense — all decision-relevant data always visible (e.g., Diablo IV, StarCraft II)"
• "Adaptive — HUD density responds to combat state, exploration mode, menus (e.g., God of War)"

AskUserQuestion

"The current Must Show list has [N] items. That may conflict with the HUD-free philosophy. Options: reduce the Must Show list, revise the philosophy, or define a hybrid approach where HUD is absent in exploration and present in combat."

• Which items are Must Show (they drive the permanent zone decisions)
• Where player attention naturally goes during gameplay (center-screen for action games, corners for strategy games)
• Platform and aspect ratio targets

• Element name and category (Must Show / Contextual / On Demand)
• Content displayed
• Visual form (bar, number, icon, counter, map)
• Update behavior (real-time, event-driven, player-queried)
• Contextual trigger (if not always visible)
• Animation behavior (does it pulse when low? Fade in? Slam in?)

• Dynamic Behaviors: what causes the HUD to change density mid-gameplay?
• Platform Variants: does mobile/console require different element sizes or positions?

design/ux/*.md

interaction-patterns.md

• [Pattern name]: used in [screen], [screen]
• [etc.]

• [Component behavior]
• [Input mapping]
• [Visual/audio feedback]
• [Accessibility requirements for this pattern]

Work through patterns in groups. Use `AskUserQuestion`:
- "How do you want to work through these patterns?"
- Options: "Draft the first batch from existing specs (faster)", "Define them one by one (more control)", "Start with the most-used pattern first"

---

• "Are there screens or interactions planned that would need patterns not yet in this library?"
• "Are there any patterns in existing specs that feel inconsistent with each other and should be consolidated?"

AskUserQuestion

• "This spec uses [pattern name], which isn't in the pattern library yet. What should we do?"
• Options: "Add it to the pattern library now", "Flag it as a gap and continue", "Skip — this pattern is one-off"

design/accessibility-requirements.md

Cross-Reference Check: [Screen Name]

• GDD requirements: [N of M covered / all covered]
• New patterns to add to library: [list or "none"]
• Navigation mismatches: [list or "none"]
• Accessibility gaps: [list or "none"]
• Missing empty states: [list or "none"]

production/session-state/active.md

• Task: [screen-name] UX spec
• Status: Complete (or In Review)
• File: design/ux/[filename].md
• Sections: All written
• Next: [suggestion]

"This spec should be validated with

/ux-review

before it enters the implementation pipeline. The Pre-Production gate requires all key screen specs to have a review verdict."

AskUserQuestion

• "Run

  /ux-review [filename]

  now, or do something else first?"
  • Options:
    • "Run

      /ux-review

      now — validate this spec"
    • "Design another screen first, then review all specs together"
    • "Update the interaction pattern library with new patterns from this spec"
    • "Stop here for this session"

/ux-review

/gate-check pre-production

1. Read

   production/session-state/active.md

   — it records the current screen and which sections are complete.
2. Read

   design/ux/[filename].md

   — sections with real content are done; sections with

   [To be designed]

   still need work.
3. Resume from the next incomplete section — no need to re-discuss completed ones.

ux-designer

art-director

ui-programmer

game-designer

narrative-director

• Provide: screen name, game concept summary, the specific question needing expert input
• The agent returns analysis to this session
• This session presents the agent's output to the user
• The user decides; this session writes to file
• Agents do NOT write to files directly — this session owns all file writes

1. Question -> Options -> Decision -> Draft -> Approval for every section
2. AskUserQuestion at every decision point (Explain -> Capture pattern):
   • Phase 2: "Ready to start, or need more context?"
   • Phase 3: "May I create the skeleton?"
   • Phase 4 (each section): design questions, approach options, draft approval
   • Phase 5: "Run cross-reference check? What's next?"
3. "May I write to [filepath]?" before the skeleton and before each section write
4. Incremental writing: Each section is written to file immediately after approval
5. Session state updates: After every section write

• Run

  /ux-review [filename]

  to validate this spec before it enters the implementation pipeline
• Run

  /ux-design [next-screen]

  to continue designing remaining screens or flows
• Run

  /gate-check pre-production

  once all key screens have approved UX specs