ux-design

name ux-design description 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. argument-hint [screen/flow name] or 'hud' or 'patterns' user-invocable true allowed-tools Read, Glob, Grep, Write, Edit, AskUserQuestion, Task model sonnet agent ux-designer When this skill is invoked: 1. Parse Arguments & Determine Mode 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 : "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" 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 ). 2. Gather Context (Read Phase) Read all relevant context before asking the user anything. The skill's value comes from arriving informed. 2a: Required Reads 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. 2b: Player Journey Read design/player-journey.md if it exists. For each relevant section, extract: 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? 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." Also add to the UX spec's Open Questions section: "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." 2c: GDD UI Requirements 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. 2d: Existing UX Specs 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. 2e: Interaction Pattern Library 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. 2f: Art Bible Check for design/art/art-bible.md . If found, read the visual direction section. UX layout must align with the aesthetic commitments already made. 2g: Accessibility Requirements Check for design/accessibility-requirements.md . If found, read it. The spec must satisfy the accessibility tier committed to there. 2h: Input Method (from Project Config) 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: 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 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-engine to 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. 2i: Present Context Summary 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?" 2b. Retrofit Mode Detection 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: 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 If the file does not exist — fresh authoring mode: Proceed to Phase 3 (Create File Skeleton) as normal. 3. Create File Skeleton 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 ?" Skeleton for UX Spec (screen or flow) # 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] Skeleton for HUD Design # 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] Skeleton for Interaction Pattern Library # 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: Task: Designing [screen/flow name] UX spec Current section: Starting (skeleton created) File: design/ux/[filename].md 4. Section-by-Section Authoring Walk through each section in order. For each section , follow this cycle: Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write Context : State what this section needs to contain and surface any relevant constraints from context gathered in Phase 2. Questions : Ask what is needed to draft this section. Use AskUserQuestion for constrained choices, conversational text for open-ended exploration. Options : Where design choices exist, present 2-4 approaches with pros/cons. Explain reasoning in conversation, then use AskUserQuestion to capture the decision. Decision : User picks an approach or provides custom direction. Draft : Write the section content in conversation for review. Flag provisional assumptions explicitly. 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". 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. After writing each section, update production/session-state/active.md . Section Guidance: UX Spec Mode Section A: Purpose & Player Need This section is the foundation. Every other decision flows from it. Questions to ask : "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 ___.' " Cross-reference the player journey context gathered in Phase 2. The stated purpose must align with the journey phase and emotional state. Section B: Player Context on Arrival Questions to ask : "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?" Offer to map this against the journey phases if the player journey doc exists. Section B2: Navigation Position 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 : "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?" Present as: "This screen lives at: [root] → [parent] → [this screen]" plus any alternate entry paths. Section B3: Entry & Exit Points Map every way the player can arrive at and leave this screen. Questions to ask : "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?" 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] Section C: Layout Specification This is the largest and most interactive section. Work through it in sub-sections: Sub-section 1 — Information Hierarchy (establish this before any layout): 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