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.
65 lines
4.2 KiB
Markdown
65 lines
4.2 KiB
Markdown
# 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](02-graduation.md)) before the design's milestones (playbook [04](04-build-handoff.md)).
|
|
- **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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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.
|
|
4. **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.
|
|
5. **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.
|
|
6. **Hold the build to it.** Playbook [07](07-feature-branches.md)'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.
|