UX — Seam UX-prototype track (Krishna interview) [tracking]

[jack-champagne]

Tracking issue for the seam UX-prototype track — throwaway, fake-data webview prototypes we put in front of Krishna/Andrew for feedback, ahead of their backends.

Why

The Krishna Suresh UX interview (2026-06-30) concentrated on late-phase surfaces — the pulse catalog / history (Phase 3) and QILC iteration (v4) — plus the onboarding interview. Rather than wait for those backends, we prototype the surfaces in the inspector seam and harvest feedback now. Prototyping ≠ reordering the build — these are feedback probes with fake data, not a commitment to pull Phase 3/v4 forward.

Design freedom (read this first)

These issues are exploration prompts, not fixed specs. The UI/UX lane (Kate + team) has wide latitude to reshape, combine, split, drop, or invent surfaces based on what feedback shows works. The UX-number ordering is a priority suggestion, not a mandate — pull work forward or defer it as the design demands. Each issue states a problem + feedback questions; how it's solved is open.

Operating model (all prototypes)

• Built like the merged Run Inspector (PR refactor(extension): extract Run Inspector view to media files #44): CSP/wiring shell in .ts, markup+style in media/<surface>.{html,css}, DOM-id + message contract pinned by a *_contract.test.ts. Same lane-split, same discipline.
• No backend — each fed by a fake-data fixture.
• Fixtures grounded in @amicode/schema (run.toml / result.toml / catalog-entry) so the data model is honest and swaps to the real store later without redesign.
• Each prototype ships with 1–2 feedback questions — it's an experiment, not just a demo.

Lanes

• Kate — design lane (media/*.{html,css} + interaction)
• Raghav — plumbing (.ts shell, contract test, fixture loader)
• Jack — content + steer (fields/questions per surface; sequencing)

Surfaces — all in this track, ordered by priority (lower number = sooner)

Basics (start here):

• UX1 — Onboarding + pulse-design interview flow storyboard (E5) #46 — UX1: Onboarding + pulse-design interview flow storyboard (E5) ⚠️ storyboard only; renders via AskUserQuestion in v1
• UX2 — Catalog entry card + "what do next" resume (E2) #47 — UX2: Catalog entry card + "what do next" resume (E2)

Comprehensive (next):

• UX3 — Pulse/run catalog browser (master-detail) (E1) #48 — UX3: Pulse/run catalog browser, master-detail (E1) — carries the flat-vs-per-system A/B
• UX4 — Run Inspector enhancements: phase stepper, tags, ipopt output (E4) #49 — UX4: Run Inspector enhancements (E4) — rides the live seam

Later (numbered higher on purpose; pick up as capacity/feedback allow):

• UX5 — Instance-vs-historical compare view (E3) #51 — UX5: Instance-vs-historical compare view (E3) — Phase 1.3 + catalog
• UX6 — Hardware status pills + device topology + sim/hardware switch (E6) #52 — UX6: Hardware status pills + device topology + sim/hardware switch (E6) — v4 hardware crossover
• UX7 — User-profiles view (experimental / production / optimizing) (E7) #53 — UX7: User-profiles view (E7) — persona / multi-user; least-formed, decide if it's real

Refs: spec-20260614-231647-amicode-interview-ux, spec-20260529-amicode-architecture, plan-20260603-124231-amicode-phased-build (armonissima). Source: Krishna UX interview note (personal vault, pending promotion to armonissima).

[kateebonner]

Design-lane execution plan (Kate, 2026-07-01)

Resolved in a grilling session against the track spec + interview note. Decisions:

Scope & sequence

• First outcome: UX1 + UX2 prototypes in front of Krishna/Andrew ~week of 07-07, in parallel as specced.
• UX2 scope: clickable chip → card → what-do-next (model catalog stays in UX3).
• UX1 content: I'm drafting the onboarding/pulse-design question tree myself (strawman for Jack's pass) rather than waiting on content or reusing the atoms tree — see comment on UX1 — Onboarding + pulse-design interview flow storyboard (E5) #46.

Design philosophy (applies to all UX1–UX7)

• Native-first: VS Code components/theme variables (--vscode-*) wherever possible; the point is feeling integrated.
• New components are style-agnostic: every brand decision routed through variables in one brand file (media/brand.css). Function and UX flow now; branding is a later, one-file pass.
• Vocabulary for the track now lives in the repo's new CONTEXT.md (surface, seam, chip, card, what-do-next, lanes…).

Design leads, schema follows

• Where a surface needs fields the v1 schemas forbid (catalog-entry has no tags/label/short-hash; lab.toml is transmon-only but onboarding asks "platform?"), the prototype uses a proposed v2 shape and the delta is filed back on the issue. The prototypes are the experiments that decide v2.

Workflow

• Browser-first, wire later: media/*.html open directly in a browser (media/dev/vscode-theme-stub.css fakes the theme, dev-only); @Rchari1 wires the webview shell + contract test once the DOM stabilizes. Contract-relevant DOM ids are stable from the first commit.
• Feedback loop: 30-min live sessions, Krishna and Andrew separately, them driving, the issue's feedback questions as script. Findings → interview-style vault note in armonissima (same pattern as the 06-30 note) → schema/architecture deltas filed to the open-questions doc + these issues.

First artifact: the UX2 browser-ready prototype just landed — see #47.

[kateebonner]

Design-lane structure update: UI building blocks now follow atomic design across the track. src/ui/atoms/ (pill, tag, icon, text — typed DOM factories, skinned only via brand.css variables) feed src/ui/components/ (chip, panel/kv, metric, action, plot host); surface scripts (src/<surface>_webview.ts) own only state + layout, with parallel style layers media/ui/atoms.css + media/ui/components.css. Vocabulary pinned in CONTEXT.md: pill = status indicator, chip = catalog-entry identity, tag = user label. UX2 refactored onto this structure (typecheck + 79 tests green); UX1 and later surfaces build on the same layers. The live Run Inspector is untouched — aligning it onto the atoms is a later, mechanical pass.

[kateebonner]

Sequencing update (design lane): UX4 (#49) is now Kate's first working surface, ahead of the UX1 storyboard — UX2's catalog-card prototype is already built, so the front of the queue is inspector redesign → UX1 content when Jack's tree drafting pairs up. Also housekeeping: the atomic UI layers moved to media/ui/{atoms,components}/ (TS factories + CSS together) so the design lane owns one folder.

[kateebonner]

Correction to the structure note above: there are no ui/atoms.css / ui/components.css files — that split let hardcoded styling leak outside the brand file. All atom + component styling is consolidated into the one media/brand.css (variables in :root at the top — palette, type scale, shape/rhythm, derived surfaces — with the atom/component classes below consuming them). Surface CSS stays layout-only. Restyling Amicode later = editing brand.css, mostly the variables block. TS factories remain at media/ui/{atoms,components}/.

[kateebonner]

Design-lane reset (2026-07-01, Kate): the local prototype scaffolding described in the comments above (catalog_card / inspector_v2 prototypes, media/ui structure, dev-preview command) was reverted before ever being committed — we're restarting the design-lane implementation with a cleaner structure. The plan decisions in the first comment (sequencing, feedback loop, native-first / single-brand-file philosophy, design-leads-schema) still stand. Disregard file paths in the structure comments; the work is archived locally and a fresh structure will follow.

[jack-champagne]

Ownership policy (Jack, 2026-07-02): Kate is sole owner of each UX issue. If a prototype turns out to need substantial extension plumbing (the .ts shell / contract test / fixture-loader is more than trivial), break it out into a sub-part / sub-issue and ping @Rchari1 — high bar. Light plumbing is handled inline, no separate assignment. The per-issue design-lane/plumbing-lane text still describes the work; this governs assignment.