# Review and quality

> What "done" means for a Kwark change: built from the system, looked at in screenshots, reviewed by separate supervisors, tested, inside the free-tier budget, then shipped to main one feature at a time.

Source: https://kwark.space/designSystem/method/review-and-quality

## 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.

1. **Built from the system.** Shared `Button`, `TextButton`, `IconButton`, `Sheet`, `ListRow`, `Segmented`, `PageHeader`; tokens only; icons 14, 16 or 20; 44px tap targets on phones.
2. **Every control says what it is.** A word, or a labelled icon. Nothing that is only "⋯". Anything that opens something has a chevron.
3. **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.
4. **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).
5. **Defects fixed, then re-checked.** A finding is never marked "not needed" without a written reason in the decision record.
6. **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](https://kwark.space/designSystem/foundations/accessibility.md).

## Tests

- `npx tsc --noEmit`, `npm test` and `npx vite build` green 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 archive` before 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".

**Do:** "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."

**Don't:** "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
