Take a topic through the screen pipeline
Table of Contents
This page documents a runbook — a named, repeatable composition of recipes and skills for a complete multi-step procedure. Each step references a recipe or skill by id-link.
1. Goal
Take one topic of Screen pipeline topics from the person's goal to a signed off screen, so that every screen of the web speaks the one UX language and the next topic repeats the same steps without discussion. Each step ends in a document a person signs off: the journeys, the prototype, the screens, the scenario and the sheet. The calendars topic ran it first, in Take the first reference data topic through the screen pipeline, and this page is what that run taught.
2. Preconditions
- The topic is a row of Screen pipeline topics, with its entities and its first judgement, and its gaps are on the Qt to web reference data matrix.
- The UX language is settled: the Record screen standard and the Entity screen specification carry a rule identifier on every rule, and the Screen review checklist cites them.
- The harness of How do I run the browser harness against the environment? runs against the checkout's environment, and the record screen baseline says what the topic's screens measured before the pipeline touched them.
- A story for the topic exists in the sprint with the four tasks below, as
compass add storyandcompass add taskscaffold them; the owner is reachable, because three steps stop for their sign off.
3. Steps
In execution order. Each step is one task of the topic's story, worked
through Work a task through to merged PR; a step that ends in the owner's
sign off leaves its task STARTED and waiting on them until they have
spoken, and closes on the next PR.
- Extract and judge the journeys. Start from the person's goal, not from
the Qt dialog. Read the topic's row and the matrix; find the journeys that
exist under User Journeys and write the ones that do not, with
compass add user_journeyas New user journey says. Then judge each step of each journey on the journey page, under Screens and wireframes, in a table of step, shape on the screen, and judgement: a step the standard record screen already draws, a kind's own action by RS-PAGE-03, a view no rule draws yet, a missing server operation, or a step that keeps state across a reply and so needs a workflow under the Workflows menu. Add the* Prototypesection the journey contract requires, link each gap in What is missing to its capture, and name the placements the prototype must decide. Stop for the owner: the journeys are signed off before any prototype. Record the sign off and its decisions on the journey, the task and the story's* Decisions. - Prototype the screens. One prototype per topic under
doc/prototypes/<group>/<name>/, as the Prototypes page requires: plain HTML, CSS and JavaScript, the web app's tokens, the query string as the state so every screen, dialog and reader view has an address a reviewer opens. Draw the screens where the standard settles them and nowhere else; where no rule covers a part, define it in the design note for the standard to take. Copy no history, dialog or panel from a live screen or an older prototype without checking it against the standard: the live reference data screens still carry the legacyHistoryPanel, and the first calendars prototype copied it (see the memory History is the shared timeline, never the compare panel). The design note cites the rule identifiers each screen follows, lists every state's address and says what is fake; the group page and the top page list the prototype; the journey's* Prototypesection links it. Render every state with Playwright and read the screenshots against the checklist before the owner does. Stop for the owner: the prototype is signed off before any code; their corrections are PRs on the same task. - Build the screens. Move the live screen to the prototype, and land each
move in the shared part the standard names, so that no screen builds a
dialog of its own and every record screen gains the fix:
RecordHeader,RecordDialog,PartsPanel,RecordDetails,RecordTimeline,RecordList. A kind's own action that answers in one reply is an operation dialog opened from the header. The strings exist in English, French and Portuguese before the screen ships. Where the harness has no check for a rule the build relies on, add one toprojects/ores.web/packages/harness/tests, titled by the identifier, so the legacy shape cannot pass a sign off again. Prove the build on the running web with the harness on the screen alone and a scripted drive of the editable path; the dialog checks skip on a screen whose first row is read only, so derive or add a record to reach them. - Test and sign off. Follow How do I test a feature after implementation?:
recreate the database and provision Acme as
How do I ready up an environment? says, write the test scenario with
compass add test_scenarioover list, page, create, amend with a stale version, parts, derived views, history and revert, delete, and the reader, and drive it with a script kept in the task'sevidence/folder, one function per step, until every failure is the screen's and not the script's. Press Refresh after every write in the script and in the words, because the page does not reload by itself. Then follow How do I sign off a screen?: the harness on the screen alone, the sheet fromscreen_sign_off.py, the person's lines filled from the scenario and its screenshots, the verdict. File every gap as a capture or fix it when it is the screen's and small; a gap the owner's run finds in the standard changes the standard, with the date and the reason on the rule. Stop for the owner: they run the scenario by hand and walk the sheet; their verdict is the sign off that closes the topic. Record it on the scenario, the sheet, the task and the story. - Close the topic. Close the story with its decisions distilled, and scaffold the next topic's story from this runbook with the same four tasks, in the order of Screen pipeline topics. The close PR of each topic adds what the topic taught to the section below, under the topic's name and date, so the page grows without being rewritten.
4. Postconditions
- The topic's journeys carry a judgement per step and the owner's sign off.
- The prototype is on
mainunderdoc/prototypes/<group>/, listed and signed off, with the rule it added to the standard recorded there. - The live screens draw what the prototype draws, through the shared parts, in three languages, with a harness check for every rule the build relied on; the harness on each screen has no failure that is the screen's.
- The scenario is PASSED by the owner's own run, the sheet carries their verdict, and every gap found is a capture or a fix.
- The story is DONE with its decisions, and the next topic's story exists.
5. What the topics taught
5.1. Calendars, 2026-10-25
- The topic's journey already existed; the task was to judge it, not to write a second one. Look before writing.
- A copied screen copies its legacy. The first prototype carried the two-pane history compare from the live currencies page and the classifications prototype; the owner caught it. The timeline is the only history.
- The owner's run of the scenario changed the standard twice: a record's history carries its parts (RS-HIST-01), and the tabs a read-only kind lacks stay hidden. Expect the standard to move at the sign off and write the decision on the rule.
- The scenario script's first failures were its own: it looked for a row before pressing Refresh, clicked the header's Edit instead of the row's, and left a regex literal uninterpolated. Three runs found two server gaps along the way: a deleted calendar's days stay behind, and a re-created key continues the old history.
- The harness skips the dialog checks on a screen whose first row is read only; derive or add a record to reach them, and let the scenario create and delete its own.
- The local gate can be red on main's defects while the branch is clean;
prove whose failure it is on a clean worktree of
origin/mainand capture it rather than wait.
6. See also
- Screen pipeline topics — the topics in order, and what each produces.
- Take the first reference data topic through the screen pipeline — the calendars run, step by step.
- User Journey: Keep a holiday calendar right — a judged journey, the shape step 1 produces.
- Keep a holiday calendar right prototype — a signed off prototype and its note.
- Test Scenario: Verify the holiday calendar screens — a scenario run by the owner.
- How do I sign off a screen? — the sheet and the verdict.
- UX — the structure note that orders the UX cluster.