oc-ux-engineer

# UX Engineer

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

A tri-agent design harness: Design Planner → Design Generator → Design Evaluator.
The same architecture that makes oc-app-architect's Phase 6 build loop produce honest
quality scores — skeptical evaluation with agent separation — applied to UI/UX design.

Also runs cross-screen flow analysis, maintains a living component library, and
enforces fidelity between approved designs and built code.

Works in two modes:
- **Standalone**: Full tri-design workflow for new or existing projects
- **oc-app-architect plugin**: Adds a Design Evaluator alongside the Code Evaluator
  during UI-heavy oc-app-architect Phase 6 build sprints

## /oc-ux-engineer — Command Reference

```
UX ENGINEER COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  TRI-DESIGN HARNESS
  /oc-uxe plan          Run the Design Planner on a brief
  /oc-uxe build         Start or resume Design Generator → Evaluator loop
  /oc-uxe eval          Run the Design Evaluator ad-hoc on any artifact

  MODULES
  /oc-uxe flow          Map and audit user flows across screens
  /oc-uxe components    View, update, or audit the living component library
  /oc-uxe fidelity      Compare built code against approved design artifacts
  /oc-uxe dash          Route data-heavy UI to oc-dash-forge for specialized design

  APP-ARCHITECT PLUGIN
  /oc-uxe attach        Activate Design Evaluator for current oc-app-architect Phase 6 build session
  /oc-uxe detach        Deactivate Design Evaluator (code-only evaluation)

  UTILITIES
  /oc-uxe status        Show current design state, scores, component coverage
  /oc-uxe export        Export component library as interactive HTML
  /checkpoint        Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-uxe to see this again.
```

---

## Tri-Design Architecture

```
DESIGN BRIEF (from user, oc-app-architect, or prompt)
        │
        ▼
┌──────────────┐
│   DESIGN     │  Expands brief → design spec
│   PLANNER    │  Outputs: design-spec.md, design-sprints.md
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────────────────┐
│       DESIGN BUILD LOOP (per sprint)         │
│                                              │
│  ┌────────────┐  contract   ┌─────────────┐  │
│  │  DESIGN    │◄─negotiate──►│  DESIGN     │  │
│  │  GENERATOR │             │  EVALUATOR  │  │
│  │            │──artifact──►│             │  │
│  │  Builds    │             │  Grades     │  │
│  │  design    │◄──feedback──│  (isolated) │  │
│  └────────────┘             └─────────────┘  │
│       │                           │          │
│       │    PASS threshold?        │          │
│       │      or max iters?        │          │
│       └───────────────────────────┘          │
└──────────────────────────────────────────────┘
        │
        ├──► Component Library (living artifact)
        ├──► Flow Map (cross-screen navigation)
        └──► Design Tokens (source of truth)
```

### Why Three Agents for Design?

The same failure modes that plague code generation hit design even harder:

1. **Self-evaluation bias** — A generator that just built a screen layout will
   always think it "looks good." A separate evaluator, tuned to be a skeptical
   senior product designer, catches hierarchy problems, missing states, and
   accessibility gaps that the generator would wave through.

2. **Context contamination** — The generator explored 3 layout options before
   settling on one. That exploration context makes the chosen option feel more
   justified than it is. An evaluator with clean context judges the output on
   its merits, not the journey.

3. **Design drift** — Over multiple screens, the generator gradually drifts from
   the approved tokens (slightly different spacing, one-off colors). The evaluator
   catches drift because it reads the design spec fresh each time.

---

## Routing to oc-dash-forge (`/oc-uxe dash`)

Some screens are primarily **data display**: dashboards, BI views, analytics, monitoring consoles, dense reports. These have their own design discipline (Tufte density, scannability hierarchy, semantic color, chart selection) that is poorly served by the general-purpose tri-design harness.

For these screens, oc-ux-engineer routes to **oc-dash-forge** — a specialized skill for dashboard and dense-information UI.

### Auto-detect triggers

During `/oc-uxe plan` or when evaluating a brief, oc-ux-engineer should recognize dashboard surfaces and surface the routing option. Triggers:

- Brief mentions "dashboard", "analytics", "BI", "KPI", "monitoring", "report view"
- ≥3 charts or ≥5 KPIs on the same screen
- Upstream context includes a `data-architect-handoff.md`
- Screen's primary job is "show data" rather than "enable action"

When detected, offer:

```
This screen looks data-heavy. Route design to oc-dash-forge?

oc-dash-forge specializes in:
  - Exec / Ops / Analyst archetype branching
  - Density tuning, semantic color, chart selection
  - Working React prototype with archetype-appropriate viz stack (Tremor / Recharts / D3)

  (Y) Route to oc-dash-forge
  (N) Continue with oc-ux-engineer tri-design harness
```

### Explicit routing: `/oc-uxe dash`

User can force routing with `/oc-uxe dash [brief]`. oc-ux-engineer packages its current context (tokens, component library, design spec if any) and invokes oc-dash-forge's `/oc-data-forge` with upstream context pre-populated.

### Token handoff (bidirectional)

- **oc-ux-engineer → oc-dash-forge:** If oc-ux-engineer already has approved tokens, pass them as design constraints. oc-dash-forge will specialize density/chart-color tokens within that system.
- **oc-dash-forge → oc-ux-engineer:** When oc-dash-forge produces dashboard tokens (semantic color, density scales), hand them back so oc-ux-engineer's living component library stays consistent.

### When NOT to route

Keep the work in oc-ux-engineer if:
- The