Guided, section-by-section UX spec authoring for a screen, flow, or HUD. Reads game concept, player journey, and relevant GDDs to provide context-aware design guidance. Produces ux-spec.md (per screen/flow) or hud-design.md using the studio templates.
When this skill is invoked:
Three authoring modes exist based on the argument:
| Argument | Mode | Output file |
|---|---|---|
hud | HUD design | design/ux/hud.md |
patterns | Interaction pattern library | design/ux/interaction-patterns.md |
Any other value (e.g., main-menu, inventory) | UX spec for a screen or flow | design/ux/[argument].md |
| No argument | Ask the user | (see below) |
If no argument is provided, do not fail — ask instead. Use AskUserQuestion:
If the user selects "I'll name it" or types a screen name, normalize it to kebab-case
for the filename (e.g., "Main Menu" becomes main-menu).
Read all relevant context before asking the user anything. The skill's value comes from arriving informed.
design/gdd/game-concept.md — if missing, warn:
"No game concept found. Run
/brainstormfirst to establish the game's foundation before designing UX." Continue anyway if the user asks.
Read design/player-journey.md if it exists. For each relevant section, extract:
If the player journey file does not exist, note the gap and proceed:
"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."
Glob design/gdd/*.md and grep for UI Requirements sections. Read any GDD whose
UI Requirements section references this screen by name or category.
These GDD UI Requirements are the requirements input to this spec. Collect them as a list of constraints the spec must satisfy.
If designing the HUD, read ALL GDD UI Requirements sections — the HUD aggregates requirements from every system.
Glob design/ux/*.md and note which screens already have specs. For screens that
will link to or from the current screen, read their navigation/flow sections to
find the entry and exit points this spec must match.
If design/ux/interaction-patterns.md exists, read the pattern catalog index
(the list of pattern names and their one-line descriptions). Do not read full
pattern details — just the catalog. This tells you which patterns already exist
so you can reference them rather than reinvent them.
Check for design/art/art-bible.md. If found, read the visual direction
section. UX layout must align with the aesthetic commitments already made.
Check for design/accessibility-requirements.md. If found, read it. The spec
must satisfy the accessibility tier committed to there.
Read .claude/docs/technical-preferences.md and extract the ## Input & Platform
section. Store these values for use throughout the skill — they drive the
Interaction Map and inform accessibility requirements:
If the section is unconfigured ([TO BE CONFIGURED]), ask once:
"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-engineto save this permanently so you won't be asked again.)
Store the answer for the rest of this session. Do not ask again per section or per screen.
Before any design work, present a brief summary to the user:
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"]
Then ask: "Anything else I should read before we start, or shall we proceed?"
Before creating a skeleton, check if the target output file already exists.
Glob design/ux/[filename].md (where [filename] is the resolved output path from Phase 1).
If the file exists — retrofit mode:
[To be designed] placeholder) or is empty/placeholder"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."
Edit to fill placeholders in-place rather than creating a new skeletonIf the file does not exist — fresh authoring mode: Proceed to Phase 3 (Create File Skeleton) as normal.
Once the user confirms, immediately create the output file with empty section headers. This ensures incremental writes have a target and work survives interruptions.
Ask: "May I create the skeleton file at design/ux/[filename].md?"
# UX Spec: [Screen/Flow Name]
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Journey Phase(s)**: [from context]
> **Template**: UX Spec
---
## Purpose & Player Need
[To be designed]
---
## Player Context on Arrival
[To be designed]
---
## Navigation Position
[To be designed]
---
## Entry & Exit Points
[To be designed]
---
## Layout Specification
### Information Hierarchy
[To be designed]
### Layout Zones
[To be designed]
### Component Inventory
[To be designed]
### ASCII Wireframe
[To be designed]
---
## States & Variants
[To be designed]
---
## Interaction Map
[To be designed]
---
## Events Fired
[To be designed]
---
## Transitions & Animations
[To be designed]
---
## Data Requirements
[To be designed]
---
## Accessibility
[To be designed]
---
## Localization Considerations
[To be designed]
---
## Acceptance Criteria
[To be designed]
---
## Open Questions
[To be designed]
# HUD Design
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Template**: HUD Design
---
## HUD Philosophy
[To be designed]
---
## Information Architecture
### Full Information Inventory
[To be designed]
### Categorization
[To be designed]
---
## Layout Zones
[To be designed]
---
## HUD Elements
[To be designed]
---
## Dynamic Behaviors
[To be designed]
---
## Platform & Input Variants
[To be designed]
---
## Accessibility
[To be designed]
---
## Open Questions
[To be designed]
# Interaction Pattern Library
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Template**: Interaction Pattern Library
---
## Overview
[To be designed]
---
## Pattern Catalog
[To be designed]
---
## Patterns
[Individual pattern entries added here as they are defined]
---
## Gaps & Patterns Needed
[To be designed]
---
## Open Questions
[To be designed]
After writing the skeleton, update production/session-state/active.md with:
Walk through each section in order. For each section, follow this cycle:
Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write
AskUserQuestion
for constrained choices, conversational text for open-ended exploration.AskUserQuestion to capture the decision.Edit to replace the [To be designed] placeholder with approved
content. Confirm the write.After writing each section, update production/session-state/active.md.
This section is the foundation. Every other decision flows from it.
Questions to ask:
Cross-reference the player journey context gathered in Phase 2. The stated purpose must align with the journey phase and emotional state.
Questions to ask:
Offer to map this against the journey phases if the player journey doc exists.
Where does this screen sit in the game's navigation hierarchy? This is a one-paragraph orientation map — not a full flow diagram.
Questions to ask:
Present as: "This screen lives at: [root] → [parent] → [this screen]" plus any alternate entry paths.
Map every way the player can arrive at and leave this screen.
Questions to ask:
Present as two tables:
| Entry Source | Trigger | Player carries this context |
|---|---|---|
| [screen/event] | [how] | [state/data they arrive with] |
| Exit Destination | Trigger | Notes |
|---|---|---|
| [screen/event] | [how] | [any irreversible state changes] |
This is the largest and most interactive section. Work through it in sub-sections:
Sub-section 1 — Information Hierarchy (establish this before any layout):
Sub-section 2 — Layout Zones:
Sub-section 3 — Component Inventory:
Sub-section 4 — ASCII Wireframe:
AskUserQuestion: "Want an ASCII wireframe as part of this spec?"
Guide the user to think beyond the happy path.
Questions to ask (work through these one at a time):
Present the collected states as a table for approval:
| State / Variant | Trigger | What Changes |
|---|---|---|
| Default | Normal load | — |
| Empty | No data available | [content area description] |
| [etc.] | [trigger] | [changes] |
For each interactive component identified in the Layout Specification, define:
Use the input methods loaded from technical-preferences.md in Phase 2h — do
not ask the user again. State them upfront: "Mapping interactions for:
[Input Methods from tech-prefs]. Covering [Gamepad Support] gamepad support."
Work through components one at a time rather than asking for all at once. For navigation actions (going to another screen), verify the target matches an existing UX spec or note it as a spec dependency.
For every player action in the Interaction Map, document the corresponding event the game or analytics system should fire — or explicitly note "no event" if none applies.
Questions to ask:
Present as a table alongside the Interaction Map:
| Player Action | Event Fired | Payload / Data |
|---|---|---|
| [action] | [EventName] or none | [data passed with event] |
Flag any action that modifies persistent game state (save data, progress, economy) — these need explicit attention from the architecture team.
Specify how the screen enters and exits, and how it responds to state changes.
Questions to ask:
Minimum required:
Cross-reference the GDD UI Requirements sections gathered in Phase 2.
For each piece of information the screen displays, ask:
Flag any case where the UI would need to own or manage game state as an architectural concern. UX specs define what the UI needs; they do not dictate how the data is delivered. That is an architecture decision.
Present the data requirements as a table:
| Data | Source System | Read / Write | Notes |
|---|---|---|---|
| [item] | [system] | Read | — |
| [item] | [system] | Write | [concern if any] |
Cross-reference design/accessibility-requirements.md if it exists.
Walk through the ux-designer agent's standard checklist for this screen:
Use AskUserQuestion to surface any open questions on accessibility tier:
Document constraints that affect how this screen behaves when text is translated.
Questions to ask:
Note: aim to flag any element where a 40% text expansion (common in translations from English to German or French) would break the layout. Mark those as HIGH PRIORITY for the localization engineer.
Write at least 5 specific, testable criteria that a QA tester can verify without reading any other design document. These become the pass/fail conditions for /story-done.
Format: Use checkboxes. Each criterion must be verifiable by a human tester:
- [ ] 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"
Minimum required:
Ask the user to confirm: "Do these criteria cover what would actually make this screen 'done' for your QA process?"
HUD design follows a different order from UX spec mode. Begin with philosophy; do not touch layout until the information architecture is complete.
Ask the user to describe the game's relationship with on-screen information in 1-2 sentences.
Offer framing examples to help:
This philosophy becomes the design constraint for every subsequent HUD decision. If a proposed element conflicts with the stated philosophy, surface that conflict.
Complete this before any layout work. Do not skip it.
Step 1 — Full information inventory: Pull all information from GDD UI Requirements sections gathered in Phase 2. Present the full list: "These are all the things your game systems say they need to communicate to the player on screen."
Step 2 — Categorization: For each item, ask the user to categorize it:
| Category | Description |
|---|---|
| Must Show | Always visible, player needs it for core decisions |
| Contextual | Visible only when relevant (in combat, near interactable, etc.) |
| On Demand | Player must actively request it (toggle, hold button) |
| Hidden | Communicated through world/audio, never on-screen text |
Use AskUserQuestion to step through items in groups of 3-4, not all at once.
This is the most consequential design decision in the HUD — do not rush it.
Conflict check: If the information philosophy (Section A) says "nearly HUD-free" but the Must Show list is growing long, surface the conflict explicitly:
"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."
Only after the information architecture is approved, design layout zones.
Base layout on:
Offer 2-3 zone arrangements. Include rationale based on the HUD philosophy and the categorization from Section B.
For each element in the layout, specify:
Work element by element. Reference the interaction pattern library if relevant patterns exist for status displays, resource bars, or cooldown indicators.
These follow the same structure as the UX spec equivalents. See UX Spec section guidance for D (States/Variants), E (Interactions), and G (Accessibility).
For the HUD specifically, emphasize:
Pattern library authoring is additive and catalog-driven, not linear.
Glob design/ux/*.md (excluding interaction-patterns.md) and read the Component
Inventory and Interaction Map sections of each spec. Extract every interaction
pattern used.
Present the extracted list: "Based on existing UX specs, these patterns are already in use in the game:"
Ask: "Are there patterns you know exist but aren't in existing specs yet? List any additional ones now."
For each pattern (existing or new), document:
### [Pattern Name]
**Category**: Navigation / Input / Feedback / Data Display / Modal / Overlay / [other]
**Used In**: [list of screens]
**Description**: [One paragraph explaining what this pattern is and when to use it]
**Specification**:
- [Component behavior]
- [Input mapping]
- [Visual/audio feedback]
- [Accessibility requirements for this pattern]
**When to Use**: [Conditions where this pattern is appropriate]
**When NOT to Use**: [Conditions where another pattern is more appropriate]
**Reference**: [Screenshot path or ASCII example, if available]
Work through patterns in groups. Offer: "Shall I draft the first batch based on what I've found in the existing specs, or do you want to define them one by one?"
After cataloging known patterns, ask:
Document gaps in the Gaps section for follow-up.
Before marking the spec as ready for review, run these checks:
1. GDD requirement coverage: Does every GDD UI Requirement that references this screen have a corresponding element in this spec? Present any gaps.
2. Pattern library alignment: Are all interaction patterns used in this spec referenced by name? If a new pattern was invented during this spec session, flag it for addition to the pattern library:
"This spec uses [pattern name], which isn't in the pattern library yet. Want to add it now, or flag it as a gap?"
3. Navigation consistency: Do the entry/exit points in this spec match the navigation map in any related specs? Flag mismatches.
4. Accessibility coverage: Does the spec address the accessibility tier
committed to in design/accessibility-requirements.md? If not, flag open questions.
5. Empty states: Does every data-dependent element have an empty state defined? Flag any that don't.
Present the check results:
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"]
When all sections are approved and written:
Update production/session-state/active.md with:
Before presenting options, state clearly:
"This spec should be validated with
/ux-reviewbefore it enters the implementation pipeline. The Pre-Production gate requires all key screen specs to have a review verdict."
Then use AskUserQuestion:
/ux-review [filename] now, or do something else first?"
/ux-review now — validate this spec"If the user picks "Design another screen first", add a note: "Reminder: run
/ux-review on all completed specs before running /gate-check pre-production."
If other UX specs link to or from this screen, note which ones should reference this spec. Do not edit those files without asking — just name them.
If the session is interrupted (compaction, crash, new session):
production/session-state/active.md — it records the current screen
and which sections are complete.design/ux/[filename].md — sections with real content are done;
sections with [To be designed] still need work.This is why incremental writing matters: every approved section survives any disruption.
This skill uses ux-designer as the primary agent (set in frontmatter). For
specific sub-topics, additional context or coordination may be needed:
| Topic | Coordinate with |
|---|---|
| Visual aesthetics, color, layout feel | art-director — UX spec defines zones; art defines how they look |
| Implementation feasibility (engine constraints) | ui-programmer — before finalizing component inventory |
| Gameplay data requirements | game-designer — when data ownership is unclear |
| Narrative/lore visible in the UI | narrative-director — for flavor text, item names, lore panels |
| Accessibility tier decisions | Handled by this session — owned by ux-designer |
When delegating to another agent via the Task tool:
This skill follows the collaborative design principle at every step:
Aesthetic deference: When layout or visual choices come down to personal taste, present the options and ask. Do not select a layout because it is "standard" — always confirm. The user is the creative director.
Conflict surfacing: When a GDD requirement and the available screen real estate conflict, surface the conflict and present resolution options. Never silently drop a requirement. Never silently expand the layout without flagging it.
Never auto-generate the full spec and present it as a fait accompli. Never write a section without user approval. Never contradict an existing approved UX spec without flagging the conflict. Always show where decisions come from (GDD requirements, player journey, user choices).
Verdict: COMPLETE — UX spec written and approved section by section.
/ux-review [filename] to validate this spec before it enters the implementation pipeline/ux-design [next-screen] to continue designing remaining screens or flows/gate-check pre-production once all key screens have approved UX specs