spreadlab/docs/m3-frontend-handoff.md

Handoff: milestone 3 frontend (slices 2-12)

You are implementing the spreadlab dashboard frontend. The design is fully decided and the backend is ready; this segment is Vue/TypeScript only. Repo root: grant-proposal/tool/ (paths below are relative to it).

State as of 2026-06-10

• docs/ui-spec.md is the NORMATIVE spec: read it end to end before any code. Page layout, component tree, every interaction with trigger/behavior/states, visual tokens for both themes, URL scheme, accessibility checklist, responsive rules, and the slice order (section 10). Slice 1 is done; you start at slice 2.
• docs/mockup/rendered.html is the approved visual reference. View it in a browser (or headless, see Method) in light, dark (?dark), and at phone width. Match its look; do not port its code.
• POST /api/scenario is live (slice 1): {config, strategy} in, {config, result, edges} out, edges as deterministic [from, to] node-index pairs. 400 with {"error": "..."} on invalid input. Generated types in web/src/types/ already include ScenarioRequest/ScenarioResponse (edges arrive as number[][]).
• The current web/src/App.vue is the milestone 2 parity page. Slice 3 replaces it; ComparisonTable.vue evolves into the collapsed ResultsTable (spec 4 and 8). Keep its test current, do not orphan it.
• The Go side needs no changes in this segment. If one becomes necessary, raise it first; remember go generate ./... + commit the regenerated types (CI has a drift guard).

Method

• Vue/TS is Justin's home turf: drive fast and mostly autonomously. No micro-briefs needed; keep commits per slice with clear messages, push after each slice (CI must stay green: type-check, lint, vitest, build, plus the Go jobs).
• THE DESIGN BAR IS THE HARD PART. Justin rejected the first mockup as "a very weak mishmash of elements"; the approved one is the bar: one card system, real type scale, consistent spacing, both themes, mobile first-class. Never show boxes-on-a-page, not even as an intermediate state. Slice 3 is the make-or-break visual slice.
• Self-check visually before claiming a visual slice done: screenshot the running app headlessly and compare against the mockup, e.g. chromium --headless --disable-gpu --screenshot=/tmp/app.png --window-size=1366,900 http://localhost:5173 (also dark theme and --window-size=390,1400). Read the PNGs; if it does not look like the mockup, it is not done.
• Dev stack runs in the shared tmux session "spreadlab" (window 1 runs ./dev.sh: API :8080, Vite :5173). Restart it there with C-c + ./dev.sh via tmux send-keys; never spawn invisible background tasks.
• Work through the accessibility checklist (spec section 8) as you build each piece; slice 12 is the audit, not the first time you think about it.
• One shared formatPct (Math.round to whole percent) used everywhere; the mockup says 83% where Go's printf said 82% for 99/120, and that class of mismatch must not reach the UI.
• Descriptive variable names; no em dashes anywhere.

Small open choices (decide with Justin via AskUserQuestion, batched)

• d3-force dependency: d3-force + d3-quadtree only (recommended) vs full d3. The seeded random source (mulberry32, spec section 6) is hand-written either way.
• Inter font: @fontsource-variable/inter (recommended) vs static weights.
• Panel ids: crypto.randomUUID() (recommended, zero deps) vs nanoid.
• Reach chart: hand-rolled SVG paths (recommended at this scale) vs a chart library.

Everything else is decided in the spec; do not re-open decided items (rejected alternatives are listed in spec section 11).

First steps

1. Read docs/ui-spec.md fully, view the mockup in both themes and at phone width.
2. Batch the four open choices above into one AskUserQuestion round.
3. Slice 2 (store + URL + debounced parallel runs) with Vitest coverage: it is pure logic, test it well; it carries every later slice.
4. Slice 3, compared pixel-wise against the mockup before you call it done.
5. Continue down spec section 10; each slice leaves the app shippable.