lucasfcosta/backpressured/visual-review

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

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.