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. 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

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:

---

Content truncated.