Visual QA
Evidence first
Do not critique only source code. Render the real interface.
Default sequence
- ensure the target app runs;
- settle the intended capture state: await fonts, promote/decode lazy media, and disable nondeterministic motion;
- assert that critical content is visible before accepting a baseline, including in reduced-motion or JavaScript-failure states;
- capture all configured viewports;
- inspect full-page composition and first viewport separately;
- test critical interactive states;
- inspect keyboard focus and sticky/fixed overlays;
- inspect utility/micro text at native screenshot scale—technically present text can still be functionally illegible;
- test reduced-motion mode;
- check horizontal overflow and console/page errors;
- use Playwright visual baselines for stable views;
- hand screenshots to
$design-criticwithout implementation justification.
Defect format
For each issue record:
- severity: blocker / major / moderate / minor;
- viewport/state;
- observed evidence;
- design/UX impact;
- likely root cause;
- recommended correction scope: system / section / component / micro.
Stability
Visual baselines are environment-sensitive. Keep the comparison environment consistent and only update baselines after reviewing the diff. A passing pixel comparison is not evidence when its baseline recorded hidden critical content or media that had not finished decoding.
Use scripts/capture-screenshots.mjs and tests/visual.spec.ts as starters.


