Trigger: Use when "visual QA", "visual validation", "compare to reference". Screenshots localhost, compares to reference, fixes gaps in up to 3 passes.
Step 1: Animation Detection (CRITICAL — Do This First)
Before starting the loop, scan the project for animation libraries and CSS animations. If animations are detected AND they are the primary element being reviewed, halt and offer options: skip the visual QA loop, static-only pass (screenshot anyway but only evaluate static elements), or disable animations temporarily.
Step 2: Establish Reference Target
Option A: Screenshot File — User provides a screenshot. Read it with the Read tool to visually analyze it before starting.
Option B: Described Aesthetic — User describes the target verbally: "dark brutalist vibe with orange accents", "clean SaaS landing page with gradient hero", etc. Document key visual attributes.
Option C: Live URL Reference — Screenshot a live URL for comparison using: npx playwright screenshot --full-page https://example.com temp-screenshots/reference-full.png
Step 3: Screenshot Loop (Max 3 Passes)
For each pass:
- Capture Screenshots:
npx playwright screenshot --full-page http://localhost:PORT temp-screenshots/pass-N-full.png - Visual Analysis — Read screenshots and evaluate against reference target. Score each dimension: Typography (font family, sizes, weights, line-height, hierarchy), Colors (background, text, accents, gradients, borders, shadows), Spacing (padding, margins, gaps, section spacing, alignment), Layout (grid structure, flexbox alignment, responsive behavior), Components (all expected elements present), Polish (border radius, shadows, hover states, transitions, icons).
- Report and Decide — If satisfied: stop loop early. If not satisfied and passes remain: list specific changes needed and make them. If max passes reached: report best effort with remaining issues.
Error Handling
- Server not running: Attempt to start it. If it fails, report the error and stop.
- Playwright not available: Install chromium browser via
npx playwright install chromium - Screenshot fails: Check if the URL is accessible. Common issues: wrong port, server crashed, build error.
- Build errors after fix: If a code fix introduces a build error, revert the fix and try an alternative approach before the next pass.