Design Review on Every PR

This is the closing module of the course, and it is where the earlier modules stop being separate practices and become one habit. Critique loops, heuristic findings, screenshot baselines, accessibility passes — all of them are valuable as occasional projects, but design quality mostly degrades between those projects, one merge at a time. The end state this module describes is a review that runs on every pull request that touches the interface, scoped to what the branch actually changed.

Set expectations about scale honestly. The gate described here is not a full design review of the product on every merge; it is a narrow, mechanical review of the diff, with humans pulled in only when the findings need judgment. That narrowness is what makes it sustainable. A gate that tries to check everything blocks everything, and a blocked team routes around the gate within a fortnight.

If participants have not done Modules 3 and 4, the screenshot-evidence and accessibility material here will still make sense, but point them back: the per-PR gate reuses the capture-and-diff and accessibility techniques from those modules at smaller scope, not new ones.

The argument for putting design review on the pull request is an argument about cost and timing, not about distrust of engineers. Engineers reviewing a UI pull request are reading it for logic, naming, and side effects — that is their job. Nobody in that review is checking whether the new badge colour exists in the token set, whether the gap below 768 pixels collapsed, or whether the new dialog's close button still has a focus ring. Each of those slips is small and individually defensible, which is exactly why they accumulate.

The timing point matters as much as the coverage point. When a finding is raised while the branch is open, the author still has the whole change in their head, the preview is already built, and the fix is usually a one-line commit. The same finding discovered after release becomes a bug report, a triage discussion, a regression risk assessment, and often a debate about whether it is worth fixing at all. The work is identical; the overhead is not.

The historical blocker has been cost: no design team can manually review every UI branch at three widths with a token check and an accessibility pass. The previous modules established that an agent can run each of those checks reliably when the procedure is written down. This module is about writing the procedure down once and attaching it to the place changes actually happen.

Spend as much time on the last row as on the first four. The strongest temptation when setting this up is to keep adding checks — copy review, performance budgets, full-product heuristics — because each one is individually valuable. Resist it. Every check added to the per-PR gate adds run time, adds findings the author has to read, and adds opportunities for false positives. The gate's authority comes from being fast, scoped, and almost always right; that is what earns it the right to run on every branch.

The four in-scope checks are the ones the previous modules made cheap. The visual diff is Module 3's capture-and-compare technique, narrowed to changed screens only. Token usage is the same kind of mechanical rule the design-system maintenance loop relies on: raw values in component code that have a token equivalent. Accessibility is Module 4's automated-plus-keyboard pass, on changed routes only. States matter because the diff is where new states are born, and a state nobody captured is a state nobody designed.

Note what the scoping buys operationally: a branch that touches two screens gets a two-screen review, and the whole run typically lands in the ten-to-twenty-minute range. The full-surface reviews from Modules 2 and 3 still exist — they just run on a release or quarterly cadence, not per branch.

The mechanical heart of the gate is a small set of reviewer definitions checked into the repository — in the Claude Code version of this workflow they live in .claude/agents/, and the saved workflow command that orchestrates them lives in .claude/workflows/. The token reviewer shown here is the workhorse: it reads only the changed component files, flags raw values that have a token equivalent, and reports file, line, value, replacement token, and severity. The two constraints in its definition matter most: it must say when no reasonable token exists rather than inventing a mapping, and it must not report style preferences. Both rules exist because they are the two ways automated reviewers lose a team's trust.

Component and anti-pattern checks follow the same shape. Component rules catch the one-off variant built under deadline pressure and the primitive that got bypassed; anti-pattern rules encode the things your team has explicitly decided not to do. The important property is that these are your team's named rules written down, not a generic linter's opinion. If a rule is not written down, the gate cannot check it — which is also a useful forcing function for actually writing the rules down.

The versioning point deserves emphasis with design leads. Because the reviewers are files, tightening or loosening the standard is itself a pull request: visible, discussed, and applied to everyone's next run. That is the difference between a shared quality bar and whichever reviewer happened to be grumpy that week.

Module 3 made the case that visual review needs evidence rather than memory; the per-PR gate is where that evidence becomes routine. For each changed screen, the run captures the branch and main at the same widths, diffs them, and attaches the capture paths to the relevant finding. The difference this makes to the author is practical: they see the regression rather than being told about it, and they can judge in seconds whether the difference is the change they intended or a side effect they did not.

The quality bar for the findings comment decides whether the gate gets respected or routed around. A vague comment — the new badge colour looks off-brand — generates a debate. A precise one — Badge.tsx line 24 uses a hex value not in the tokens, the closest token is the warning colour, evidence at this capture path — generates a commit. Every finding should carry severity, evidence, user impact, and a concrete fix. Spot-check the first few runs and tighten the reviewer instructions if findings drift towards generalities.

There is also a quiet cultural benefit worth naming: the screenshot evidence gives engineers a way to see what the designer would have seen. Over a few weeks of reading these comments, authors start catching the issues before the gate does, which is the real win — the gate is a teaching mechanism as much as a catching mechanism.

Walk the diagram left to right along the top, then right to left along the bottom. The pull request opens and the previews build — that is the author's only setup cost. The agent scopes the run by mapping the diff to screens and states using a routes map kept in the repository; when the map misses a component, the gate reports the gap rather than silently skipping it, which is how the map improves over time. The automated checks and the capture-and-critique pass then run in parallel — same reviewers, same widths, every branch.

The bottom row is where judgment lives. The merged summary is posted on the pull request with severity, evidence, and a fix per finding. The designer decision gate is deliberately narrow: most pull requests never reach it, because nothing block-level was found and the author simply fixes the warn-level items. When it is reached, the questions are the ones only a person can answer — is this deviation intentional, does this block the merge, is the severity right. Then the author fixes the branch and the same command re-verifies before merge.

Point at the dashed line last, because it is the part teams forget. A finding that appears on every third pull request is not a review problem; it is a missing rule. Encoding it — in the instruction file, the reviewer agent, or the component itself — is what makes the gate get quieter over time instead of noisier. A gate whose finding count never drops is a gate nobody is learning from.

Severity exists to answer one question: who has to look at this finding, and does it stop the merge. Three levels are enough to answer it, and they map cleanly onto the P0-to-P3 scales most teams already use for bugs — block covers P0 and P1, warn covers P2, note covers P3. Adding more levels feels rigorous and in practice just moves the argument from whether something blocks to which of five labels it deserves.

The definitions need to be written for your product, not copied from a slide. What counts as a primary surface, which flows are revenue-critical, which token violations are brand-level rather than cosmetic — those are decisions the design lead makes once, writes into the reviewer instructions, and adjusts as the first weeks of findings show where the lines actually fall. The waive option on block-level findings is not a loophole; it is what keeps the gate honest. There are legitimate reasons to ship with a known issue, and recording the waiver with a reason is far healthier than pressuring the gate to stay quiet.

The note level earns its place over time. Notes are where the gate reports the things that are not the author's fault — a value with no token equivalent, a screen missing from the routes map — and routing those to the design-system owner is how the gate feeds the system instead of just policing it.

The escalation rules are what make every PR honest rather than aspirational. Without them, one of two things happens: the designer tries to read every findings comment and burns out within a month, or nobody reads them and the gate becomes decoration. The list on the slide is deliberately short — block disputes and waivers, intentional visual changes, genuinely new surfaces, gaps the gate itself reports, and severity arguments. Everything else is between the author and the gate.

The intentional-change case is worth dwelling on, because it is the most common escalation in practice and the one the gate genuinely cannot decide. A visual diff only shows that something changed; whether the change is an improvement is a design judgment. The protocol is simple: the author marks the diff as intended, and someone with design authority looks at the capture and agrees or pushes back. That is a two-minute review with the evidence already attached, which is exactly the kind of review a designer can do twenty times a week without it consuming the week.

Make the escalation path concrete: a named person or rotation, an expected response time, and a rule for what happens when nobody responds — usually that warn-level changes proceed and block-level changes wait. An escalation path that is just a channel where comments accumulate is how the gate quietly dies.

Most per-PR review efforts that die do not die because the checks were wrong; they die because the experience of being checked was annoying. The failure sequence is predictable: the gate is noisy, authors learn that most findings are ignorable, they stop reading the comments, then a real block-level finding gets ignored along with the noise, and the team concludes the gate does not work. The defences are operational, not technical, which is why this slide is a checklist rather than a concept.

The noise budget is the most important line. Track the false-positive rate from the first week, and treat exceeding the budget as a defect in the reviewers — tighten the instructions, narrow the rules, or remove the check — rather than as a tax authors should tolerate. The twenty-minute ceiling is the second one: a gate that takes an hour gets run overnight, then gets run sometimes, then stops being a gate.

The rollout advice is to start soft. A soft requirement — UI-labelled pull requests need the findings comment before merge, but nothing physically prevents merging — builds the habit and surfaces the false positives while the stakes are low. Promote it to a hard requirement only for the block level, only once the team trusts the findings. And keep the monthly review of the gate itself: a standing gate that nobody ever re-examines becomes bureaucracy by default, even if it started well.

The honest measure of a per-PR design review is escapes: regressions of the kinds the gate checks for, found after merge by users, support, or a later audit. That is the number that was painful enough to justify the gate, and it is the number to keep reporting. Track it before the rollout if you can, even roughly — a quarter's worth of after-the-fact regressions is a baseline that makes the later comparison meaningful rather than anecdotal.

The supporting numbers guard against the two ways the headline number can mislead. The catch profile and fix rate show whether findings are actually being acted on or just generated. The cost numbers — run minutes, designer minutes on escalations — are what you weigh the catches against, and they are also the early warning for the social failure on the previous slide. Waivers are worth counting because a rising waiver rate means either the severity definitions are miscalibrated or the team is under delivery pressure that no gate will fix.

The trend line is the subtle one: a healthy gate's finding count should fall over months, because recurring findings become harness rules, fixed components, and better defaults — the issues stop being made rather than stop being caught. A gate that catches the same number of the same findings forever is technically working and organisationally failing. Be careful not to turn any of these numbers into individual performance metrics; the moment finding counts attach to people, the incentive becomes avoiding the gate rather than improving the work.

This case is drawn from the school's published Design QA on Every PR workflow, and it is worth presenting precisely because it is unglamorous. The team's starting condition is the common one: one designer, four engineers, UI pull requests merging weekly or faster, and a quarter in which three visual regressions reached customers — including a pricing table that lost its column alignment on tablets. The designer could not review every branch; the engineers did not know what to look for. The gate was adopted as a soft requirement: any pull request labelled ui needs the findings comment before merge.

Walk the numbers as a profile rather than a benchmark. Forty-seven gated pull requests in six weeks, about fourteen minutes per run. Nine block-level findings, the largest being a refactor that silently dropped the focus ring from every dialog close button — exactly the class of regression that passes engineering review because the code still works. Forty-one warn-level findings, mostly token violations, mostly fixed on the branch within the day. Escapes dropped from roughly one a week to one in the whole period.

The single escape is the most instructive row. It happened on a screen missing from the routes map — and the workflow's design is that map gaps are reported in the findings rather than silently skipped, so the team could see the blind spot and close it. That is the realistic promise of the gate: not zero escapes, but escapes that arrive with an explanation and a one-line fix to the map. These figures are from one team on one product; treat them as a shape to expect, not a guarantee to quote.

This exercise produces the document that makes the rollout possible: the gate's rules, written before the gate runs. Most of the difficulty is not technical. Deciding what blocks a merge in your product, who answers escalations, and what false-positive rate you will tolerate are team agreements, and writing them down on one page is what turns this module from an idea into a proposal someone can say yes to.

Steer participants towards specificity. A good severity definition names the surfaces — checkout blocks, the marketing footer warns. A good escalation line names a person or a rotation, not the design team. The routes-map sketch should cover one product area, not the whole product; the map grows by being used, and the gate reporting its own gaps is part of the design. The widths and check list can be lifted directly from this module and adjusted later — those are the easy 20 per cent.

The last bullet is the one to insist on. The people who will live with this gate daily are the engineers whose pull requests it comments on, and rules they helped write get respected in a way that rules announced to them do not. If participants do one thing after this course, having that one-page review with their engineering counterparts is the highest-leverage option available.

Close the module by closing the course, because this module is the destination the earlier ones were building towards. Module 1 gave critique a structure — named dimensions, evidence, the split between actionable findings and judgment calls. Modules 2 and 3 made evaluation and visual evidence affordable at scale. Module 4 made accessibility and content review routine. This module wires the per-change subset of all of that into the place changes actually happen, with humans reviewing what matters instead of everything or nothing.

Restate the honest limits one last time. A clean run means the branch did not regress the things the gate checks on the screens the routes map knows about. It does not mean the design is good, the flow makes sense, or the change should ship. Automated accessibility checks cover well under half of the relevant guidance, visual diffs are noisy around animation and live data, and taste never came from the gate in the first place. The gate makes human review cheap and consistent; it is not a substitute for it.

For participants asking what to study next: Design Systems for Agents covers the token and component infrastructure this gate enforces — the better the system, the quieter the gate. Orchestrating Design Agent Teams covers running multiple reviewer agents and workflows like this across a portfolio. And the school's published Design QA on Every PR workflow is the hands-on companion to this module, with the prompts, reviewer definitions, and the saved-command setup ready to adapt.