mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.0 — one config file, and a process weight you choose
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5
Claude Opus 5
parent
984023ddac
commit
d05699707f
+207
-429
@@ -1,29 +1,73 @@
|
||||
---
|
||||
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'"
|
||||
description: "Section-by-section UX spec authoring for a screen, flow or HUD. Reads the player journey to provide context; also project-wide accessibility."
|
||||
argument-hint: "[screen/flow name] or 'hud' or 'patterns' or 'accessibility'"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Task
|
||||
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Agent
|
||||
model: sonnet
|
||||
agent: ux-designer
|
||||
---
|
||||
|
||||
!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && 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;
|
||||
`automation_always_ask` 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:
|
||||
|
||||
| Producing | Guide |
|
||||
|---|---|
|
||||
| UX spec | `.claude/docs/templates/guidance/ux-spec-guide.md` |
|
||||
| HUD design | `.claude/docs/templates/guidance/hud-design-guide.md` |
|
||||
| Interaction patterns | `.claude/docs/templates/guidance/interaction-pattern-library-guide.md` (routes to three topic files) |
|
||||
| Accessibility requirements | `.claude/docs/templates/guidance/accessibility-requirements-guide.md` |
|
||||
|
||||
**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
|
||||
|
||||
Three authoring modes exist based on the argument:
|
||||
Four 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` |
|
||||
| `accessibility` | Project-wide accessibility requirements | `design/accessibility-requirements.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) |
|
||||
|
||||
> **`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", "I'm not sure — help me figure it out"
|
||||
- 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`).
|
||||
@@ -56,7 +100,12 @@ If the player journey file does not exist, note the gap and proceed:
|
||||
> 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."
|
||||
> "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
|
||||
|
||||
@@ -66,8 +115,19 @@ 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.
|
||||
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
|
||||
|
||||
@@ -94,17 +154,23 @@ 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:
|
||||
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:
|
||||
|
||||
- **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
|
||||
- **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
|
||||
`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.
|
||||
|
||||
If the section is unconfigured (`[TO BE CONFIGURED]`), ask once:
|
||||
If neither source is 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"
|
||||
>
|
||||
@@ -124,7 +190,7 @@ Before any design work, present a brief summary to the user:
|
||||
> - 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"]
|
||||
> - Input methods: [derived from the `project.yaml` platform block, or "asked above"]
|
||||
|
||||
Then ask: "Anything else I should read before we start, or shall we proceed?"
|
||||
|
||||
@@ -170,7 +236,9 @@ Proceed to Phase 3 (Create File Skeleton) as normal.
|
||||
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`?"
|
||||
Ask: "May I create the skeleton file at `design/ux/[filename].md`?" — except in
|
||||
`accessibility` mode, where the path is `design/accessibility-requirements.md`
|
||||
(see the mode table in Section 1; it is deliberately not under `design/ux/`).
|
||||
|
||||
---
|
||||
|
||||
@@ -396,10 +464,102 @@ Ask: "May I create the skeleton file at `design/ux/[filename].md`?"
|
||||
|
||||
---
|
||||
|
||||
### Skeleton for Accessibility Requirements
|
||||
|
||||
Section list mirrors `.claude/docs/templates/accessibility-requirements.md` — if
|
||||
the template gains or loses a section, this skeleton follows it, not the reverse.
|
||||
|
||||
```markdown
|
||||
# Accessibility Requirements
|
||||
|
||||
> **Status**: In Design
|
||||
> **Author**: [user + ux-designer]
|
||||
> **Last Updated**: [today's date]
|
||||
> **Template**: Accessibility Requirements
|
||||
|
||||
## Accessibility Tier Definition
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Visual Accessibility
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Motor Accessibility
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Cognitive Accessibility
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Auditory Accessibility
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Platform Accessibility API Integration
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Per-Feature Accessibility Matrix
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Test Plan
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Known Intentional Limitations
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Audit History
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## External Resources
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
[To be designed]
|
||||
```
|
||||
|
||||
> **The tier commitment is the gated part.** `gate-pre-production.md` requires
|
||||
> the file to exist *with an accessibility tier committed*, and
|
||||
> `gate-production.md` checks that tier is addressed in every key screen spec.
|
||||
> A skeleton whose Tier Definition is still `[To be designed]` satisfies the
|
||||
> glob but not the gate — author that section first.
|
||||
|
||||
---
|
||||
|
||||
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
|
||||
- File: design/ux/[filename].md (or `design/accessibility-requirements.md` in `accessibility` mode)
|
||||
|
||||
---
|
||||
|
||||
@@ -432,413 +592,27 @@ 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.
|
||||
- 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 / Variant | Trigger | What Changes |
|
||||
|-----------------|---------|--------------|
|
||||
| Default | Normal load | — |
|
||||
| Empty | No 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 Action | Event Fired | Payload / 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:
|
||||
|
||||
| Data | Source System | Read / Write | Notes |
|
||||
|------|--------------|--------------|-------|
|
||||
| [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:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| **Must Show** | Always visible, player needs it for core decisions |
|
||||
| **Contextual** | Visible only when relevant (in combat, near interactable, etc.) |
|
||||
| **On Demand** | Player must actively request it (toggle, hold button) |
|
||||
| **Hidden** | Communicated 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:
|
||||
|
||||
```markdown
|
||||
### [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.
|
||||
### Section guidance — read the ONE file for the active mode
|
||||
|
||||
Per-section authoring guidance lives in its own file per mode. **When you reach
|
||||
Phase 4, read only the file matching the mode resolved in Section 1; never load
|
||||
the other two.**
|
||||
|
||||
| Mode | Guidance file |
|
||||
|------|---------------|
|
||||
| UX Spec (screen or flow) | `.claude/skills/ux-design/references/sections-ux-spec.md` |
|
||||
| HUD Design | `.claude/skills/ux-design/references/sections-hud.md` |
|
||||
| Interaction Pattern Library | `.claude/skills/ux-design/references/sections-patterns.md` |
|
||||
| Accessibility Requirements | `.claude/docs/templates/guidance/accessibility-requirements-guide.md` |
|
||||
|
||||
> The accessibility guidance lives under `templates/guidance/` rather than this
|
||||
> skill's `references/` because the template it documents
|
||||
> (`.claude/docs/templates/accessibility-requirements.md`) is consumed by
|
||||
> `/ux-review` and the gate files too. Same rule applies: load only the part
|
||||
> covering the section you are authoring, never the whole file.
|
||||
|
||||
Apply `docs.density` (Section 1) to whatever that file tells you to author — it
|
||||
controls the depth of each section, not which sections exist.
|
||||
|
||||
---
|
||||
|
||||
@@ -942,7 +716,7 @@ specific sub-topics, additional context or coordination may be needed:
|
||||
| Narrative/lore visible in the UI | `narrative-director` — for flavor text, item names, lore panels |
|
||||
| Accessibility tier decisions | Handled by this session — owned by ux-designer |
|
||||
|
||||
When delegating to another agent via the Task tool:
|
||||
When delegating to another agent via the `Agent` 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
|
||||
@@ -953,6 +727,10 @@ When delegating to another agent via the Task tool:
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
**In `collaborative` mode (the default).** For `guided` and `autonomous` modes,
|
||||
see the per-mode rules in `.claude/docs/automation-modes.md` — the steps below
|
||||
describe what collaborative mode requires, not what applies universally.
|
||||
|
||||
This skill follows the collaborative design principle at every step:
|
||||
|
||||
1. **Question -> Options -> Decision -> Draft -> Approval** for every section
|
||||
|
||||
Reference in New Issue
Block a user