Justin Visser
5196ed270b
The design session runs in the VS Code extension from the course workspace, one level above this repo; spell every referenced path from there so nothing depends on the session's working directory.
96 lines
4.8 KiB
Markdown
96 lines
4.8 KiB
Markdown
# UI/UX design session brief
|
|
|
|
You are running a design session for spreadlab's milestone 3 dashboard. The
|
|
deliverable is a written spec, `docs/ui-spec.md`, that an implementation
|
|
session can execute without re-deciding anything. Do NOT write application
|
|
code in this session.
|
|
|
|
## How to run this session
|
|
|
|
- Walk through the UX with the user top-down: audience and core message
|
|
first, then page layout, then each interaction, then states and edge
|
|
cases. One topic at a time.
|
|
- Use AskUserQuestion aggressively for every meaningful choice, with a
|
|
recommended option first. Use ASCII mockups in option previews when
|
|
comparing layouts.
|
|
- The user is a developer (Vue/TS background), not a designer; explain
|
|
design trade-offs the way you would explain code trade-offs.
|
|
- No em dashes in anything you write.
|
|
|
|
## What spreadlab is
|
|
|
|
A self-hosted dashboard running an agent-based model live: a non-consensual
|
|
deepfake spreads through a simulated school year group (120 students), and
|
|
an education program changes who forwards it. The headline result: the same
|
|
education budget reaches 82% / 58% / 6% of the school depending on who gets
|
|
educated (no program / random 30% / best-connected 30%). The product goal
|
|
is making that lever visceral. Always framed "illustrative, not validated".
|
|
|
|
Audience, in order: grant-pitch audience and course graders (first contact,
|
|
must land in seconds), curious public on the hosted demo, the author.
|
|
|
|
## What already exists (look at it)
|
|
|
|
Paths below are given from the course workspace root
|
|
(/home/jv/src/uni/ai-in-open-society); the repo itself is
|
|
grant-proposal/tool/.
|
|
|
|
- Run ./dev.sh from grant-proposal/tool/ and open http://localhost:5173 to
|
|
see the current parity page (a static table of the three scenarios).
|
|
- The Python prototype's rendered output defines the inherited visual
|
|
language: grant-proposal/pitch/figure/out/spread.png and spread.gif.
|
|
Read the PNG; it is the look to inherit. Teal donut ring = educated,
|
|
rose = forwarded the fake, haloed node = origin, slate = unreached;
|
|
colourblind-safe via shape, not colour alone. Modern-dashboard look,
|
|
Tailwind-ish palette (see constants in
|
|
grant-proposal/pitch/figure/spread_figure.py).
|
|
- API: GET /api/config/default, POST /api/comparison (full Config in, all
|
|
three strategies' Results out). Result.reachedAtRound gives per-node
|
|
activation rounds, exactly what an animation needs. Types in
|
|
web/src/types/ are generated from Go structs.
|
|
- KNOWN GAP: the API does not yet expose graph topology (edges), which any
|
|
network view needs. The spec should state what the frontend needs from a
|
|
new/extended endpoint; the implementation session will add it.
|
|
|
|
## Locked decisions the spec must respect (from grant-proposal/tool-handoff.md)
|
|
|
|
- Layout is computed in the frontend with a force simulation (d3-force or
|
|
equivalent) seeded from the config: a shared URL must render the same
|
|
picture.
|
|
- Config is the whole truth and goes in the URL: shareable, reproducible.
|
|
- Vue 3 + TypeScript, lean and conventional; Pinia/Router only when the
|
|
design actually requires them (note it in the spec if so).
|
|
- No shape redefinition in the frontend: all data types come generated
|
|
from Go.
|
|
- Quality bar includes accessibility, and the concrete criteria are
|
|
UNDEFINED so far. Defining them is part of this design session (keyboard
|
|
operation, reduced-motion behaviour for the animation, contrast,
|
|
screen-reader treatment of results at minimum).
|
|
|
|
## Questions the spec must answer
|
|
|
|
1. Page composition: prototype-style three panels side by side, or one
|
|
network view with a strategy switcher, or something better? What is
|
|
above the fold at first contact?
|
|
2. Which config levers get visible controls first, which live in an
|
|
"advanced" area (seeds?), and what control types (sliders, steppers)?
|
|
3. Animation: autoplay or user-initiated? Play/pause/scrub/speed? What does
|
|
round-by-round progression look like; what happens at reduced motion?
|
|
4. Metrics: what numbers/curves accompany the picture, and how do they
|
|
update while animating?
|
|
5. Sharing UX: how does config-in-URL surface to the user (copy button,
|
|
live-updating address bar)?
|
|
6. States: loading, API unreachable, invalid config (the API returns 400
|
|
with an error string), tiny screens.
|
|
7. How is "illustrative, not validated" communicated without undermining
|
|
the demo?
|
|
8. Accessibility acceptance criteria (the concrete, testable list).
|
|
|
|
## Output format for docs/ui-spec.md
|
|
|
|
Page layout (with a final ASCII wireframe), component tree with
|
|
responsibilities, every interaction specced (trigger, behaviour, states),
|
|
data requirements from the API (including the topology gap), visual tokens
|
|
(palette, shape encodings), accessibility criteria as a checklist, and an
|
|
ordered implementation slice list for milestone 3. Decisions only, no
|
|
options left open; record rejected alternatives in one line each at the end.
|