design-visual-qa

Family: design Status: Stable

Purpose

Visual regression for the rendered surface — the visual analog of seo-drift. Captures snapshots at multiple viewports and compares them against prior baselines to catch unintended rendering changes. It is tool-aware: rendering uses the bundled, free Playwright extension; comparison uses Claude's vision by default (and an exact pixel-diff CLI for precise deltas when one is installed). Without a browser it can't capture pixels — so it delivers a structured manual visual-QA checklist and the single step to enable the free renderer, rather than failing.

Use cases: pre/post refactor, pre/post deploy (staging vs prod), component/token updates, and cross-browser drift.

Triggers

• "visual qa" / "visual regression"
• "screenshot diff" / "pixel diff"
• "did anything change visually"
• "compare against baseline"
• "before and after screenshots"

Inputs

• Target URL(s) or local build paths
• Viewports (default: 375, 768, 1280, 1920)
• Browser(s) (default: chromium; optional firefox, webkit)
• Baseline mode: capture | diff | both
• Threshold for "changed" (pixel-diff % when an exact differ is present; otherwise a qualitative materiality call)

Steps

1. Detect the renderer. Confirm the Playwright MCP is connected, then run the capability probe to see if an exact differ (odiff/pixelmatch via npx) is available:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workflow/capability_probe.py"    # use `py` on Windows if python3 is absent; in PowerShell the variable is $env:CLAUDE_PLUGIN_ROOT

2. Capture. For each (URL, viewport, browser): load, wait for network idle + fonts + animations settled, then full-page screenshot.
3. Baseline vs diff.
   • capture: save baselines to visual-qa/baselines/ in the user's workspace.
   • diff: compare each shot to its baseline. Exact differ present → pixel-delta %
     • highlighted diff image. Otherwise → Claude-vision comparison reporting the specific regions/elements that changed and whether each looks intentional.
4. Aggregate which pages/viewports drifted and by how much (or how materially). Grade each change against the four axes (hierarchy, rhythm, contrast, restraint) and the severity ladder in references/design-visual-qa/visual-qa-rubric.md — a large delta can be a deliberate improvement, while a tiny delta that drops text below AA or hides a focus ring is a critical regression.
5. Report which tier ran (per the plugin's capability-tier cascade, references/CAPABILITY-TIERS.md: Tier 1/2 = Playwright render + exact-differ-or- Claude-vision compare; Tier 4 = no browser, guided checklist) and, if no browser was available, the one step to enable it (connect the bundled Playwright extension).

Outputs

Filed to: the user's project workspace. A change is judged by the rubric in references/design-visual-qa/visual-qa-rubric.md, not by pixel delta alone.

Error Handling

Dependencies

• Playwright extension (extensions/playwright/) — free, bundled; required to capture. Without it, the skill runs its Tier-4 guided path.
• Optional: an exact pixel-diff CLI (odiff/pixelmatch via npx) for precise deltas; Claude-vision comparison is the default and needs nothing extra.
• scripts/workflow/capability_probe.py

Notes

Pairs with seo-drift for a complete "did anything change" picture — drift catches SEO regressions, visual-qa catches rendering regressions. Comparison defaults to Claude's vision so no pixel-diff dependency is required for a useful result.