---
name: ux-design-standards
description: UX design principles for agent-console. Use when designing features, evaluating acceptance criteria, or reviewing user-facing interactions in a multi-agent management UI.
---

# UX Design Standards

Five principles for a multi-agent management UI where one user orchestrates many parallel AI agents.

## Principles

### 1. Sequential Flow Over Hub-and-Spoke
Process multiple items in sequence (A → done → B) instead of forcing return to a central hub between each item. Example: Review Queue (#405) — owner reviews one PR then advances to the next without returning to a queue list.

### 2. Parallel Awareness Without Parallel Attention
Surface state changes passively (badges, activity indicators, memos) without requiring active monitoring. Pull, not push — no popups for routine updates. Example: Session sidebar shows agent state (idle/active/asking) via color-coded indicators; agents write memos the user reads asynchronously.

### 3. Interruption Hierarchy
Distinguish urgency: **Blockers** (agent asking question, error) → prominent indicator, unmissable from any screen. **Action needed** (PR ready, acceptance done) → badge on next glance. **Informational** (task completed, CI passed) → passive, on demand. Completions are not blockers.

### 4. Action Proximity
Actions available where the user already is — inline over page-level, contextual creation, progressive disclosure. Example: Worktree creation from session breadcrumb (#402) — no navigation to a management page.

### 5. Glanceable Status, Opt-in Detail
Summaries in lists, full detail on click. Summarize semantically ("Agent completed PR #42"), not by truncation. Two-level pattern: Level 1 = summary in lists, Level 2 = detail on expand. Example: Session sidebar shows name, state icon, and memo preview without terminal output.

## Applying to Acceptance Criteria

When writing criteria for user-facing features, verify each principle:
- "User can process items sequentially without returning to the list" (P1)
- "State change visible from session list without opening the session" (P2)
- "Blocker visually distinct from completion" (P3)
- "Action available inline without page navigation" (P4)
- "Status understandable from list view without expanding" (P5)

See [ux-design-standards.md](ux-design-standards.md) for full rationale, design guidelines, and codebase examples.