# 5 · Review: look, then check through six lenses

You tend to say "done" when the code is written. A designer says "done" when
the work has been looked at, by them and in their head by everyone it
affects. Do the same.

---

## Step 1 · Look at it

**Rule:** Render what you built and look at actual screenshots. Do not
review your own code and imagine the result.

Look at:
- widths **375** (phone) and **1280** (desktop), plus 768 if the layout changes;
- **light and dark** mode, if supported;
- at least one **empty**, one **error** and one **long-content** state.

If you cannot render (no browser available), say so clearly in your report.
Never claim something looks right without having seen it.

**Agent trap:** reading your CSS and concluding "this will look balanced".
Your prediction of a layout is often wrong in exactly the details humans
notice first: wrapping, overflow, alignment.

---

## Step 2 · Six lenses

Go through each lens. Each takes a minute. Fix what you find **before**
reporting, not after.

### Lens 1 · The user (5-second test)
- [ ] In five seconds, can someone tell what this is and what to do first?
- [ ] Is the primary action obvious, and is it the right one?
- [ ] Could a first-time user finish the main job without help?

- [ ] **Predict, then click:** for each control, write what a person would
      expect it to do, then click it. Any surprise is a bug, even if it "works".
      Run `checks/affordance.js`.
- [ ] **Act, then measure:** run `checks/stability.js` on every action that
      loads, saves, sends or shows a message, using long realistic content
      (a 50-character email, a long error), at 375 and 1280. The button you
      pressed must not move or resize, while loading or after.

### Lens 2 · The designer
- [ ] **Squint test:** blurred, is the hierarchy still right?
- [ ] Everything aligns to a shared edge or grid. No "almost aligned".
- [ ] Spacing between groups is clearly larger than within groups.
- [ ] **Measure, don't eyeball:** run `checks/spacing.js` at 375 and 1280 on
      every section. Small gaps (0–4px) are nearly invisible in a screenshot,
      and they are the first thing a designer sees.
- [ ] Every value comes from the system (run the checks in `2-system.md`).
- [ ] Nothing from the cliché list (`7-avoid.md`).

### Lens 3 · The writer
- [ ] Buttons say what they do, with a verb: "Save changes", not "OK" or "Submit".
- [ ] Headings make sense without the text under them.
- [ ] No jargon, no filler ("Seamlessly unlock…"), no exclamation marks.
- [ ] Errors say how to fix the problem.
- [ ] Empty states say what this is and give a first action.
- [ ] Copy is real and specific, not lorem ipsum or generic placeholders.

### Lens 4 · The product manager
- [ ] Does it do the **one job** from the brief?
- [ ] Did you build anything that wasn't asked for? Remove it, or flag it.
- [ ] **Decision screens:** if this screen asks someone to choose, can they
      decide from this screen alone? Check the seven points in `3-humans.md` B5.
- [ ] Are the edge cases covered: none, one, many, failed, no permission?
- [ ] What would a stakeholder ask in the first review meeting? Answer it now.

### Lens 5 · The engineer (the next person to touch this)
- [ ] Zero raw colours or off-scale values outside the token file.
- [ ] One definition per component; no copy-pasted variants.
- [ ] Semantic HTML; no `div onClick`, no `!important`, no inline styles.
- [ ] Names are clear; no dead code; no unused tokens.
- [ ] Someone new could add a screen by reusing what's there.

### Lens 6 · Accessibility
- [ ] Tab through everything: logical order, visible focus, nothing trapped.
- [ ] Text contrast ≥ 4.5:1; UI boundaries ≥ 3:1.
- [ ] Every input has a label; every icon-only button has an accessible name.
- [ ] Colour is never the only signal.
- [ ] Reduced motion respected; works at 200% zoom and 320px wide.

---

## Step 3 · Report honestly

Your report to the human starts with the outcome, then:

1. **What you built**, in one or two sentences.
2. **Assumed**: the guesses from your brief, so they can correct them in one reply.
3. **Not done or not verified**: anything you skipped or couldn't check
   (for example "didn't test with a screen reader").
4. **Decisions worth knowing**: tokens created, taste translation, trade-offs.

**Agent trap:** a report that lists everything you did, so the one thing that
didn't work is buried. Lead with the outcome; surface the gaps.