ux-design skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,docs.density

Resolved above — use as-is. No block → defaults in .claude/docs/config-resolution.md.

When this skill is invoked:

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

Authoring guidance: the skeletons below are self-contained — author from them directly. When a section needs depth (worked examples, pattern catalogs, accessibility criteria), the matching guide has it:

Load a guide per-section, never whole — each is organised by section and the pointers in the templates name the exact section to read.

workflow (see .claude/docs/workflow-modes.md):

• full — a UX spec is required per screen.
• standard — core screens only (main menu, HUD, primary game loop).
• minimal — not required. Can still be run voluntarily.

docs.density — it controls per-section depth, where workflow controls which screens are specced. modes.rigor sets both together; set docs.density explicitly to vary depth alone: terse = wireframe descriptions + interaction bullets; balanced = wireframes + paragraph descriptions of flows (default); thorough = full prose including user-research summaries and alternative flow considerations. Apply it to every section you author.

1. Parse Arguments & Determine Mode

Four authoring modes exist based on the argument:

accessibility is the only mode that writes outside design/ux/. Its

output is a project-wide standard the per-screen specs consult, not a spec for

one screen — .claude/docs/workflow-catalog.yaml, the Pre-Production and

Polish gates, and /architecture-review all check

design/accessibility-requirements.md at that exact path. Do not "tidy" it

under design/ux/: every one of those checks would stop matching, and the

Technical Setup → Pre-Production gate would become unpassable again.

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", "The project-wide accessibility requirements", "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. Author it from the template at .claude/docs/templates/player-journey.md to establish player context for this screen."

Do not tell the user to "run /ux-design Phase 2b" to create it. Phase 2b

is this step — the one that reads the file. That remediation is circular: it

sends the user back to the check that just reported the gap. No skill

writes design/player-journey.md; it is hand-authored from its template.

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, you need the UI Requirements of every system — the HUD aggregates them. Collect them with one scan rather than opening each GDD:

Grep pattern="^#+ .*UI Requirements" glob="design/gdd/*.md" output_mode="content" -A 20

Establish the denominator first (glob design/gdd/.md, count N) and check the match count against it. A GDD with no UI Requirements section is not a GDD with no UI needs** — it may predate the section. List the unmatched ones and confirm with the user that they are genuinely headless before excluding them from the HUD's requirement set; a HUD that silently omits a system's readout is the exact failure this aggregation exists to prevent.

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 the platform block from project.yaml; if project.yaml has no platform block, fall back to the ## Input & Platform section of .claude/docs/technical-preferences.md. Store these values for use throughout the skill — they drive the Interaction Map and inform accessibility requirements:

project.yaml, derive it: keyboard/mouse if PC or Web is in targets; gamepad if gamepad support is Full/Partial; touch if touch support is Full/Partial; plus the primary input. When falling back to technical-preferences.md, use its explicit Input Methods field.

• Primary Input — platform.primary_input — the dominant input for this game
• Gamepad Support — platform.gamepad_support — Full / Partial / None
• Touch Support — platform.touch_support — Full / Partial / None
• Target Platforms — platform.targets — for safe zone and aspect ratio decisions
• Input Methods — the set of supported methods. When reading from

If neither source is configured, ask once: