添加 claude code game studios 到项目
This commit is contained in:
panw
989
.claude/skills/ux-design/SKILL.md
Normal file
989
.claude/skills/ux-design/SKILL.md
Normal file
@@ -0,0 +1,989 @@
|
||||
---
|
||||
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'"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Task
|
||||
model: sonnet
|
||||
agent: ux-designer
|
||||
---
|
||||
|
||||
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)
|
||||
|
||||
```markdown
|
||||
# UX Spec: [Screen/Flow Name]
|
||||
|
||||
> **Status**: In Design
|
||||
> **Author**: [user + ux-designer]
|
||||
> **Last Updated**: [today's date]
|
||||
> **Journey Phase(s)**: [from context]
|
||||
> **Template**: UX Spec
|
||||
|
||||
---
|
||||
|
||||
## Purpose & Player Need
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Player Context on Arrival
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Navigation Position
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Entry & Exit Points
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Layout Specification
|
||||
|
||||
### Information Hierarchy
|
||||
|
||||
[To be designed]
|
||||
|
||||
### Layout Zones
|
||||
|
||||
[To be designed]
|
||||
|
||||
### Component Inventory
|
||||
|
||||
[To be designed]
|
||||
|
||||
### ASCII Wireframe
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## States & Variants
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Interaction Map
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Events Fired
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Transitions & Animations
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Data Requirements
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Localization Considerations
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
[To be designed]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Skeleton for HUD Design
|
||||
|
||||
```markdown
|
||||
# HUD Design
|
||||
|
||||
> **Status**: In Design
|
||||
> **Author**: [user + ux-designer]
|
||||
> **Last Updated**: [today's date]
|
||||
> **Template**: HUD Design
|
||||
|
||||
---
|
||||
|
||||
## HUD Philosophy
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Information Architecture
|
||||
|
||||
### Full Information Inventory
|
||||
|
||||
[To be designed]
|
||||
|
||||
### Categorization
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Layout Zones
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## HUD Elements
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Behaviors
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Platform & Input Variants
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
[To be designed]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Skeleton for Interaction Pattern Library
|
||||
|
||||
```markdown
|
||||
# Interaction Pattern Library
|
||||
|
||||
> **Status**: In Design
|
||||
> **Author**: [user + ux-designer]
|
||||
> **Last Updated**: [today's date]
|
||||
> **Template**: Interaction Pattern Library
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Pattern Catalog
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Patterns
|
||||
|
||||
[Individual pattern entries added here as they are defined]
|
||||
|
||||
---
|
||||
|
||||
## Gaps & Patterns Needed
|
||||
|
||||
[To be designed]
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
[To be designed]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
After writing the skeleton, update `production/session-state/active.md` with:
|
||||
- Task: Designing [screen/flow name] UX spec
|
||||
- Current section: Starting (skeleton created)
|
||||
- File: design/ux/[filename].md
|
||||
|
||||
---
|
||||
|
||||
## 4. Section-by-Section Authoring
|
||||
|
||||
Walk through each section in order. For **each section**, follow this cycle:
|
||||
|
||||
```
|
||||
Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write
|
||||
```
|
||||
|
||||
1. **Context**: State what this section needs to contain and surface any relevant
|
||||
constraints from context gathered in Phase 2.
|
||||
2. **Questions**: Ask what is needed to draft this section. 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 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.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
| Topic | Coordinate with |
|
||||
|-------|----------------|
|
||||
| Visual aesthetics, color, layout feel | `art-director` — UX spec defines zones; art defines how they look |
|
||||
| Implementation feasibility (engine constraints) | `ui-programmer` — before finalizing component inventory |
|
||||
| Gameplay data requirements | `game-designer` — when data ownership is unclear |
|
||||
| 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:
|
||||
- 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
|
||||
Reference in New Issue
Block a user