From voice-sweep
This skill should be used when checking a deployed or local web app for layout regressions, horizontal overflow, element clipping, or breakage across viewports. Trigger phrases include "visual QA", "check for overflow", "layout check", "responsive bug", "test mobile layout", "playwright overflow". Generates a Playwright spec that crawls a sitemap and checks every route across mobile (375px), tablet (768px), and desktop (1440px) viewports. Reports horizontal overflow, off-screen fixed elements, and zero-height containers. Deterministic, no LLM, requires Playwright as a peer dep.
How this skill is triggered — by the user, by Claude, or both
Slash command
/voice-sweep:visual-qaThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generates a Playwright spec that crawls a sitemap and checks every
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.
Trigger this skill when:
Do NOT use for:
design-audit skill instead)voice-sweep skill instead)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)| 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) |
Discovers routes in this order:
sitemap.xml at ${BASE_URL}/sitemap.xml (default http://localhost:3000)src/app/**/page.tsx and infer routesroutes array in .visual-qa.config.json| Tier | Viewport | Use |
|---|---|---|
| Mobile | 375 × 667 | iPhone-class baseline |
| Tablet | 768 × 1024 | iPad-class baseline |
| Desktop | 1440 × 900 | Laptop baseline |
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"
}
- 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.
This skill works in:
npx @operator-skills/visual-qa init/plugin install visual-qa; Claude generates the spec on demand and runs itnpx @operator-skills/visual-qa mcp into any MCP-aware runtimedesign-audit — static-analysis design-system checksvoice-sweep — brand-voice + tone violationsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub cmj-hub/operator-skills --plugin design-audit