visual-dev

name	visual-dev
description	Visual development with Patchright screenshots. Use when building, fixing, reviewing, or creating new UI pages and dashboard components. Use when the user wants to build a dashboard, create a new page, verify UI works correctly, or iterate on visual design. Takes screenshots, analyzes layout, iterates until correct.

Visual Development Loop

This skill is a mandatory validation gate, not an optional polish step. Every dashboard page must be screenshotted and judged against the 7 criteria before the iteration is complete. See dashboard-builder/SKILL.md "Required states" table for the full list of visual states to implement and screenshot.

Core principle: Build, screenshot, judge, fix, re-screenshot, repeat until zero problems. The screenshot loop IS the development loop.

Prompt compliance gate: Before committing: list every prompt requirement, state evidence for each (curl output, screenshot, Patchright click). Any requirement without evidence = not done. Loop until all have evidence.

Prerequisites

1. Discover the running server

lsof -iTCP -sTCP:LISTEN -P 2>/dev/null | grep -E ':(3000|3001|3002|3003|4000|5173|8080)\s'

CRITICAL: curl every candidate port and verify the HTML title matches this project before setting BASE_URL.

2. Discover auth credentials

Search for login files, then check: existing e2e tests, seed files, .env.test, CLAUDE.md. Also extract the post-login redirect URL for waitForURL.

3. Create screenshot directory

mkdir -p /tmp/interceptor-dev-screenshots

Phase Overview

Phase	Purpose	Details
1. Understand	Read source code, build mental model before screenshotting	reference/phase-1-understand.md
2. Enumerate	List every visual state before taking any screenshots	reference/phase-2-enumerate.md
3. Verify	Build + screenshot + judge loop with 7 criteria	reference/phase-3-verify.md
4. Interactions	Test button clicks, form submits, state transitions	reference/phase-4-interactions.md
5. Viewports	Multi-viewport sweep (mobile, tablet, desktop, wide)	reference/phase-5-viewports.md

Cross-cutting references:

• reference/ui-patterns.md — shadcn components, transitions, dark mode
• reference/common-visual-bugs.md — Common bugs checklist
• reference/troubleshooting.md — Getting unstuck

Critical Gate

The loop for a given state ends when you find zero issues across all 7 judgment criteria (3-second test, data accuracy, visual hierarchy, interaction affordance, error communication, empty states, density balance). The full page is done when every enumerated state passes.

Cleanup

Run only at the very end, after all states pass. Delete the entire directory:

rm -rf /tmp/interceptor-dev-screenshots/

Do this before committing or switching branches. Never leave Patchright scripts in the repo.