CommunityCoding & Developmentgithub.com

visual-qa

Mandatory screenshot-driven visual QA loop for any significant UI change — run the site, capture every breakpoint with Playwright, judge each screenshot, fix, repeat. Use after building or restyling any page or section, and before reporting UI work as finished. For design judgement use premium-frontend; for conversion audit use conversion-optimization.

What is visual-qa?

visual-qa is a Claude Code agent skill that mandatory screenshot-driven visual QA loop for any significant UI change — run the site, capture every breakpoint with Playwright, judge each screenshot, fix, repeat. Use after building or restyling any page or section, and before reporting UI work as finished. For design judgement use premium-frontend; for conversion audit use conversion-optimization.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/artem2167/website-factory/tree/HEAD/.claude/skills/visual-qa

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does visual-qa do?

Valid JSX is not evidence of good design. Never report UI work as finished without having looked at it.

Core

Run the website locally.

Inspect:
375px
390px
768px
1440px
1920px

Capture screenshots.

Review each screenshot for:

- broken layout
- weak hierarchy
- excessive whitespace
- insufficient whitespace
- ugly line wrapping
- poor image crop
- inconsistent margins
- oversized typography
- tiny typography
- weak CTA prominence
- alignment problems
- generic AI-design patterns

Fix detected issues.

Repeat until no major visual issues remain.

How to run it

Start the dev server, then:

QA_ROUTES=/,/services,/doctors,/contact node scripts/qa-screenshots.mjs

Output lands in qa/<route>/<width>.png, full-page, one file per breakpoint. The script also reports horizontal overflow and console errors per breakpoint — both are automatic failures.

Breakpoints captured: 375×812, 390×844, 430×932, 768×1024, 1440×900, 1920×1080.

First-time setup:

npm i -D playwright && npx playwright install chromium

For interactive poking rather than a full sweep, the in-editor browser tools are faster: open the page, resize, read the accessibility tree, check the console.

Reading a screenshot

Go breakpoint by breakpoint. For each one answer:

  1. Does anything overflow horizontally?
  2. Is there one obvious focal point, or does the eye wander?
  3. Do headings wrap into an ugly orphan or a one-word last line?
  4. Are the margins between sections consistent where they should be, and deliberately different where they should be?
  5. Are images cropped through a face, a plate or a bed?
  6. Is the primary CTA the most prominent element in its screenful?
  7. On mobile: is the sticky CTA visible, thumb-reachable, and not covering content?
  8. Does anything look like a default AI page — gradient, icon-card grid, pill badges, blurred blobs?

Mobile-specific checks

Local-business visitors arrive from Instagram, Google Maps, TikTok, ads and messenger links. Mobile is the primary surface, not an afterthought.

  • no horizontal scroll at 375;
  • hero text not oversized — it must not eat the whole first screen;
  • tap targets large enough, nothing tiny;
  • navigation reachable and closable;
  • images cropped for portrait, not squeezed from a landscape desktop crop;
  • sticky CTA present and refined.

Loop discipline

  • Fix the findings, then re-capture. Do not fix blind.
  • Stop when a full sweep produces no major finding, not when the list gets boring.
  • If the same finding returns after a fix, the problem is in the block, not in the page — fix it in the block library.
  • Report honestly: if a breakpoint still has an open issue, say so.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Related Skills