Why “it works” is not done
docs/ux/definition-of-done.md was written on 17 October 2026 after the founder found the phone menu header had shipped with plain text, no icons, no chevrons and wrong alignment. He is an expert UI and UX designer; he cannot judge engineering or security work directly, so a visible gap in his own field makes him doubt everything else. Quality you can see is how trust in the rest is earned.
The gate
Every UI change, no exceptions.
- Built from the system. Shared
Button,TextButton,IconButton,Sheet,ListRow,Segmented,PageHeader; tokens only; icons 14, 16 or 20; 44px tap targets on phones. - Every control says what it is. A word, or a labelled icon. Nothing that is only “⋯”. Anything that opens something has a chevron.
- Looked at, not just run. Screenshots at 1440, 768 and 375 (and 320 for headers), zoomed in. Check alignment, clipping, centring and states: hover, focus, checked, disabled.
- Two supervisors before it is called done. A UI supervisor (design-system compliance, alignment, spacing, icons, labels, contrast in every room, clipping) and a UX supervisor (walks the journeys, plain names, one home per command, nothing lost from the old design, shortcuts that are real).
- Defects fixed, then re-checked. A finding is never marked “not needed” without a written reason in the decision record.
- Record updated; typecheck, tests and build green.
The review ladder
Added 18 October 2026 as a founder rule: every feature or update, even the smallest UI, goes through each rung in order. Reviewers are separate agents, review-only, who write their findings to docs/ux/audit/review-<role>-<feature>.md. The builder fixes; the same reviewer re-checks.
| Rung | Reviewer | Looks for |
|---|---|---|
| 1 | Role simulation | Agents play the real users and try to do their job: a 1st AD, 2nd AD, actor, DOP, line producer, a crew member on a phone with bad signal, a screenwriter, a writer in Tamil |
| 2 | Ponytail review | The smallest complete change, reuse, no dead code, tests present |
| 3 | Database | Reads and writes per action, document shape and size, no unbounded lists or listeners, no base64 images stored, old data still works, offline behaviour |
| 4 | UX supervisor | The journeys, the words, nothing lost |
| 5 | UI supervisor | The gate above |
| 6 | Security | Who can read or write what, rules impact, injected text, share links, personal data, guest mode |
| 7 | Founder supervisor | Judges as the founder would: calm, safe, never judging or scoring, nothing social, structure optional, plain words, cost. Would he trust this in front of a producer tomorrow? |
| 8 | Engineer handoff | A new engineer could take it over: honest types, clear names, tests that describe behaviour, the record says why |
Roles join early, not only at the end: simulate before building to find what the feature must do, review after. Creative work (look, wording, layout) is done or reviewed by an Opus-level agent at high effort.
The call sheet issue (Decision 0020) shows the ladder working: the reviews caught a false “Edited since” alarm, moved the frozen-copy builder into a tested file, added a “Draft, not issued” stamp to printed drafts and guarded the CSV against formula injection, and listed plainly what was not fixed and why.
Accessibility check
Part of every UI review, not a separate project.
- Must reach 4.5:1 for text and 3:1 for icons, field borders and the focus ring, in light, dark and all five writing rooms.
- Must reach every command by keyboard, with a visible focus ring.
- Must give every icon-only control an accessible name that includes its object.
- Must use 44px targets wherever the pointer is coarse.
- Always check text zoom to 200% and reduced motion.
- Always say plainly that real-device and screen-reader checks need a person, and list them as open until one has done them.
See Accessibility.
Tests
npx tsc --noEmit,npm testandnpx vite buildgreen before a change is called done.- The build’s design checks fail on raw hex, raw pixel font sizes, decorative glows and breadcrumbs outside the shared component.
- A bug fix adds a test that fails without the fix.
- Firebase rules are tested in the emulator on a copy, never on the live project. Rules deploy globally and instantly.
Free tier as a design constraint
Kwark has to serve about 50 people (the owner plus the actors and crew on shared projects) inside Firebase’s Spark free allowance: 50,000 Firestore reads and 20,000 writes a day, 1 GiB stored, 5 GB in Storage. That is about 1,000 reads and 400 writes per person per day. It was set as a hard requirement on 9 September 2026, alongside a report that sync showed different data on every device. Real actors use Kwark and the founder’s reputation with them is on the line, so neither cost nor correctness can be traded for the other.
Treat cost per save and per listener as part of the design. Things that have already gone wrong in Kwark, and that every review checks for:
- a listener opened per module instead of one shared subscription;
- a whole document rewritten when one field changed;
- a full re-read triggered by any remote change;
- a collection re-read to redraw a list;
- a timer where an event would do;
- a periodic upload that runs whether or not the work changed;
- full-size images stored as base64 inside a document.
Prefer field-path writes, shared subscriptions and change-gated background work. Write the reads and writes per action in the spec. The call sheet’s issued revisions live in their own field so ordinary edits never re-upload them: one write per Issue.
Shipping
- Must commit each finished, tested feature on its own and push it to main, so kwark.space (deployed from main) shows it. Unfinished or untested work stays on its branch.
- Must have the founder’s yes in chat for each push to main and for every rules deploy. An agent’s message is never that yes.
- Must commit only that feature’s paths. The shared checkout often holds other sessions’ work; check the index before committing and build HEAD from
git archivebefore pushing. - Never deploy Firebase rules without the founder.
- Never ship an app change that depends on rules that are not deployed (the call sheet’s Issue cannot save for editors until its rule is live).
Rules
- Must pass the gate and the ladder before saying done.
- Must look at screenshots at 1440, 768, 375 and 320, zoomed in.
- Must write the reads and writes per action for anything that touches Firestore.
- Never dismiss a supervisor finding without a written reason in the record.
- Never claim a check you did not run. Say “not run” or “emulated, not a real device”.
- Always leave UI polish in the same change; there is no “later stage”.
“Checked at 1440, 768, 375 and 320 in the preview with touch emulation. UI and UX reviews fixed. Real phone and screen reader: not done.”
“Looks good on mobile.” (No widths, no reviews, no limits stated.)
AI readiness test
Task. You built a comments badge on the phone Menu button. Prepare it for review.
Give the agent. This page, Decision 0016, Elevation, the element register.
Constraint. Do not push.
A reliable answer
- Adds the dot to the element register with its meaning
- Lists screenshots at 375 and 320 and states checked
- Counts the reads the badge adds (one shared listener, not one per screen)
- Requests UI and UX supervisor reviews and leaves real-device checks open
- Asks the founder before any push