visual-review

Name: visual-review
Author: lucasfcosta

62stars1forks

How to install visual-review?

lucasfcosta/backpressured/visual-review

$npx -y skills add lucasfcosta/backpressured --skill visual-review

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Visual Review
2
3	## Overview
4
5	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.
6
7	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.
8
9	## When to Use
10
11	- 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.
12
13	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.
14
15	## Step 1 — Capture the current UI
16
17	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.
18
19	## Step 2 — Get the design reference
20
21	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.
22
23	## Step 3 — Compare region by region
24
25	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:
26
27	- Layout & structure: correct elements, in the right order and proportions.
28	- Spacing: padding, margins, and gaps between fields/sections — the most common and most-missed mismatch.
29	- Alignment: fields, labels, and edges line up; nothing visually drifts.
30	- Typography: size, weight, family, and case match for headings, labels, and body.
31	- 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.
32	- Components & completeness: every element in the design is present (and nothing extra); icons, buttons, and inputs styled to match.
33	- Interactive states: hover, focus, disabled, and error styling — not just the default state.
34	- Responsive: if the design specifies breakpoints, check them; don't silently verify only one width.
35
36	## Step 4 — Report, fix, re-verify
37
38	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.
39
40	Passing = every region matches the reference with no outstanding BLOCKER/SHOULD discrepancies, verified at the design's target viewport(s).
41
42	## Common rationalizations
43
44	\| Rationalization \| Reality \|
45	\|-----------------\|---------\|
46	\| "It looks fine to me at a glance" \| A glance catches gross breakage and misses everything subtle. Go region by region. \|
47	\| "I checked the one default viewport" \| If the design specifies breakpoints, an unchecked width is an unverified design. \|
48	\| "I couldn't find the Figma, but it's probably right"

People who liked this also viewed

6 picks

Type

visual-review

62stars1forks

View on GitHub

How to install visual-review?

lucasfcosta/backpressured/visual-review

$npx -y skills add lucasfcosta/backpressured --skill visual-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Visual Review
2
3	## Overview
4
5	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.
6
7	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.
8
9	## When to Use
10
11	- 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.
12
13	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.
14
15	## Step 1 — Capture the current UI
16
17	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.
18
19	## Step 2 — Get the design reference
20
21	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.
22
23	## Step 3 — Compare region by region
24
25	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:
26
27	- Layout & structure: correct elements, in the right order and proportions.
28	- Spacing: padding, margins, and gaps between fields/sections — the most common and most-missed mismatch.
29	- Alignment: fields, labels, and edges line up; nothing visually drifts.
30	- Typography: size, weight, family, and case match for headings, labels, and body.
31	- 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.
32	- Components & completeness: every element in the design is present (and nothing extra); icons, buttons, and inputs styled to match.
33	- Interactive states: hover, focus, disabled, and error styling — not just the default state.
34	- Responsive: if the design specifies breakpoints, check them; don't silently verify only one width.
35
36	## Step 4 — Report, fix, re-verify
37
38	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.
39
40	Passing = every region matches the reference with no outstanding BLOCKER/SHOULD discrepancies, verified at the design's target viewport(s).
41
42	## Common rationalizations
43
44	\| Rationalization \| Reality \|
45	\|-----------------\|---------\|
46	\| "It looks fine to me at a glance" \| A glance catches gross breakage and misses everything subtle. Go region by region. \|
47	\| "I checked the one default viewport" \| If the design specifies breakpoints, an unchecked width is an unverified design. \|
48	\| "I couldn't find the Figma, but it's probably right"

People who liked this also viewed

6 picks

Type