ux-design

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. Ask the user directly in plain text: - "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." ### 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 `docs/studio/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 apply_patch 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) ```markdown # 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 ```markdown # 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 ```markdown # 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 ``` 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. Ask the user directly in plain text 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 ask the user directly in plain text 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**: "Does this capture it? Any changes before I write it to the file?" 7. **Write**: Use apply_patch to replace the `[To be designed]` placeholder with approved content. Confirm the write. 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 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. **Sub-section 2 — Layout 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. - Ask: "Do any of these match your mental image, or shall we build a custom arrangement?" **Sub-section 3 — Component Inventory**: - 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)