UI Interview - V2 Card Mosaic

UI Interview — V2 Card Mosaic (approved UI branch packet)

Approved canonical UI branch packet. Finalized from this alignment page after final compiled YAML approval on 2026-06-29. Fixture data and simulated terminal output in the reviewed mockup remain prototype-only. Confirmed artifacts: design/ui-v2-card-mosaic.md, design/ui-v2-card-mosaic-interview.md, and design/flow-tree-personal-workstation.yaml.

0. Source Evidence

Stage-1 research note: No design/*/design-inspirations-.md artifact exists. Reference feel is supplied by the V2 spec itself (Vercel / Railway / Render / CI dashboard lineage) and the competitive analysis; live web inspiration research was not required for this baseline/control branch. Research folded into design.

1. Confirmed UI Assumptions Manifest (stage 0, round 1 — all confirmed)

2. Resolved Open Items (stage 0, round 1 — recommendations accepted)

2b. Round-2 Aesthetic Directive (coverage checkpoint, OF1)

OF1 (user, verbatim): "Polish, minimalism, as little text as possible, icon buttons where possible with text tooltips."

How applied: icon buttons with title/aria-label tooltips replace text buttons wherever the action is unambiguous (header QR/settings, detail stop/restart/back, card retry, approval verbs); chrome copy is minimized so status badges + live stdout carry the signal; generous whitespace; calm, restrained motion; premium, non-generic finish. The one always-labeled action is the primary Start Agent CTA. This directive refines — does not override — the V2 spec's "comfortable, legible, boringly competent" tone: minimalism here means less chrome text, not less information per card.

3. Parent Flow, Branch Role & Coordination

• Parent user-flow branch: monitoring-start — "Board Monitoring & One-Click Start" (flow paths:

happy-path, C; screens S3, S4, S5, S6).

• Selected UX variation: v2-card-mosaic — the baseline/control. Takes the flow-map-native

position on all four axes (board=card grid · connection=full-page route · launch=modal · posture=co-equal responsive).

• Touched sibling flows (linked, not designed here): recovery (Path D — error card → detail

remediation), approval (Path B — push-triggered approval; V2 surfaces the global queue badge/preview + focused-agent inline approval), diff-review (S9 — "Review diffs →" handoff), device-handoff (QR / async recap S8), settings (S10 — credential/tool fixes link out from card/modal).

• Sibling UX variations this control is measured against: v1-operator-console, v3-kanban-pipeline,

v4-command-first, v5-glanceable-stream. V2 deliberately introduces the fewest net-new concepts so the others' single-axis deviations have a measuring stick.

• Shared (not net-new) cost: the folded tool-adaptive detail (xterm.js/WebSocket + structured

stream) and live stdout previews are shared across all five variations.

4. Page Inventory & Route Map

Overlays/interstitials (S4 modal, S8 recap) stack over whatever route is active; they are not routes. Deep links resolve directly to /agents/:id, falling back to /.

5. Global Shell Rules

• Persistent header (~56–64px, sticky, full width): left = app name/logo (minimal). Right cluster

(icon buttons + tooltips per OF1): approval-queue badge (count), QR / "Open on Mobile", settings gear, and the primary Start Agent CTA (accent; the one always-labeled action).

• Connection banner (conditional, under header): "Reconnecting to workspace…" with exponential

backoff retry; cards freeze at last-known state; Start/Stop disabled until reconnect.

• Optional chip row (O3): single row — status filter chips + repo filter chip. Light only.
• Detail top bar replaces the board header on /agents/:id: Back to Board (chevron icon) · agent

identity · stop/restart icon controls.

6. Page-by-Page Anatomy

S3 — Agent Board (mosaic)

• Header (above) → conditional connection banner → conditional chip row → mosaic (fills rest).
• Grid: 3 col >1024px · 2 col ≤1024px · 1 col ≤640px, generous gutters, columns capped (~3–4) at

very large widths so cards stay readable.

• Empty state replaces the mosaic: centered minimal glyph + "Start your first agent" + single

prominent Start Agent CTA + muted quick-start link + muted "Open settings." Approval/diff hidden.

Agent Card (canonical component; vary by state)

Regions top→bottom (~220–280px tall desktop):

1. Top row: agent name (left) + status badge (right; colorblind-safe = shape/icon + short label, not color alone).
2. Meta row: tool · repo (· branch) — small/muted.
3. Metrics row: elapsed · token usage — small/muted, right-aligned.
4. Live stdout preview: ~4 lines (range 3–5), monospace ~12px, auto-scrolling tail, fade-truncated at bottom. V2's signature; best-effort raw tail, not a structured promise.
5. Conditional strip: one-line error summary (error) or "completed — Review diffs →" (completed).

• Whole card = click target → /agents/:id. Hover = subtle lift/accent. Left-edge accent by status.

Waiting cards pulse gently (reduced-motion-respecting). Sort: error > waiting > running > idle.

S4 — Start Agent (modal overlay)

• Backdrop ~50% scrim, click-to-cancel. Centered ~520px desktop; near-full-width bottom sheet on mobile.
• Title "Start Agent." Fields: Repo picker (dropdown, GitHub-OAuth-populated, skeleton while

loading) · Tool selector (dropdown) · Prompt (textarea, tallest, ~4–6 rows) · "More options" toggle → optional Branch field.

• Footer: Start Agent (primary accent, right; validates required repo/tool/prompt on submit and highlights missing fields) · Cancel

(secondary, left). Inline error region above footer.

• States: loading skeleton · required-field markers · submit-time error highlights · transient launching spinner ("Starting agent…", fields

disabled briefly; success closes the modal and shows a starting card; a permanent spinner is a bug) · inline launch error + Retry · tool-unavailable warning + "Install tool" link (→ S10), Start disabled.

S5/S6 — Folded Agent Detail (/agents/:id)

• Top bar: Back to Board (chevron icon, left) · agent name · tool · repo · status badge · elapsed

(center) · stop / restart icon controls (right; destructive → confirm).

• Primary region (bounded to the active detail viewport):
• CLI tools → terminal-primary: large xterm.js terminal (~75–80% desktop), darker console bg,

live interactive stream. Long terminal history scrolls inside the terminal body only; the rendered terminal shell, full detail route, top bar, side rail, inline approval, and prompt controls stay inside the detail viewport. Switching between reviewed approvals resets detail stream and scroll state so stale terminal output cannot push the next detail view.

Error terminal semantics: for a failed CLI agent, the terminal view is the preserved session transcript and error output up to the failure, not decorative window dressing and not a replacement summary that discards prior history. The reviewed mockup uses representative fixture output only because it has no real agent session buffer.

• API-native → structured-primary: parsed activity stream (steps, progress, file-change list)

in the same footprint. Structured progress scrolls internally and must not push inline approval or prompt controls out of reach.

• Side rail (right ~24% desktop — O2): global approval-queue count, previewed next item, Approve shown / Review shown actions, Triage all approvals stub, and file-change summary.

Collapsible on tablet; collapses below the primary region at ≤640px.

• Inline approval card (when waiting): Approve / Reject / Modify / Defer — in-flow (overlay/badge

over terminal for CLI; inline in stream for structured). Approval actions stay reachable after Review shown switches between queued approvals.

• Footer: prompt-injection textarea + send (both renderings).
• Mobile: CLI terminal remains viewport-contained and read-mostly with "Heavy typing? Open on desktop →" hint (O4);

structured detail fully usable on phone.

7. Component Inventory

Agent Card · Status Badge (error/waiting/running/idle/starting/completed; drives color, sort, pulse; colorblind-safe) · Live stdout Preview · Start Agent button (header) + Start Agent modal (repo/tool/ prompt/branch/Start/Cancel) · Approval-queue badge (header) + global queue preview/actions (rail) + focused-agent inline approval card (detail) · xterm.js terminal (CLI) / parsed activity stream (API) · prompt-injection textarea · stop/restart/retry controls · connection/recovery banner + reconnecting overlay · Back to Board control · QR / Open-on-Mobile + PWA install prompt · Async Recap interstitial (stub) · optional status/repo filter chips.

8. Control & Link Inventory (behavior)

Destructive/irreversible actions (stop, reject) get a confirmation affordance; launching and approving do not (happy path, reversible enough).

9. Layout, Density, Hierarchy & Responsive

• Density: comfortable, not dense (deliberate tradeoff — buys per-agent glanceability + co-equal

touch usability, costs fleet density). Card ~220–280px tall; in-card controls ≥44px on mobile.

• Hierarchy (card): status badge + name (primary) → stdout preview (secondary) → meta/metrics

(tertiary, muted). Color reserved for status; rest grayscale.

• Board hierarchy: sort + pulse + red badges pull the eye; header approval badge is the single

global alarm.

• Detail hierarchy: primary region (terminal/stream) dominates; chrome quiet.
• Type scale: name ~15–16px; meta/metrics ~12–13px muted; stdout ~12px mono.
• Color: dark house palette `--bg:#1a1a2e; --card:#16213e; --border:#2a2a4a; --accent:#4dabf7;

--text:#e0e0e0; --muted:#8b8fa3`; status green/amber/red/grey on top; terminal bg darker than card.

• Responsive (3 breakpoints): Mobile ≤640 = 1-col stack, header condenses (Start may be sticky FAB

/ full-width), modal = full-screen sheet, detail rail collapses below, CLI terminal history scrolls inside the terminal body and remains read-mostly. Tablet ≤1024 = 2-col, full card richness, modal ~480–520px, rail visible ~30% (collapsible). Desktop >1024 = 3-col generous gutters, modal ~520–560px, rail persistent ~24%, terminal ~75–80%. Columns capped at very large widths. No breakpoint is "the real one" — co-equal posture.

10. Visual Tone

Familiar, trustworthy, boringly competent — a polished deploy/CI dashboard (Vercel/Railway/Render lineage) for instant fluency. Dark palette; calm grayscale chrome with status color as the only loud element; soft card elevation; restrained motion (fade-in on launch, gentle waiting pulse, smooth stdout scroll — no gratuitous animation). Terminal reads as a real console. Refined per OF1 toward icon-led, minimal-text chrome.

11. Interaction States (coverage)

Card: starting · running (streaming) · waiting (pulse, sorted top) · error (red badge + summary + re-sort to top) · idle · completed (Review diffs →) · hover · focus. Board: default · empty · connection-lost banner. Modal: loading skeleton · required-field markers · submit-time validation errors · transient launching spinner · success close/card insertion · inline error · tool-unavailable. Detail: streaming · waiting/inline-approval · reconnecting overlay · stop/restart confirm · mobile read-mostly.

12. Accessibility Requirements (baseline, not optional)

Logical keyboard order + focus management; visible focus rings; ≥44px mobile tap targets; colorblind- safe status (badge = shape/icon + label, not color alone); prefers-reduced-motion disables pulse + auto-scroll; aria-labels + title tooltips on every icon button; correct button/link semantics; the whole-card click target also keyboard-activatable.

13. Prototype-First Section

• First clickable journey: land on S3 board → click Start Agent → fill modal → watch a starting card become running with live stdout → click a waiting card → approve in detail → Back to Board.
• Experiment route map (this run): build just V2 (per E2 correction). After V2 approval, continue with the next UI branch/variation review; downstream prototype work remains gated until UI branch decisions are complete enough for build-plan synthesis.
• Fake / fixture data: agent list, stdout streams, token/elapsed metrics, repo/tool lists, approval prompts — all fixture/in-memory for the mockup. In production, detail terminal output must come from the actual agent session buffer, including the transcript leading into any error.
• Visually mocked, not implemented: WebSocket live state, simulated xterm.js-over-tunnel terminal output, Web Push, GitHub OAuth, model-key auth, server-canonical persistence, QR deep-link auth.
• Deferred production infra: xterm.js sub-100ms keystroke echo over tunnel; Multica-style stdout-parsing generality; iOS Safari Web Push reliability; agent resource isolation at 5-12 concurrent; BYO-client connectivity.

14. Risks & Failure Modes

• Cards waste space at scale (~12 agents scroll; no single-screen overview) — mitigated by column cap +

sort-to-top, ceiling is real (this is why V1's dense table exists).

• Route-switch drops board context (detail unmounts the board) — mitigated by fast back + lossless

server state + deep links; round-trip cost inherent to V2.

• stdout-preview reliability bounded by stdout-parsing open question — treat as best-effort tail.
• Terminal latency in folded CLI detail unproven — phone read-mostly + desktop handoff.
• "Generic" risk — being the familiar control, may underwhelm a power user (loses by being merely fine).
• Modal launch friction at high volume — mitigate with remembered last repo/tool defaults.
• No fleet-bottleneck spatiality (can't see a pileup as a column like V3) — inferred from badge + sort.

15. Non-Goals

Multi-user sharing / collaboration / permissions (single-user); Mode A/B user toggle (folding is tool-driven); Mode C / IDE (code-server); heavy/faceted filtering (V1's job); in-depth S8/S9/S10 design (linked); reopening the four fixed axes (route to /ux-variations).

16. Implementation Notes

Lowest build complexity of the five (baseline): standard responsive CSS-grid of card components fed by one WebSocket state stream; plain routing (/, /agents/:id) + modal + interstitial; reuses shared stack + design system. Owns only its grid layout, card component, and modal. The two non-trivial pieces (folded tool-adaptive detail; live stdout previews) are shared across all five variations, not net-new relative to the set.

17. Open Questions Carried Forward (not blockers)

Terminal latency over tunnel (Open Q #1); stdout-parsing generality (Open Q #2); iOS Safari push reliability (Open Q #3); Mode C ROI (Open Q #4); resource isolation at 5–12 (Open Q #5); BYO connectivity (Open Q #6). These are evaluation criteria for /uat, not resolved here.

18. Build Screen Batch Plan

Downstream prototype work remains gated, but this approved UI packet provides the ordered visual-screen batch slice for $build-ui-screens when the prototype phase is later authorized.

19. Final Branch Decision

Decision: approve — V2 Card Mosaic is a valid UI experiment/control branch. Advance after canonical write.

Decision source: final compiled response YAML submitted 2026-06-29 with approval_status: ready-for-agent-review, required_gate_status: complete, and no unanswered required questions.

Route: continue with the next UI branch/variation review; downstream prototype remains gated.

20. Canonical File Destinations

• design/ui-v2-card-mosaic.md — approved UI branch packet.
• design/ui-v2-card-mosaic-interview.md — interview log and branch decision record.
• design/flow-tree-personal-workstation.yaml — V2 ui_reviews[], ui_experiments[], and decisions[] records with decision_id: ui-v2-card-mosaic-approve-2026-06-29.
• docs/history/archive/2026-06-29/134241/research/_working/preliminary-ui-interview-research.md — archived pre-approval working packet.
• docs/history/archive/2026-06-29/134241/research/_working/ui-interview-v2-card-mosaic-mockup.html — archived pre-approval mockup source.
• alignment/ui-interview-v2-card-mosaic.html — confirmed alignment page.

21. Interview Log

Provenance: live-ui-interview. Stage-0 interrogation loop, 2 rounds, confidence gate passed.

Round 1 — Assumptions Manifest (A1–E2): presented as the UI Assumptions Manifest; user confirmed A1, A2, A3, A4, A5, B1, B2, B3, C1, C2, C3, D1, D2, E1; corrected E2 → "build just this variation" (V2 only this run, not fan-out). 20/20 items resolved.

Round 1 — Open items (O1–O5): O1 accept (~220–280px, 4-line preview), O2 accept (~24% rail, collapse below ≤640), O3 accept (single chip row), O4 accept (read-mostly mobile terminal + "open on desktop" hint), O5 free: "All looks good, this v2 mockup will calibrate how I deal with all the other variations."

Round 2 — Coverage checkpoint: gate pass; G-scope confirm (build just V2); G-coverage confirm-complete; OF1 (free): "Polish, minimalism, as little text as possible, icon buttons where possible with text tooltips." → applied as the chrome/finish directive (§2b).

Options & recommendations presented: O1–O4 each offered a recommendation with rationale/tradeoff (accepted as-is). Axes A3 explicitly flagged as out-of-scope-to-reopen (→ /ux-variations).

Mockup feedback / retry notes: Gate B approved the mockup as a valid V2 control branch. The reviewer asked whether the error terminal view represents the run up to the error or is window dressing. Decision: in production, the error terminal is the preserved agent session transcript plus failure output; the mockup's error stream is representative fixture output only.

Final branch decision: approve — valid UI experiment/control branch; advance after canonical write.