agentleFS
chuanglibschuanglibs/Claude-Code-Game-Studios-Codex/.claude/skills/ux-design/SKILL.md

ux-design

Skill1 starsChanged 59 days agoMITView on GitHub

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.

26 other projects use a version of this, 8 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use app-brief, design-from-app and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • StijnusSkill

    app-brief

    One-page brief (docs/BRIEF.md) for a new macOS app, written before any code. Use when the user has an app idea, wants to replace an app they pay for, or the research and clone skills are done.

    Also in 3 projects that use this

  • StijnusSkill

    design-from-app

    Rebuild the look of an app the user likes as a native SwiftUI design kit, by measuring its screenshots (sizes, spacing, type, colors, icons), building its parts, and comparing pixel by pixel until they match. Use when the user names an app whose look they want, shares screenshots of one, or says "make it look like X".

    Also in 3 projects that use this

  • launchapp-devSkill

    layout-grid

    Define responsive layout grid systems with columns, gutters, margins, and breakpoint behavior.

    Also in 3 projects that use this

  • MohamedAbdallah-14Skill

    app-icon

    Generate an app icon from a single 1024² master and fan out to iOS (AppIcon.appiconset with squircle-ready 1024 opaque), Android (adaptive foreground + background + Android 13 monochrome), PWA (192/512 + 512 maskable with 80% safe zone), and visionOS (3-layer parallax).

    Also in 3 projects that use this

  • timeplus-ioSkill

    build-and-verify

    Build, compile, run server/client/cluster, execute unit/stateless/SQL tests, verify results, and troubleshoot build/test failures. Make sure to use this skill whenever the user mentions building, compiling, ninja, cmake, running tests, test failures, starting the server, or pre-commit checks, even if they just say 'it doesn't build' or 'the test broke'.

    Also in 3 projects that use this

  • CrystalPlatformsSkill

    agent-cli

    Design and audit CLIs that AI agents (Claude Code, Codex, automated pipelines) consume. Applies ten agent-native principles in two tiers — Tier 1 table stakes (non-interactive default, structured output, errors that enumerate, safe retries, bounded responses) and Tier 2 compounding (cross-CLI vocabulary, three-layer introspection, async-aware execution, persistent profiles, two-way I/O) — with a Blocker / Friction / Optimization severity rubric across six command classes (read, mutate, stream, bootstrap, async, config). Use when building, reviewing, or specifying a CLI for agent invocation, mentions argparse, click, cobra, clap, commander, yargs, oclif, thor, agent-friendly or agent-native CLI design, --json output, exit codes, idempotent commands, --wait flags, agent-context introspection, persistent profiles, --deliver routing, --force bypass, vocabulary consistency, or repos with cli.py, main.go, src/cli.rs, bin/<tool>. Skip general shell scripting and human-only TUIs.

    Also in 3 projects that use this

  • +1 more from Stijnus

The file

Show its rules and text

We split this skill into the rules it gives an agent

62 rules. 0 are common, 36 are distinctive, and 26 are very specific to this project.

  • 0

    Common

    Most of the 26 edited versions we read keep these.

  • 36

    Distinctive

    This author's own choices. Worth a look.

  • 26

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When this skill is invoked:

    line 11
  2. Very specific:

    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 …

    line 28
  3. Distinctive:

    Read all relevant context before asking the user anything.

    line 35
  4. Very specific:

    Game concept: Read design/gdd/game-concept.md — if missing, warn:

    line 40
  5. Very specific:

    Read design/player-journey.md if it exists.

    line 47
  6. Distinctive:

    If the player journey file does not exist, note the gap and proceed:

    line 53
  7. Distinctive:

    If designing the HUD, read ALL GDD UI Requirements sections — the HUD aggregates requirements from every system.

    line 69
  8. Very specific:

    If design/ux/interaction-patterns.md exists, read the pattern catalog index (the list of pattern names and their one-line descriptions).

    line 80
  9. Very specific:

    Check for design/art/art-bible.md.

    line 87
  10. Very specific:

    Check for design/accessibility-requirements.md.

    line 92
  11. Very specific:

    Read .claude/docs/technical-preferences.md and extract the ## Input & Platform section.

    line 97
  12. Very specific:

    If the section is unconfigured ([TO BE CONFIGURED]), ask once:

    line 107
  13. Distinctive:

    Before any design work, present a brief summary to the user:

    line 118
  14. Distinctive:

    Before creating a skeleton, check if the target output file already exists.

    line 135
  15. Distinctive:

    Read the file in full

    line 140
  16. Very specific:

    Use Edit to fill placeholders in-place rather than creating a new skeleton

    line 161
  17. Very specific:

    Ask: "May I create the skeleton file at design/ux/[filename].md?"

    line 173
  18. Very specific:

    After writing the skeleton, update production/session-state/active.md with:

    line 399
  19. Very specific:

    Questions: Ask what is needed to draft this section.

    line 416
  20. Distinctive:

    Draft: Write the section content in conversation for review.

    line 421
  21. Distinctive:

    Do not proceed to step 7 until the user selects "Yes".

    line 426
  22. Very specific:

    Write: Use AskUserQuestion: "May I write the [section name] section to [filepath]?"

    line 427
  23. Very specific:

    After writing each section, update production/session-state/active.md.

    line 431
  24. Distinctive:

    Ask the user to list every piece of information this screen must communicate.

    line 502
  25. Very specific:

    Use AskUserQuestion to capture the choice:

    line 512
  26. Distinctive:

    If it uses an existing pattern from the library (reference by pattern name)

    line 521
  27. Distinctive:

    If it introduces a new pattern (flag for later addition to the library)

    line 522
  28. Very specific:

    Use AskUserQuestion: "Want an ASCII wireframe as part of this spec?"

    line 526
  29. Distinctive:

    If yes, produce the wireframe in conversation first.

    line 528
  30. Very specific:

    Use the input methods loaded from technical-preferences.md in Phase 2h — do not ask the user again.

    line 565
  31. Distinctive:

    If no accessibility tier has been defined for this project, note the gap in the UX spec's Open Questions section:

    line 644
  32. Distinctive:

    Document constraints that affect how this screen behaves when text is translated.

    line 652
  33. Very specific:

    Write at least 5 specific, testable criteria that a QA tester can verify without reading any other design document.

    line 665
  34. Distinctive:

    Format: Use checkboxes. Each criterion must be verifiable by a human tester:

    line 667
  35. Very specific:

    Use AskUserQuestion to confirm:

    line 685
  36. Distinctive:

    Ask the user to describe the game's relationship with on-screen information in 1-2 sentences.

    line 698
  37. Distinctive:

    If a proposed element conflicts with the stated philosophy, surface that conflict.

    line 708
  38. Very specific:

    Use AskUserQuestion to step through items in groups of 3-4, not all at once.

    line 731
  39. Distinctive:

    Conflict check: If the information philosophy (Section A) says "nearly HUD-free" but the Must Show list is growing long, surface the …

    line 734
  40. Distinctive:

    Only after the information architecture is approved, design layout zones.

    line 744
  41. Distinctive:

    Update behavior (real-time, event-driven, player-queried)

    line 763
  42. Distinctive:

    Ask: "Are there patterns you know exist but aren't in existing specs yet?

    line 798
  43. Distinctive:

    After cataloging known patterns, ask:

    line 835
  44. Distinctive:

    Document gaps in the Gaps section for follow-up.

    line 841
  45. Distinctive:

    Before marking the spec as ready for review, run these checks:

    line 847
  46. Distinctive:

    3. Navigation consistency: Do the entry/exit points in this spec match the navigation map in any related specs?

    line 859
  47. Distinctive:

    When all sections are approved and written:

    line 880
  48. Distinctive:

    Before presenting options, state clearly:

    line 893
  49. Very specific:

    If the user picks "Design another screen first", add a note: "Reminder: run /ux-review on all completed specs before running /gate-check …

    line 907
  50. Distinctive:

    If other UX specs link to or from this screen, note which ones should reference this spec.

    line 912
  51. Distinctive:

    If the session is interrupted (compaction, crash, new session):

    line 919
  52. Very specific:

    Read production/session-state/active.md — it records the current screen and which sections are complete.

    line 921
  53. Very specific:

    Read design/ux/[filename].md — sections with real content are done.

    line 923
  54. Distinctive:

    When delegating to another agent via the Task tool:

    line 945
  55. Distinctive:

    "May I write to [filepath]?": before the skeleton and before each section write

    line 964
  56. Distinctive:

    Session state updates: After every section write

    line 966
  57. Distinctive:

    Aesthetic deference: When layout or visual choices come down to personal taste, present the options and ask.

    line 968
  58. Distinctive:

    Conflict surfacing: When a GDD requirement and the available screen real estate conflict, surface the conflict and present resolution …

    line 972
  59. Distinctive:

    Never: write a section without user approval.

    line 977
  60. Very specific:

    Run /ux-review [filename] to validate this spec before it enters the implementation pipeline

    line 987
  61. Very specific:

    Run /ux-design [next-screen] to continue designing remaining screens or flows

    line 988
  62. Very specific:

    Run /gate-check pre-production once all key screens have approved UX specs

    line 989

“Common” is measured: kept by at least 6 in 10 of the 26 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

When this skill is invoked:

1. Parse Arguments & Determine Mode

Three authoring modes exist based on the argument:

ArgumentModeOutput file
hudHUD designdesign/ux/hud.md
patternsInteraction pattern librarydesign/ux/interaction-patterns.md
Any other value (e.g., main-menu, inventory)UX spec for a screen or flowdesign/ux/[argument].md
No argumentAsk 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:

SectionStatus
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: 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".
  7. 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 SourceTriggerPlayer carries this context
[screen/event][how][state/data they arrive with]
Exit DestinationTriggerNotes
[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.
  • Use AskUserQuestion to capture the choice:
    • "Which zone arrangement fits best?"
    • Options: [the 2-3 named arrangements you just presented] + "None — 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)

Sub-section 4 — ASCII Wireframe:

  • Offer to generate an ASCII wireframe based on the zone layout and component list.
  • Use AskUserQuestion: "Want an ASCII wireframe as part of this spec?"
    • Options: "Yes, include one", "No, I'll attach a separate file"
  • If yes, produce the wireframe in conversation first. Ask for feedback before writing it to file.

Section D: States & Variants

Guide the user to think beyond the happy path.

Questions to ask (work through these one at a time):

  • "What does this screen look like the very first time a player sees it, when there is no data yet? (empty state)"
  • "What happens when something goes wrong — an error, a failed action, a missing resource? (error state)"
  • "Is there ever a loading wait on this screen? If so, what does it show? (loading state)"
  • "Are there any player progression states that change what this screen shows? For example, locked content, premium content, or tutorial-mode overlays?"
  • "Does this screen behave differently on any supported platform? (platform variant)"

Present the collected states as a table for approval:

State / VariantTriggerWhat Changes
DefaultNormal load—
EmptyNo data available[content area description]
[etc.][trigger][changes]

Section E: Interaction Map

For each interactive component identified in the Layout Specification, define:

  • The action (tap, click, press, hold, scroll, drag)
  • The platform input(s) that trigger it (mouse click, gamepad A, keyboard Enter)
  • The immediate feedback (visual, audio, haptic)
  • The outcome (navigation target, state change, data write)

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.


Section E2: Events Fired

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:

  • "For each action, should the game fire an analytics event, trigger a game-state change, or both?"
  • "Are there any actions that should NOT fire an event — and is that a deliberate choice?"

Present as a table alongside the Interaction Map:

Player ActionEvent FiredPayload / 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.


Section E3: Transitions & Animations

Specify how the screen enters and exits, and how it responds to state changes.

Questions to ask:

  • "How does this screen appear? (fade in, slide from right, instant pop, scale from button)"
  • "How does it dismiss? (fade out, slide back, cut)"
  • "Are there any in-screen state transitions that need animation? (loading spinner, success state, error flash)"
  • "Is there any animation that could cause motion sickness — and does the game have a reduced-motion option?"

Minimum required:

  • Screen enter transition
  • Screen exit transition
  • At least one state-change animation if the screen has multiple states

Section F: Data Requirements

Cross-reference the GDD UI Requirements sections gathered in Phase 2.

For each piece of information the screen displays, ask:

  • "Where does this data come from? Which system owns it?"
  • "Does this screen need to write data back, or is it read-only?"
  • "Is any of this data time-sensitive or real-time? (health bars, cooldown timers)"

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:

DataSource SystemRead / WriteNotes
[item][system]Read—
[item][system]Write[concern if any]

Section G: Accessibility

Cross-reference design/accessibility-requirements.md if it exists.

Walk through the ux-designer agent's standard checklist for this screen:

  • Keyboard-only navigation path through all interactive elements
  • Gamepad navigation order (if applicable)
  • Text contrast and minimum readable font sizes
  • Color-independent communication (no information conveyed by color alone)
  • Screen reader considerations for any non-text elements
  • Any motion or animation that needs a reduced-motion alternative

If no accessibility tier has been defined for this project, note the gap in the UX spec's Open Questions section:

"Accessibility tier not yet defined — consider WCAG-AA as a baseline. Run /gate-check to see whether this blocks any phase gates." Then continue to the next section without stopping.


Section H: Localization Considerations

Document constraints that affect how this screen behaves when text is translated.

Questions to ask:

  • "Which text elements on this screen are the longest? What is the maximum character count that fits the layout?"
  • "Are there any elements where text length is layout-critical — e.g., a button label that must stay on one line?"
  • "Are there any elements that display numbers, dates, or currencies that need locale-specific formatting?"

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.


Section I: Acceptance Criteria

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:

  • 1 performance criterion (load/open time)
  • 1 navigation criterion (at least one entry or exit path verified)
  • 1 error/empty state criterion
  • 1 accessibility criterion (per committed tier)
  • 1 criterion specific to this screen's core purpose

Use AskUserQuestion to confirm:

  • "Do these acceptance criteria cover what would make this screen 'done' for your QA process?"
  • Options: "Yes — these are solid", "Add one more criterion", "Remove or rephrase one"

Section Guidance: HUD Design Mode

HUD design follows a different order from UX spec mode. Begin with philosophy; do not touch layout until the information architecture is complete.

Section A: HUD Philosophy

Ask the user to describe the game's relationship with on-screen information in 1-2 sentences.

Offer framing examples to help:

  • "Nearly HUD-free — atmosphere requires unobstructed immersion (e.g., Hollow Knight, Firewatch)"
  • "Minimal but present — only critical information visible, everything else contextual (e.g., Dark Souls)"
  • "Information-dense — all decision-relevant data always visible (e.g., Diablo IV, StarCraft II)"
  • "Adaptive — HUD density responds to combat state, exploration mode, menus (e.g., God of War)"

This philosophy becomes the design constraint for every subsequent HUD decision. If a proposed element conflicts with the stated philosophy, surface that conflict.


Section B: Information Architecture

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:

CategoryDescription
Must ShowAlways visible, player needs it for core decisions
ContextualVisible only when relevant (in combat, near interactable, etc.)
On DemandPlayer must actively request it (toggle, hold button)
HiddenCommunicated 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."


Section C: Layout Zones

Only after the information architecture is approved, design layout zones.

Base layout on:

  • Which items are Must Show (they drive the permanent zone decisions)
  • Where player attention naturally goes during gameplay (center-screen for action games, corners for strategy games)
  • Platform and aspect ratio targets

Offer 2-3 zone arrangements. Include rationale based on the HUD philosophy and the categorization from Section B.


Section D: HUD Elements

For each element in the layout, specify:

  • Element name and category (Must Show / Contextual / On Demand)
  • Content displayed
  • Visual form (bar, number, icon, counter, map)
  • Update behavior (real-time, event-driven, player-queried)
  • Contextual trigger (if not always visible)
  • Animation behavior (does it pulse when low? Fade in? Slam in?)

Work element by element. Reference the interaction pattern library if relevant patterns exist for status displays, resource bars, or cooldown indicators.


Sections E, F, G: Dynamic Behaviors, Platform Variants, Accessibility

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:

  • Dynamic Behaviors: what causes the HUD to change density mid-gameplay?
  • Platform Variants: does mobile/console require different element sizes or positions?

Section Guidance: Interaction Pattern Library Mode

Pattern library authoring is additive and catalog-driven, not linear.

Phase 1: Catalog Existing Patterns

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:"

  • [Pattern name]: used in [screen], [screen]
  • [etc.]

Ask: "Are there patterns you know exist but aren't in existing specs yet? List any additional ones now."


Phase 2: Formalize Each Pattern

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. Use AskUserQuestion:

  • "How do you want to work through these patterns?"
  • Options: "Draft the first batch from existing specs (faster)", "Define them one by one (more control)", "Start with the most-used pattern first"

Phase 3: Identify Gaps

After cataloging known patterns, ask:

  • "Are there screens or interactions planned that would need patterns not yet in this library?"
  • "Are there any patterns in existing specs that feel inconsistent with each other and should be consolidated?"

Document gaps in the Gaps section for follow-up.


5. Cross-Reference Check

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: Use AskUserQuestion:

  • "This spec uses [pattern name], which isn't in the pattern library yet. What should we do?"
  • Options: "Add it to the pattern library now", "Flag it as a gap and continue", "Skip — this pattern is one-off"

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"]

6. Handoff

When all sections are approved and written:

6a: Update Session State

Update production/session-state/active.md with:

  • Task: [screen-name] UX spec
  • Status: Complete (or In Review)
  • File: design/ux/[filename].md
  • Sections: All written
  • Next: [suggestion]

6b: Suggest Next Step

Before presenting options, state clearly:

"This spec should be validated with /ux-review before it enters the implementation pipeline. The Pre-Production gate requires all key screen specs to have a review verdict."

Then use AskUserQuestion:

  • "Run /ux-review [filename] now, or do something else first?"
    • Options:
      • "Run /ux-review now — validate this spec"
      • "Design another screen first, then review all specs together"
      • "Update the interaction pattern library with new patterns from this spec"
      • "Stop here for this session"

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

6c: Cross-Link Related Specs

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.


7. Recovery & Resume

If the session is interrupted (compaction, crash, new session):

  1. Read production/session-state/active.md — it records the current screen and which sections are complete.
  2. Read design/ux/[filename].md — sections with real content are done; sections with [To be designed] still need work.
  3. Resume from the next incomplete section — no need to re-discuss completed ones.

This is why incremental writing matters: every approved section survives any disruption.


8. Specialist Agent Routing

This skill uses ux-designer as the primary agent (set in frontmatter). For specific sub-topics, additional context or coordination may be needed:

TopicCoordinate with
Visual aesthetics, color, layout feelart-director — UX spec defines zones; art defines how they look
Implementation feasibility (engine constraints)ui-programmer — before finalizing component inventory
Gameplay data requirementsgame-designer — when data ownership is unclear
Narrative/lore visible in the UInarrative-director — for flavor text, item names, lore panels
Accessibility tier decisionsHandled by this session — owned by ux-designer

When delegating to another agent via the Task tool:

  • Provide: screen name, game concept summary, the specific question needing expert input
  • The agent returns analysis to this session
  • This session presents the agent's output to the user
  • The user decides; this session writes to file
  • Agents do NOT write to files directly — this session owns all file writes

Collaborative Protocol

This skill follows the collaborative design principle at every step:

  1. Question -> Options -> Decision -> Draft -> Approval for every section
  2. AskUserQuestion at every decision point (Explain -> Capture pattern):
    • Phase 2: "Ready to start, or need more context?"
    • Phase 3: "May I create the skeleton?"
    • Phase 4 (each section): design questions, approach options, draft approval
    • Phase 5: "Run cross-reference check? What's next?"
  3. "May I write to [filepath]?" before the skeleton and before each section write
  4. Incremental writing: Each section is written to file immediately after approval
  5. Session state updates: After every section write

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.


Recommended Next Steps

  • Run /ux-review [filename] to validate this spec before it enters the implementation pipeline
  • Run /ux-design [next-screen] to continue designing remaining screens or flows
  • Run /gate-check pre-production once all key screens have approved UX specs

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.