visual-review

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.