ux-design

User Guide

• When to use: Guided, section-by-section UX spec authoring for a screen, flow, or HUD. Supports both game projects (player journey, HUD, game screens) and product projects (user flows, CLI interaction, API consumer journey). Reads concept doc and relevant CDDs for context-aware design guidance.
• Inputs: Command arguments: /ux-design [screen/flow name] or 'hud' or 'patterns; project artifacts referenced below; user decisions and approvals before writes.
• Outputs: Primary artifacts, reports, or conversation guidance described below; write files only after user approval.
• Memory-bank writes: None.
• Next steps: Follow the workflow hand-off or next-step guidance below; recommendations do not auto-run and require explicit user command/approval.

When this skill is invoked:

Domain detection. Read the concept document to determine domain:

• design/cdd/game-concept.md → [游戏专用] Game mode
• design/cdd/product-concept.md → [通用产品] Product mode

1. Parse Arguments & Determine Mode

[游戏专用] Game modes:

Argument	Mode	Output file
hud	HUD design	design/ux/hud.md
patterns	Interaction pattern library	design/ux/interaction-patterns.md
Any other value	UX spec for a screen or flow	design/ux/[argument].md
No argument	Ask the user	(see below)

[通用产品] Product modes:

Argument	Mode	Output file
patterns	Interaction pattern library	design/ux/interaction-patterns.md
workflow or flow name	UX spec for a user workflow	design/ux/[argument].md
cli	CLI interaction design	design/ux/cli-interaction.md
api	API consumer journey	design/ux/api-consumer-journey.md
Any other value	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", "The game HUD", "The interaction pattern library", "I'm not sure"
• [通用产品] "What are we designing today?" Options: "A specific screen or user flow", "CLI interaction design", "API consumer journey", "The interaction pattern library", "I'm not sure"

If the user selects a screen or flow 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

[通用场景] Read the concept document for the detected domain:

• [游戏专用] Read design/cdd/game-concept.md — if missing, warn and continue
• [通用产品] Read design/cdd/product-concept.md — if missing, warn and continue

2b: User Journey

[游戏专用] Read design/player-journey.md if it exists. Extract:

• Which journey phase(s) does this screen appear in?
• What is the player's emotional state on arrival?
• What player need is this screen serving?
• What critical moments does this screen deliver?

[通用产品] Read the User Journey section of the product concept doc. Extract:

• Which workflow step(s) does this screen/flow belong to?
• What is the user's goal at this point?
• What user need is this screen/flow serving?
• What is the primary JTBD (Job to Be Done) at this interaction point?

If no journey information exists, note the gap and proceed with assumptions.

2c: CDD UI Requirements

Glob design/cdd/*.md and grep for UI Requirements sections. Read any CDD whose UI Requirements section references this screen by name or category.

These CDD 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 CDD 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: Visual / Product Style References

For game projects, check for design/art/art-bible.md. If found, read the visual direction section. UX layout must align with the aesthetic commitments already made.

For product projects, check for design/brand/style-guide.md. If found, read brand tone, visual standards, docs imagery rules, and accessibility-constrained color/typography commitments. For UI-heavy products, also check design/design-system.md; if it exists, read component patterns and state standards before writing screen or workflow specs.

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 standards/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 / CLI / API]
• Journey phase(s) / Workflow step(s): [from concept doc or journey map, or "unknown — no journey map"]
• CDD requirements feeding this spec: [count and names, or "none found"]
• Related screens/flows 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]
Purpose & User Need	...
User Context & 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 & User Need

[To be designed]

---

## User Context on Arrival

[To be designed]

---

## Navigation / Workflow 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: "Does this capture it? Any changes before I write it to the file?"
7. Write: Use Edit to replace the [To be designed] placeholder with approved content. Confirm the write.

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

---

Section Guidance: UX Spec Mode

Section A: Purpose & User Need

This section is the foundation. Every other decision flows from it.

[Game] — Purpose & Player Need

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.

[Product] — Purpose & User Need

Questions to ask:

• "What user goal does this screen, flow, or command serve? What is the user trying to ACCOMPLISH?"
• "What Job to Be Done (JTBD) does this fulfill? Why would the user choose this over an alternative?"
• "What would go wrong if this interaction didn't exist or was hard to use?"
• "Complete this sentence: 'The user interacts with this to ___.' "

Cross-reference the product concept doc gathered in Phase 2. The stated purpose must align with the product principles and MVP scope.

For CLI: focus on the task the user is scripting or automating — "The user runs this command to ___ as part of a pipeline/script." For API: focus on the developer consumer — "The developer calls this endpoint to ___ and expects ___ in return." For Web/Admin: focus on the end-user goal — "The user arrives at this screen to ___ and their primary concern is ___."

---

Section B: User Context on Arrival

[Game] — Player Context

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.

[Product] — User Context

Questions to ask:

• "When in the user's workflow does this interaction happen? Is it daily, weekly, or rare one-time?"
• "What was the user doing immediately before reaching this screen or running this command?"
• "What is their state of mind — exploring the product, troubleshooting a problem, completing a routine task, time-pressured by a deadline?"
• "Is the user arriving here voluntarily (exploring, learning) or were they sent here (error recovery, support link, redirect)?"

For CLI: "Where in the user's terminal session does this command appear? Are they chaining it with other commands (piping, scripting)?" For API: "Where in the developer's integration workflow does this endpoint sit? Are they building, testing, or debugging?" For Web/Admin: "What task brought the user to this screen? What were they looking at before?"

---

Section B2: Navigation / Workflow Position

Where does this screen sit in the navigation or workflow hierarchy? This is a one-paragraph orientation map — not a full flow diagram.

[Game] — Navigation Position

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.

[Product] — Workflow Position

Questions to ask:

• "Where does this screen, command, or endpoint sit in the overall product interaction tree?"
• "Is it a top-level entry point (landing page, root command, base endpoint) or a child (sub-page, subcommand, nested resource)?"
• "Can the user reach this from more than one place or context?"

For CLI: "Where in the command tree? app command subcommand [action]" — note parent commands and sibling commands. For API: "Where in the OpenAPI path tree? GET /api/v1/[resource]/[sub-resource]" — show relationship to parent and sibling resources. For Web/Admin: "Where in the breadcrumb or site map? Home → [section] → [page] → [this screen]" — note the information architecture position.

---

Section B3: Entry & Exit Points

Map every way the user can arrive at and leave this screen, flow, or command.

[通用场景]

Questions to ask:

• "What are all the ways a user can reach this interaction?" (List each trigger: button press, event, redirect, CLI argument combination, API path, deep link)
• "What can the user do to exit? What happens when they do?" (Back button, confirm action, timeout, event, exit code, redirect, next step in workflow)
• "Are there any exits that are one-way — where the user cannot return to this interaction without starting over?"

Present as two tables:

Entry Source	Trigger	User carries this context
[screen/event/command/endpoint]	[how]	[state/data they arrive with]

Exit Destination	Trigger	Notes
[screen/event/command/endpoint]	[how]	[any irreversible state changes]

[Product] Additional entry/exit considerations:

• CLI: Exit codes (0=success, non-zero=error types), stdout vs stderr as "exit destinations", pipe output to another command
• API: HTTP redirects (301/302), HATEOAS links as guided exits, error responses as exit paths (400/404/500)
• Web: Browser back button behavior, form submission redirects, external links, session timeout redirects
• Admin dashboard: Bulk action exits, filter-to-detail drill-down exits, export/download as an exit path

---

Section C: Layout Specification

This is the largest and most interactive section. Work through it in sub-sections.

[Game] Game Screen Layout

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.
• Ask: "Do any of these match your mental image, or shall we 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.

[Product] Product Layout — Mode-Specific

CLI Output Formatting

Sub-section 1 — Information Hierarchy:

• List every piece of information the command must emit (via stdout, stderr, or exit code).
• Rank by importance: "What is the single most important thing the user needs to see first in the output?"
• Consider whether the output is human-readable, machine-parseable (JSON, CSV), or both (e.g., --json flag).

Sub-section 2 — Output Zones:

• Define the output structure: header section, body/table, summary/footer, error channel (stderr).
• For table-formatted output: define columns, alignment, truncation rules.
• For JSON output: define the response schema (top-level keys, array shapes, nested objects).

Sub-section 3 — Component Inventory: Note which CLI patterns are in play:

• Flags (--verbose, --output json)
• Positional arguments
• Progress indicators / spinners
• Interactive prompts (confirmations, select menus)
• Color/styling conventions (if applicable)

API Response Shape Design

Sub-section 1 — Information Hierarchy:

• Define the response envelope: what top-level keys are always present? (e.g., data, meta, errors, links)
• For collections: pagination envelope (items, total, page, pageSize, nextCursor)
• For errors: consistent error format (code, message, details, requestId)

Sub-section 2 — Endpoint Layout:

• Map the URL structure: base path, resource nesting, query parameters.
• Define HTTP methods per resource and their semantics (GET=read, POST=create, PUT=replace, PATCH=update, DELETE=remove).
• Document rate limit headers and retry-after semantics.

Sub-section 3 — Component Inventory: Note which API patterns are in play:

• Pagination style (offset, cursor, page)
• Filtering and sorting parameters
• Field selection / sparse fieldsets
• Expansion / includes (?include=author,comments)
• Versioning strategy (URL path, header, query param)

Web / Admin Screen Layout

Follow the same sub-section structure as [Game] Screen Layout above, with these web-specific adjustments:

• Information Hierarchy: consider above-the-fold vs scroll-discoverable content.
• Layout Zones: propose responsive breakpoints (mobile, tablet, desktop). Consider grid vs flex layout.
• Component Inventory: reference standard web components (form fields, data tables, modals, tabs, accordions, toasts, breadcrumbs).
• ASCII Wireframe: include responsive variants — "mobile: single column, tablet: 2-column grid, desktop: sidebar + main content".

---

Section D: States & Variants

Guide the user to think beyond the happy path.

[通用场景] Shared core states:

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

• "What does this interaction look like the very first time, 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 interaction? If so, what does it show? (loading state)"

[Game] Additional game-specific states:

• "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)"

[Product] Additional product-specific states:

• Rate-limited: What does the user see when they've hit a rate limit? Include retry-after information.
• Auth-expired: What happens when the session/token expires mid-interaction? Redirect to login? Inline re-auth?
• Offline / Connectivity loss: How does the interaction behave when the network is unavailable? Graceful degradation?
• Partial data: What shows when some data loaded but other parts failed? Partial render with error indicators?
• Maintenance mode: What does the user see during planned downtime?
• Permission denied: Distinct from auth-expired — the user is authenticated but lacks the required role/permission.

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
• The input(s) that trigger it
• The immediate feedback
• The outcome (navigation target, state change, data write)