| name | visual-review |
| description | Use when a backpressured loop has a front-end/UI change and needs to compare the rendered result against its design reference (a Figma frame or images on a Linear ticket) — catching layout, spacing, contrast, and visual-consistency defects automated tests and happy-path clicking miss. |
Visual Review
Overview
You are the machine the producer ran so a visual defect wouldn't reach a human — or a user — first. Lint, types, and tests say nothing about whether the page looks right: layout, spacing, color contrast, and overall aesthetics live in a gap that automated checks and a quick manual click-through don't cover. This review is backpressure for that gap.
Core principle: structured region-by-region comparison against the real design, not one gestalt glance. A single "looks fine to me" glance reliably catches gross breakage and reliably misses the spacing, weight, and color mismatches that make a UI feel off. Break it down so the subtle issues have nowhere to hide.
When to Use
- A
backpressured loop has a front-end/UI change and a design reference to check it against — per-iteration on the changed view, and on the whole feature before done.
Not for: non-UI changes (skip it); pixel-perfect automated regression diffing (this is a structured human-style review, not a pixel diff). If there is no design reference available, say so and don't fake a pass — a review against nothing is not a review.
Step 1 — Capture the current UI
Run the app locally and drive a real browser with the Playwright MCP. Navigate to the changed view and screenshot it at the viewport(s) the design targets (e.g. 1280/1440 desktop; the design's mobile width if it specifies one). Take a full-page screenshot plus per-region screenshots so you can look at each area closely — a full-page shot alone is too coarse to catch local issues. Capture each region with a per-element screenshot (Playwright's locator(...).screenshot() / element clip), not by cropping the full-page image by eye — a real element shot is what lets you measure against the design.
Step 2 — Get the design reference
Obtain the source of truth and actually look at it: the Figma frame, or the images attached to the Linear ticket (pull them via the Linear MCP). Read the image files so you can see them — you cannot compare against a reference you haven't loaded. If you genuinely can't get one, stop and report that; do not approve by default. If a Figma frame and a ticket image disagree, treat Figma as authoritative unless the ticket explicitly overrides it.
Step 3 — Compare region by region
Walk the page in pieces — header → main content → footer, then components within each — comparing your screenshot to the design for that region. For each region, check:
- Layout & structure: correct elements, in the right order and proportions.
- Spacing: padding, margins, and gaps between fields/sections — the most common and most-missed mismatch.
- Alignment: fields, labels, and edges line up; nothing visually drifts.
- Typography: size, weight, family, and case match for headings, labels, and body.
- Color & contrast: backgrounds, text, accents/primary; flag text below WCAG AA (4.5:1 normal text, 3:1 large) rather than judging "low contrast" by eye.
- Components & completeness: every element in the design is present (and nothing extra); icons, buttons, and inputs styled to match.
- Interactive states: hover, focus, disabled, and error styling — not just the default state.
- Responsive: if the design specifies breakpoints, check them; don't silently verify only one width.
Step 4 — Report, fix, re-verify
Report each discrepancy with a severity — [BLOCKER] wrong/missing element, wrong color, broken layout · [SHOULD] clear spacing/typography/alignment mismatch · [NIT] sub-pixel or barely perceptible — plus the region and the specific difference (not "spacing looks off" but "32px gap above the form vs ~16px in the design"). Get those numbers from real measurements — the rendered element's computed box (browser devtools / Playwright boundingBox()) against Figma's measured values — not by eyeballing pixels off a screenshot, or your "specific" finding is just a dressed-up guess. Fix the BLOCKER/SHOULD findings, re-screenshot, and re-compare — a fix you didn't re-capture isn't verified.
Passing = every region matches the reference with no outstanding BLOCKER/SHOULD discrepancies, verified at the design's target viewport(s).
Common rationalizations
| Rationalization | Reality |
|---|
| "It looks fine to me at a glance" | A glance catches gross breakage and misses everything subtle. Go region by region. |
| "I checked the one default viewport" | If the design specifies breakpoints, an unchecked width is an unverified design. |
| "I couldn't find the Figma, but it's probably right" | A review against no reference is not a review. Get the reference or report that you can't. |
| "Close enough on spacing/weight" | "Close enough" with a number ("16 vs 32px") is a finding; "close enough" without one is a guess. |
| "I only need the default state" | Hover/focus/disabled/error are part of the design too. Check them. |
| "I fixed it, no need to screenshot again" | An un-recaptured fix is an assertion. Re-screenshot and re-compare. |
Red flags — STOP
- Approving from a single full-page glance with no per-region comparison.
- Passing with no design reference actually loaded and viewed.
- Reporting "spacing looks off" with no specific before/after measurement.
- Verifying only the default state or a single viewport the design didn't limit you to.
- Calling a fix done without re-screenshotting it.
