jochen
5d745d04db
Design 63 turns the mail page into the operator's list with Owly beside it (ADR 0515 to 0519), in six milestones with their issues; its reference mockup is kept beside it, its data invented. Playbook 10 says how a page is designed before it is built: mockups with fixed data, the operator picks, the pick is the reference. The as-is of the mail modules now describes mail reading as delivered, the glossary gains design 63's words, design 59's milestone 4 is marked replaced, and AGENTS.md allows a design's mockup. Issues 1855 and 1856.
4.2 KiB
4.2 KiB
Playbook 10 — Visual design
Trigger. A page or a screen the operator will use is about to be designed or rebuilt, or the operator judges one unusable. It runs before the decisions about its look are written and before any of its code: a page built first and judged after it ships is rebuilt (the operator, 2026-10-22, on design 59's mail page, judged unusable the day it was delivered).
Who runs it. The lead of the design, on the larger model. Mockups may be drawn by an agent on the smaller model from the lead's brief. The operator picks; nobody else does.
What it produces
- The reference: one mockup the operator picked, kept with the design as
NN-mockup/beside its to-be document. It is a direction, not a pixel specification: the build matches what it shows the operator doing, in the order and the weight it shows, not its exact pixels. - The decisions it needs: what the pick changes about what the mesh keeps, shows or does, written as decision records (playbook 02) before the design's milestones (playbook 04).
- An acceptance test in the operator's words: the page is done when the operator uses it, on the devices they named, for the work the mockup shows.
Steps
- Gather what the page must carry. Read the as-is of what it replaces and the real shape of its data from the mesh (how many items, how long a line, what is missing in practice), the operator's complaint in their own words, and a short survey of how others solve it (a handful of products, one line each on what changes for the person). Write it into the work folder; nothing goes on the mesh.
- Draw three to five mockups with fixed data. Each is one static HTML file that opens from disk: invented data shaped like the real (names, amounts, lengths, a long subject, an empty sender), no backend, a mock script only where an interaction is the point. Each mockup is a different direction, not a variation of one; each shows a phone's width and a desktop's. One index page links them all.
- Show them and ask one question. Put the index on the machine the operator is at, and ask which direction to keep, one question at a time with the lead's recommendation. A round's answer may be a pick, a combination of two, or a change; the next round draws only that. Three rounds without a pick mean something the operator wants is missing: ask what, before drawing again.
- Make the pick the reference. Copy it into the design's
NN-mockup/, with every name, address, employer, mail address and amount of the operator's own replaced by invented ones: hq is public. Say in the design that the reference is a direction, and link it. - Write what is new as decisions, each with the operator's Approve where it changes what they see, then the design and its milestones. The design's acceptance tests end with the operator using the page live.
- Hold the build to it. Playbook 07's review reads the built page against the reference (a screenshot at each width beside the mockup), and the milestone is done only when the operator has used the page.
Bounds
| Waiting on | Bound | Past the bound |
|---|---|---|
| a round of mockups | 1 hour | say to the operator what is taking long |
| the operator's pick | the next exchange | ask once more, one question, with the recommendation |
| rounds without a pick | 3 | ask what is missing before drawing again |
Rules
- No code reaches the mesh during a visual design: mockups live in the work folder until one is picked.
- Mockups use invented data, never a copy of the operator's mail, files or accounts.
- The operator's pick stands over the lead's taste; the lead's recommendation is said once, with its reason.
How it is checked
- A to-be design of a page the operator uses links its reference mockup in
NN-mockup/, and that mockup holds none of the operator's own names, addresses or amounts (read by the reviewer of the design's pull request). - The milestone's review report shows the built page beside the reference at a phone's and a desktop's width.
- The design's last acceptance test is the operator using the page, and it is proven before the milestone's issues are resolved.