pixelheros/docs/examples/session-ux-pipeline.md

Example Session: UX Pipeline — /ux-design → /ux-review → /team-ui

Context: Solo indie dev, Pre-Production phase. The HUD and inventory screen are the first UI to design. The game has a player journey doc and GDDs for inventory and combat.

Starting State:

• design/gdd/inventory-system.md — complete
• design/gdd/combat-system.md — complete
• design/player-journey.md — complete (6-phase arc defined)
• No UX specs yet
• design/ux/ directory does not exist

Session Duration: ~90 minutes across two sessions (HUD design, then inventory screen) Turns: 16 Outcome: design/ux/hud.md and design/ux/screens/inventory.md created and reviewed; team-ui handed off for visual implementation

---

Part 1: HUD Design with /ux-design

Turn 1: User Starts HUD Design

User:

/ux-design hud

Turn 2: Agent Loads Context and Presents the Approach

Agent (ux-designer, via /ux-design):

Starting HUD design. Loading context...

• design/player-journey.md read — key states: Calm Exploration, Tension (threat detected), Crisis (low HP/stamina), Combat
• design/gdd/combat-system.md — HUD needs: HP bar, stamina bar, active ability cooldowns (up to 3), damage numbers
• design/gdd/inventory-system.md — HUD needs: quick slots (4 slots), active item indicator

HUD Philosophy question: What is the player's primary attention focus during play?

This determines how aggressive the HUD should be:

• Option A: Diegetic (low presence) — HP shown only when damaged, stamina shown only when draining. World-first, HUD recedes unless urgent.
• Option B: Persistent minimal — HP and stamina always visible, small and unobtrusive. Quick reference without mode-switching.
• Option C: Full tactical — All info always visible (HP, stamina, cooldowns, map, inventory slots). Player always has full awareness.

Given your survival game and "lone survivor" fantasy, A or B is most consistent with the genre.

User:

B — I want it always there but minimal. The player is always managing resources.

Turn 3: Agent Drafts HUD Philosophy Section

Agent:

HUD Philosophy draft:

Approach: Persistent Minimal The HUD is always visible but occupies minimal screen real estate. The player is a resource-managing survivor — denying HP/stamina visibility creates frustration, not tension. All critical stats are readable at a glance without interrupting exploration focus. Elements scale in visual weight when they become urgent (HP below 30% pulses, stamina at 0 flashes), then return to minimal state.

May I write this to design/ux/hud.md as the Philosophy section?

User:

Yes

Agent creates design/ux/hud.md and writes Philosophy section.

(Turns 4–7 continue the section-by-section HUD authoring: Info Architecture, Zones, Element Specs, State Machine, Visual Budget, Platform Adaptation — each drafted, approved, and written to file.)

---

Final HUD structure after all sections:

design/ux/hud.md
  - Philosophy: Persistent Minimal
  - Info Architecture: HP (top-left), Stamina (top-left below HP), Quick Slots (bottom-center),
    Ability Cooldowns (bottom-right), Damage Numbers (world-space)
  - Zones: 4 defined (top-left vitals, bottom-center interaction, bottom-right abilities, world-space)
  - Element Specs: 6 elements with dimensions, font sizes, opacity rules
  - State Machine: Calm / Tension / Crisis / Combat (4 states, transition triggers)
  - Visual Budget: Max 8% screen coverage, 3 simultaneous animations
  - Platform Adaptation: Controller (aim reticle added), Mobile (out of scope v1)

---

Part 2: Inventory Screen with /ux-design

Turn 8: User Starts Inventory Screen

User:

/ux-design screen inventory

Turn 9: Agent Scans GDD and Player Journey

Agent:

Loading context for inventory screen...

From design/gdd/inventory-system.md:

• Grid inventory, 6×8 slots
• Items have weight (affects movement) and stack size
• Player can equip, drop, inspect, split stacks

From design/player-journey.md:

• Inventory opens frequently during Calm Exploration
• Players should feel "organized and in control" when opening inventory
• Anxiety moment: "I need to decide what to drop" — should be clear, not panicked

Player Need (from journey): I need to quickly assess what I'm carrying, decide what to keep or drop, and get back into the world.

Key design question: How do players navigate to inventory actions?

• Option A: Right-click context menu — hover item → right-click → menu appears (Escape/common)
• Option B: Drag-based — drag to drop zone to drop; drag to equipment slot to equip (Stardew Valley)
• Option C: Inspect panel — click item → details panel appears on right with action buttons

User:

B — drag-based. I want it tactile.

(Turns 10–12 continue section-by-section for the inventory screen spec: Player Need, Layout Zones, States, Interaction Map, Data Requirements, Events Fired, Accessibility, Localization.)

---

Part 3: /ux-review

Turn 13: User Runs Review

User:

/ux-review design/ux/

Turn 14: Agent Reviews Both Documents

Agent (via /ux-review):

Reviewing all UX specs in design/ux/...

---

HUD Review (hud.md):

Check	Status	Notes
GDD alignment — all required elements present	✅	HP, stamina, quick slots, cooldowns all specced
State machine coverage	✅	All 4 gameplay states covered
Accessibility tier	⚠️	No colorblind mode specified for HP/stamina bars (red/yellow convention)
Visual budget	✅	8% screen coverage, within budget
Platform notes	✅	Controller variant documented

Inventory Screen Review (screens/inventory.md):

Check	Status	Notes
Player Need stated	✅
All GDD actions covered	✅	Equip, drop, inspect, split all in interaction map
Drag-drop interaction fully specified	⚠️	Drop target behavior when inventory is full not defined — what happens?
Accessibility: keyboard alternative for drag	❌	MISSING — drag-only with no keyboard path fails motor accessibility
Localization: all strings tagged	✅
Data events fired	✅	item_equipped, item_dropped, stack_split all mapped

---

Verdict: NEEDS REVISION

Two issues must be resolved before handoff to /team-ui:

1. BLOCKING (Accessibility): Inventory screen has no keyboard alternative to drag-drop. Motor accessibility requires a non-drag interaction path. Add a "press X to pick up / press X again to place" toggle, or a details panel with keyboard-accessible action buttons.

2. ADVISORY (HUD): HP/stamina bars use color alone to convey state. Add a secondary indicator (shape, icon, or pattern) for colorblind users. Can be resolved in visual pass.

3. ADVISORY (Inventory): Full-inventory drop behavior is unspecified. Resolve in GDD before implementation, or document as out-of-scope.

Turn 15: User Resolves Blocking Issue

User:

For keyboard: press F to pick up item at cursor, press F again on target slot to place it. Add this to the inventory spec.

Agent:

Adding to Interaction Map under "Keyboard / Controller Path":

Press F (or South button) to pick up item at cursor. Item enters "held" state with visual indicator. Press F again on target slot to place. Press Escape to cancel and return item.

May I write this to design/ux/screens/inventory.md and re-run the accessibility check?

User:

Yes

Agent writes update. Re-checks accessibility — now passes.

---

Part 4: Handoff to /team-ui

Turn 16: User Kicks Off Team UI

User:

/team-ui

Agent (via /team-ui):

Running UX pipeline context check...

• design/ux/hud.md — reviewed ✅
• design/ux/screens/inventory.md — reviewed ✅
• /ux-review verdict: NEEDS REVISION was resolved — current state: APPROVED ✅

Proceeding to Phase 2: Visual Design

Handing off to art-director for visual spec (color palette, typography, iconography aligned to art bible)...

(team-ui continues through visual design → layout implementation → accessibility audit → final review)

---

What This Example Demonstrates

• Context-driven design: agent reads player-journey.md to ground HUD decisions in player emotional state, not just feature lists
• UX review is a hard gate: /team-ui checks for a passing /ux-review before proceeding to visual design
• Accessibility caught early: the missing keyboard alternative was flagged by review, not discovered by a QA tester in the final week
• Blocking vs. advisory: the missing keyboard path was BLOCKING (stops handoff); the colorblind colors were ADVISORY (can be fixed in visual pass)
• Section-by-section UX authoring: same incremental pattern as /design-system — each section written to file before moving on
• Separate HUD and screen files: design/ux/hud.md is the whole-game HUD; per-screen specs live in design/ux/screens/
• Pattern library enforced by /team-ui: after this session, inventory drag-drop becomes a documented pattern in design/ux/interaction-patterns.md for all future screens to reference