Visual QA
A functional test says the button works. Visual QA says the button looks like
a button — on a 375px phone, at 1440px desktop, in dark mode, with the CJK
font loaded.
The workflow
- Capture. Screenshot the surface through its real renderer:
- Web: Playwright
page.screenshot() or agent-browser --cdp screenshot
- TUI: xterm.js web terminal (never
tmux capture-pane — it degrades
truecolor and wide-glyph width)
- Documents: open the PDF/PNG, don't read the source
- Compare. Against the design brief, the previous baseline, or the
reference the user provided. Look for: layout collapse, text clipping,
CJK glyph corruption, color contrast failures, broken responsive
breakpoints, and the three AI-default looks (cream+serif+terracotta,
near-black+acid-green, broadsheet hairlines).
- Verdict. Good / Bad with specific evidence: screenshot path, the exact
element or region that fails, and what the fix is. "Looks fine" without a
screenshot is not a verdict.
What to check
| Surface |
Failures to hunt |
| Web page |
Responsive breakpoints, focus rings, reduced-motion, font loading |
| Component |
Padding/margin collapse, text overflow, hover states, disabled states |
| TUI |
Truecolor, wide-glyph alignment, box-drawing drift, CJK rendering |
| Document/PDF |
Page breaks, image scaling, font embedding, print colors |
| Generated art |
The design brief — does it match the philosophy that produced it |
Baselines
Keep a qa/baselines/ directory per project. Capture the current state
before any visual change; diff after. A baseline that is not updated when the
design intentionally changes is worse than no baseline — it trains you to
ignore failures.
Pairs with
webapp-testing (drive the browser to the state worth capturing),
design (the taste standard the verdict is judged against),
webapp-testing (functional QA on the same surface).
1---2name: visual-qa3description: Visual QA4---56# Visual QA78A functional test says the button works. Visual QA says the button looks like9a button — on a 375px phone, at 1440px desktop, in dark mode, with the CJK10font loaded.1112## The workflow13141. **Capture.** Screenshot the surface through its real renderer:15 - Web: Playwright `page.screenshot()` or `agent-browser --cdp screenshot`16 - TUI: xterm.js web terminal (never `tmux capture-pane` — it degrades17 truecolor and wide-glyph width)18 - Documents: open the PDF/PNG, don't read the source192. **Compare.** Against the design brief, the previous baseline, or the20 reference the user provided. Look for: layout collapse, text clipping,21 CJK glyph corruption, color contrast failures, broken responsive22 breakpoints, and the three AI-default looks (cream+serif+terracotta,23 near-black+acid-green, broadsheet hairlines).243. **Verdict.** Good / Bad with specific evidence: screenshot path, the exact25 element or region that fails, and what the fix is. "Looks fine" without a26 screenshot is not a verdict.2728## What to check2930| Surface | Failures to hunt |31|---|---|32| Web page | Responsive breakpoints, focus rings, reduced-motion, font loading |33| Component | Padding/margin collapse, text overflow, hover states, disabled states |34| TUI | Truecolor, wide-glyph alignment, box-drawing drift, CJK rendering |35| Document/PDF | Page breaks, image scaling, font embedding, print colors |36| Generated art | The design brief — does it match the philosophy that produced it |3738## Baselines3940Keep a `qa/baselines/` directory per project. Capture the current state41before any visual change; diff after. A baseline that is not updated when the42design intentionally changes is worse than no baseline — it trains you to43ignore failures.4445## Pairs with4647`webapp-testing` (drive the browser to the state worth capturing),48`design` (the taste standard the verdict is judged against),49`webapp-testing` (functional QA on the same surface).
trac3r00