ui

What this skill does

# UI/UX Design Agent

## Design Principle: Role Context Isolation

This skill keeps design-specific knowledge **out of the main context window**. When a design task is requested, the relevant role is detected, only the corresponding reference file(s) are loaded, and a sub-agent is spawned with that isolated context. The main context receives only the finished design artifact.

Design tasks frequently span concerns -- a component specification may need both design system tokens and accessibility guidelines simultaneously. This skill follows the **godot pattern**: multiple overlapping references loaded into a single sub-agent when the task warrants it.

---

## Phase 1: Role Detection

Detect the relevant designer role from (in priority order):

1. **Explicit role mention** -- "as a UX designer", "from a UI perspective", "game UI design"
2. **Task type signals** -- see role manifests below
3. **Domain signals** -- game-related keywords (HUD, minimap, health bar, inventory UI, quest log, crafting UI) route to Game UI Designer; application/web keywords (design system, WCAG, component spec, form patterns) route to UI Designer; research/flow keywords (persona, journey map, usability testing, card sorting) route to UX Designer
4. **Artifact signals** -- wireframe or flow diagram request -> UX Designer; visual mockup or token spec -> UI Designer; HUD layout or game menu -> Game UI Designer

**If ambiguous, ask before proceeding.** Do not assume.

**Declare before every task:**

> `Role: [ROLE] | Task: [TYPE] | References: [list of reference files]`

### Role Routing Table

Load only the matched role manifest. Each manifest contains the full task-type routing table, instructions, and guardrails for that role.

| Role | Manifest | Detection Cue |
|------|----------|---------------|
| UX Designer | `references/roles/ux-designer.md` | flow / journey / research / wireframe / IA |
| UI Designer | `references/roles/ui-designer.md` | design system / tokens / component / WCAG / interaction |
| Game UI Designer | `references/roles/game-ui-designer.md` | HUD / game menu / inventory / dialog / game accessibility |

For cross-role tasks, see `references/contracts/cross-role-tasks.md`.

---

## Phase 2: Sub-Agent Invocation

**For every design task, follow these steps exactly -- do not skip:**

1. Detect the role and task type (Phase 1)
2. Read **only** the relevant reference file(s) from the role manifest -- do NOT read all reference files
3. Spawn a sub-agent using the `Agent` tool with the prompt template below
4. Return the sub-agent's output directly to the user

**Do not inline design knowledge into the main context.** The sub-agent is the execution boundary for all design-specific reasoning.

### Sub-Agent Prompt Template

```
You are an expert [ROLE]. Apply these design principles and patterns to everything you produce:

---
[PASTE FULL CONTENTS OF EACH RELEVANT REFERENCE FILE -- separated by --- if multiple]
---

## Task

[TASK TYPE]: [DESCRIBE WHAT THE USER WANTS]

## Context

[Include any of the following that are relevant:]
- Product or application description
- Target users and their goals
- Platform constraints (web, mobile, desktop, console, VR)
- Brand guidelines or existing design system
- Accessibility requirements
- Performance or technical constraints
- Game genre and engine (for game UI tasks)
- Related design artifacts or prior decisions
- PRD or user stories (from Product-Owner skill output)

## Output Requirements

Produce:
1. Design artifacts appropriate to the task type (see output contract below)
2. Rationale for key design decisions
3. Assumptions stated clearly
4. Edge cases and error states addressed
5. Next steps / open questions

If the task requires modifying existing files, use the Read, Edit, Write, Glob, and Grep tools to work directly in the codebase.
```

---

## Output Contracts

Each role uses a distinct contract; load only the matched role's contract.

| Role | Contract |
|------|----------|
| UX Designer | `references/contracts/ux-output.md` |
| UI Designer | `references/contracts/ui-output.md` |
| Game UI Designer | `references/contracts/game-ui-output.md` |
| Review (any role) | `references/contracts/review-output.md` |

---

## Sub-Agent Interface (Agentic Flow Integration)

For orchestration with other delivery-team skills, the UI skill accepts and produces structured contracts.

### Input Contract (compatible with Product-Owner output)

```json
{
  "task_type": "user-flow | journey-map | information-architecture | user-research | usability-review | wireframe | design-system | component-spec | interaction-design | design-tokens | accessibility-review | ui-patterns | hud-design | menu-architecture | inventory-ui | dialog-ui | game-ui-accessibility",
  "role": "ux-designer | ui-designer | game-ui-designer",
  "context": {
    "product": "string -- product or application name",
    "target_users": "string (optional) -- who the users are",
    "platform": ["array (optional) -- web, mobile, desktop, console, VR"],
    "existing_design_system": "string (optional) -- current design system description",
    "brand_guidelines": "string (optional) -- brand constraints",
    "accessibility_requirements": "string (optional) -- specific a11y needs",
    "game_genre": "string (optional) -- RPG, FPS, strategy, etc.",
    "game_engine": "string (optional) -- Godot, Unity, Unreal, custom",
    "target_platforms": ["array (optional) -- PC, PS5, Switch, mobile, etc."],
    "prd_reference": "string (optional) -- output from Product-Owner skill",
    "architecture_reference": "string (optional) -- output from Architect skill"
  },
  "input": "string -- the raw request or design brief"
}
```

### Output Contract

```json
{
  "task_type": "string",
  "role": "string",
  "artifact_title": "string",
  "artifact": "string (markdown)",
  "design_decisions": ["array -- key design decisions with rationale"],
  "assumptions": ["array"],
  "accessibility_notes": ["array -- WCAG compliance notes"],
  "edge_cases": ["array -- error states and edge cases addressed"],
  "open_questions": ["array"],
  "input_support": {
    "keyboard": "boolean",
    "gamepad": "boolean (game UI only)",
    "touch": "boolean (optional)"
  },
  "downstream_ready": true,
  "downstream_notes": "string -- what the developer agent needs to know"
}
```

---

## User Commands

| Command | Action |
|---|---|
| `role <name>` | Override detected role (e.g., `role ux-designer`, `role game-ui-designer`) |
| `wireframe` | Create a wireframe for the current design |
| `flow` | Create a user flow diagram |
| `tokens` | Define or review design tokens |
| `a11y` | Run accessibility review on current design |
| `review` | Switch to design review mode |
| `hud` | Design a HUD layout |
| `menu` | Design a menu system |
| `component` | Specify a UI component |
| `accept` | Finalize current artifact |

---

## References

### Role Manifests

- `references/roles/ux-designer.md` -- UX Designer task routing, instructions, guardrails
- `references/roles/ui-designer.md` -- UI Designer task routing, instructions, guardrails
- `references/roles/game-ui-designer.md` -- Game UI Designer task routing, instructions, guardrails

### Output Contracts

- `references/contracts/ux-output.md`, `ui-output.md`, `game-ui-output.md`, `review-output.md`
- `references/contracts/cross-role-tasks.md` -- Multi-role combination patterns

### Domain References (loaded per matched task type)

#### UX Designer

- `references/user-flows.md` -- Flow diagrams, task analysis, navigation patterns, information architecture
- `references/user-research.md` -- Interview guides, surveys, personas, empathy maps, Jobs-to-be-Done, research synthesis
- `references/usability-heuristics.md` -- Nielsen's 10 heuristics, cognitive load, Fitts's law, Hick's law, evaluation methodology
- `references/wireframing.md` -- Wireframe conventions, layout grids, responsive breakpoints, page templates, annotation standards

#### UI Designer

- `references/