visual-qa

Visual QA

Generates a Playwright spec that crawls a sitemap and checks every public route across three viewports for layout breakage. Catches the regressions that static-analysis design audits can't see — horizontal overflow on mobile, fixed elements that clip on tablet, zero-height containers from a flexbox glitch.

When to use

Trigger this skill when:

• A user asks to "run visual QA", "check for overflow", "test mobile layout", "find layout breakage"
• After any UI / CSS / Tailwind change before opening a PR
• As a CI gate that runs against the preview deploy URL
• When QA flags a responsive bug and the source isn't obvious

Do NOT use for:

• Design-system rule violations (use design-audit skill instead)
• Copy / brand tone issues (use voice-sweep skill instead)
• Performance / Core Web Vitals (use a Lighthouse skill — not in this monorepo)

How to invoke

The skill ships a CLI that GENERATES Playwright spec files into your repo. It does NOT shell out to Playwright; you (or your CI) invoke Playwright directly. This keeps the package zero-dependency.

# One-time setup: install Playwright + generate the spec
npm i -D @playwright/test
npx @operator-skills/visual-qa init

# Run the spec
npx playwright test e2e/operator-visual-qa.spec.ts

The init subcommand creates:

• e2e/operator-visual-qa.spec.ts — the test spec (won't overwrite if exists)
• playwright.config.ts — Playwright config (only if missing)
• .visual-qa.config.json — route discovery + viewport config (only if missing)

Subcommands

Command	What it does
init	Generate spec + config files in the consuming repo
routes	Print the discovered route list (sitemap.xml or glob)
report <path>	Format a Playwright JSON results file as a summary
mcp	Run as an MCP server (stdio)

Default route discovery

Discovers routes in this order:

1. sitemap.xml at ${BASE_URL}/sitemap.xml (default http://localhost:3000)
2. Glob fallback — if no sitemap, scan src/app/**/page.tsx and infer routes
3. Manual override — routes array in .visual-qa.config.json

Default viewports

Tier	Viewport	Use
Mobile	375 × 667	iPhone-class baseline
Tablet	768 × 1024	iPad-class baseline
Desktop	1440 × 900	Laptop baseline

Default checks

Each route × viewport combination runs:

Check	Catches
horizontalOverflow	document.body.scrollWidth > window.innerWidth
clippedFixedElements	Sticky / fixed elements positioned beyond viewport edges
zeroHeightContainers	Visible containers (hero, main, section) with clientHeight === 0
consoleErrors	Browser console errors during page load

Override / add checks in .visual-qa.config.json:

{
  "baseUrl": "https://staging.jaymountconsulting.com",
  "viewports": [
    { "name": "mobile",  "width": 375, "height": 667 },
    { "name": "tablet",  "width": 768, "height": 1024 },
    { "name": "desktop", "width": 1440, "height": 900 }
  ],
  "routes": ["/", "/operator-pass", "/build", "/prototypes"],
  "checks": {
    "horizontalOverflow": "error",
    "clippedFixedElements": "error",
    "zeroHeightContainers": "warn",
    "consoleErrors": "off"
  },
  "remoteConfigUrl": "https://example.com/visual-qa-baseline.json"
}

Best-practice usage in CI

- name: Generate visual QA spec
  run: npx @operator-skills/visual-qa init
- name: Install Playwright browsers
  run: npx playwright install --with-deps chromium
- name: Run visual QA
  env:
    PLAYWRIGHT_BASE_URL: ${{ env.PREVIEW_URL }}
  run: npx playwright test e2e/operator-visual-qa.spec.ts --reporter=json > visual-qa-results.json
- name: Summarize
  run: npx @operator-skills/visual-qa report visual-qa-results.json

report exits 1 if any check fails at error severity, so CI fails the build appropriately.

Cross-runtime

This skill works in:

• Plain Node CLI — npx @operator-skills/visual-qa init
• Claude Code (Agent Skills) — install via /plugin install visual-qa; Claude generates the spec on demand and runs it
• MCP — wire npx @operator-skills/visual-qa mcp into any MCP-aware runtime
• Cursor / Gemini / Codex — planned Wave 2

Related skills

• design-audit — static-analysis design-system checks
• voice-sweep — brand-voice + tone violations