Team Ui

How to Delegate

Use the Task tool to spawn each team member as a subagent:

• subagent_type: ux-designer — User flows, wireframes, accessibility, input handling
• subagent_type: ui-programmer — UI framework, screens, widgets, data binding
• subagent_type: art-director — Visual style, layout polish, art bible consistency
• subagent_type: [UI engine specialist] — Engine-specific UI pattern validation (e.g., unity-ui-specialist, ue-umg-specialist, godot-specialist)
• subagent_type: accessibility-specialist — Accessibility compliance audit

Always provide full context in each agent's prompt (feature requirements, existing UI patterns, platform targets). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 4 review agents can run simultaneously).

Pipeline

Phase 1a: Context Gathering

Before designing anything, read and synthesize:

• design/gdd/game-concept.md — platform targets and intended audience
• design/player-journey.md — player's state and context when they reach this screen
• All GDD UI Requirements sections relevant to this feature
• design/ux/interaction-patterns.md — existing patterns to reuse (not reinvent)
• design/accessibility-requirements.md — committed accessibility tier (e.g., Basic, Enhanced, Full)

If design/ux/interaction-patterns.md does not exist, surface the gap immediately:

"interaction-patterns.md does not exist — no existing patterns to reuse."

Then use AskUserQuestion with options:

• (a) Run /ux-design patterns first to establish the pattern library, then continue
• (b) Proceed without the pattern library — ui-programmer will treat all patterns created as new and add each to a new design/ux/interaction-patterns.md at completion

Do NOT invent or assume patterns from the feature name or GDD alone. If the user chooses (b), explicitly instruct ui-programmer in Phase 3 to treat all patterns as new and document them in design/ux/interaction-patterns.md when implementation is complete. Note the pattern library status (created / absent / updated) in the final summary report.

Summarize the context in a brief for the ux-designer: what the player is doing, what they need, what constraints apply, and which existing patterns are relevant.

Phase 1b: UX Spec Authoring

Invoke /ux-design [feature name] skill OR delegate directly to ux-designer to produce design/ux/[feature-name].md following the ux-spec.md template.

If designing the HUD, use the hud-design.md template instead of ux-spec.md.

Notes on special cases:

• For HUD design specifically, invoke /ux-design with argument: hud (e.g., /ux-design hud).
• For the interaction pattern library, run /ux-design patterns once at project start and update it whenever new patterns are introduced during later phases.

Output: design/ux/[feature-name].md with all required spec sections filled.

Phase 1c: UX Review

After the spec is complete, invoke /ux-review design/ux/[feature-name].md.

Gate: Do not proceed to Phase 2 until the verdict is APPROVED. If the verdict is NEEDS REVISION, the ux-designer must address the flagged issues and re-run the review. The user may explicitly accept a NEEDS REVISION risk and proceed, but this must be a conscious decision — present the specific concerns via AskUserQuestion before asking whether to proceed.

Phase 2: Visual Design

Delegate to art-director:

• Review the full UX spec (flows, wireframes, interaction patterns, accessibility notes) — not just the wireframe images
• Apply visual treatment from the art bible: colors, typography, spacing, animation style
• Check that visual design preserves accessibility compliance: verify color contrast ratios, and confirm color is never the only indicator of state (shape, text, or icon must reinforce it)
• Specify all asset requirements needed from the art pipeline: icons at specified sizes, background textures, fonts, decorative elements — with precise dimensions and format requirements
• Ensure consistency with existing implemented UI screens
• Output: visual design spec with style notes and asset manifest

Phase 3: Implementation

Before implementation begins, spawn the engine UI specialist (from .claude/docs/technical-preferences.md Engine Specialists → UI Specialist) to review the UX spec and visual design spec for engine-specific implementation guidance:

• Which engine UI framework should be used for this screen? (e.g., UI Toolkit vs UGUI in Unity, Control nodes vs CanvasLayer in Godot, UMG vs CommonUI in Unreal)
• Any engine-specific gotchas for the proposed layout or interaction patterns?
• Recommended widget/node structure for the engine?
• Output: engine UI implementation notes to hand off to ui-programmer before they begin

If no engine is configured, skip this step.

Delegate to ui-programmer:

• Implement the UI following the UX spec and visual design spec
• Use patterns from design/ux/interaction-patterns.md — do not reinvent patterns that are already specified. If a pattern almost fits but needs modification, note the deviation and flag it for ux-designer review.
• UI NEVER owns or modifies game state — display only; emit events for all player actions
• All text through the localization system — no hardcoded player-facing strings
• Support both input methods (keyboard/mouse AND gamepad)
• Implement accessibility features per the committed tier in design/accessibility-requirements.md
• Wire up data binding to game state
• If any new interaction pattern is created during implementation (i.e., something not already in the pattern library), add it to design/ux/interaction-patterns.md before marking implementation complete
• Output: implemented UI feature

Phase 4: Review (parallel)

Delegate in parallel:

• ux-designer: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility features function correctly.
• art-director: Verify visual consistency with art bible. Check at minimum and maximum supported resolutions.
• accessibility-specialist: Verify compliance against the committed accessibility tier documented in design/accessibility-requirements.md. Flag any violations as blockers.

All three review streams must report before proceeding to Phase 5.

Phase 5: Polish

• Address all review feedback
• Verify animations are skippable and respect the player's motion reduction preferences
• Confirm UI sounds trigger through the audio event system (no direct audio calls)
• Test at all supported resolutions and aspect ratios
• Verify design/ux/interaction-patterns.md is up to date — if any new patterns were introduced during this feature's implementation, confirm they have been added to the library
• Confirm all HUD elements respect the visual budget defined in design/ux/hud.md (element count, screen region allocations, maximum opacity values)

Quick Reference — When to Use Which Skill

• /ux-design — Author a new UX spec for a screen, flow, or HUD from scratch
• /ux-review — Validate a completed UX spec before implementation
• /team-ui [feature] — Full pipeline from concept through polish (calls /ux-design and /ux-review internally)
• /quick-design — Small UI changes that don't need a full new UX spec

Error Recovery Protocol

If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:

1. Surface immediately: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
2. Assess dependencies: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
3. Offer options via AskUserQuestion with choices:
   • Skip this agent and note the gap in the final report
   • Retry with narrower scope
   • Stop here and resolve the blocker first
4. Always produce a partial report — output whatever was completed. Never discard work because one agent blocked.

Common blockers:

• Input file missing (story not found, GDD absent) → redirect to the skill that creates it
• ADR status is Proposed → do not implement; run /architecture-decision first
• Scope too large → split into two stories via /create-stories
• Conflicting instructions between ADR and story → surface the conflict, do not guess

File Write Protocol

All file writes (UX specs, interaction pattern library updates, implementation files) are delegated to sub-agents and sub-skills (/ux-design, ui-programmer). Each enforces the "May I write to [path]?" protocol. This orchestrator does not write files directly.

Output

A summary report covering: UX spec status, UX review verdict, visual design status, implementation status, accessibility compliance, input method support, interaction pattern library update status, and any outstanding issues.

Verdict: COMPLETE — UI feature delivered through full pipeline (UX spec → visual → implementation → review → polish). Verdict: BLOCKED — pipeline halted; surface the blocker and its phase before stopping.

Next Steps

• Run /ux-review on the final spec if not yet approved.
• Run /code-review on the UI implementation before closing stories.
• Run /team-polish if visual or audio polish pass is needed.