Test Improve

--- name: test-improve description: >- Iterative visual design review and improvement tool using Playwright screenshots. This skill should be used when reviewing a page's visual quality, auditing against design guidelines, making improvements, and re-checking until the design meets quality standards. Works with any web project — auto-detects brand rules from CLAUDE.md and project context. --- # Test-Improve — Visual Design Review & Auto-Fix Loop ## When to Use - `/test-improve [url]` — explicit invocation - "review and improve the design" - "audit the page design" - "check design quality and fix issues" - "test and fix [page-name]" - After building or modifying a page, before shipping ## Prerequisites - Playwright installed (`npx playwright install chromium`) - Dev server running (for local URLs) --- ## Phase 0: Detect Project Context (always runs first) Before auditing, gather project-specific design rules: 1. **Read CLAUDE.md** — extract brand colors, fonts, icon library, design preferences 2. **Read tailwind.config** (if exists) — extract theme colors, fonts, spacing 3. **Read layout/globals** — detect font imports, CSS variables, base styles 4. **Build a Brand Profile** from what you find: ``` BRAND PROFILE (auto-detected): ├─ Heading Font: [detected or "not specified"] ├─ Body Font: [detected or "not specified"] ├─ Primary Color: [hex] ├─ Accent Color(s): [hex values] ├─ CTA Color: [hex] ├─ Icon Library: [lucide/heroicons/etc.] ├─ Design Rules: [from CLAUDE.md — e.g., "no gradients", "no emojis"] └─ Component Library: [shadcn/mui/chakra/custom] ``` If no brand rules are found, use the generic defaults in the checklist. --- ## Workflow: 4 Phases, Max 3 Iterations ### Phase 1: Capture & Identify (always runs) 1. **Determine target URL** — user-provided or auto-detect from recent work - If no URL given, check recently modified files for page routes - Support both `localhost` and production URLs 2. **Identify page source files** — find all files to audit: - Page entry point (e.g., `page.tsx`, `index.tsx`, `+page.svelte`) - Client component (e.g., `content.tsx`, `client.tsx`) - Section/component directory 3. **Run multi-viewport screenshots** using Playwright: - Check for project screenshot script first (e.g., `scripts/screenshot-viewports.ts`) - Fallback: use Playwright CLI directly for 3 viewports: ```bash # Desktop (1440px) npx playwright screenshot --viewport-size="1440,900" --full-page <url> /tmp/test-improve-desktop.png # Tablet (768px) npx playwright screenshot --viewport-size="768,1024" --full-page <url> /tmp/test-improve-tablet.png # Mobile (393px) npx playwright screenshot --viewport-size="393,852" --full-page <url> /tmp/test-improve-mobile.png ``` 4. **Read all screenshots visually** — use the Read tool on each PNG file 5. **Read all component source files** — understand current implementation ### Phase 2: Audit (runs each iteration) Load `references/design-checklist.md` and evaluate the page against every applicable check. **Adapt checks to the Brand Profile** detected in Phase 0 — substitute project-specific fonts, colors, and rules for the generic defaults. #### Audit Categories & Weights | Category | Weight | Focus | |----------|--------|-------| | **Brand Compliance** | 20% | Fonts, colors, design rules from CLAUDE.md, icon library, logo | | **Anti-Slop** | 20% | AI cliches, equal-width grids, generic shadows, symmetric padding | | **Motion Quality** | 15% | Tap feedback, spring transitions, stagger timing, scroll reveals | | **Layout & Spacing** | 15% | Section padding rhythm, responsive breakpoints, whitespace | | **Conversion** | 15% | CTA above fold, value prop, social proof, objection handling | | **Visual Quality** | 15% | Tinted shadows, card hover lifts, border radius, text hierarchy | #### Audit Output Format For each issue found, record: ``` [SEVERITY] Category — Issue Title File: path/to/component.tsx:42 What: Description of what's wrong Fix: Specific code change to resolve ``` Severity levels: - **Critical** — Brand violation, broken layout, missing CTA, accessibility failure - **Important** — Anti-slop pattern, missing motion, weak conversion element - **Minor** — Spacing inconsistency, optimization opportunity, polish detail ### Phase 3: Fix (runs each iteration) 1. **Present findings to user** — grouped by severity: ``` ══════════════════════════════════════ AUDIT FINDINGS — Iteration N ══════════════════════════════════════ CRITICAL (X issues) ├─ [issue description + file] └─ [issue description + file] IMPORTANT (X issues) ├─ [issue description + file] └─ [issue description + file] MINOR (X issues) ├─ [issue description + file] └─ [issue description + file] ``` 2. **Apply fixes** — make all approved changes to source files 3. **Re-capture screenshots** using the same method from Phase 1 4. **Read new screenshots** to visually verify fixes resolved the issues ### Phase 4: Re-audit & Loop (max 3 iterations) 1. Re-run Phase 2 checklist on updated code + new screenshots 2. If new Critical or Important issues found → back to Phase 3 3. If clean (no Critical or Important remaining) → Phase 5 4. If max iterations (3) reached → Phase 5 with remaining issues noted ### Phase 5: Final Report ``` ═══════════════════════════════════════════ TEST-IMPROVE REPORT: /page-name ═══════════════════════════════════════════ Iterations: N Issues Found: X Issues Fixed: Y Remaining: Z (severity breakdown) CHANGES MADE: ├─ brand-compliance: N fixes ├─ anti-slop: N fixes ├─ motion-quality: N fixes ├─ layout-spacing: N fixes ├─ conversion: N fixes └─ visual-quality: N fixes FILES MODIFIED: ├─ path/to/component-a.tsx ├─ path/to/component-b.tsx └─ path/to/page.tsx SCREENSHOTS: [screenshot directory] ═══════════════════════════════════════════ ``` --- ## Reference Files | File | Load When | |------|-----------| | `references/design-checklist.md` | Every audit run — the master checklist | Load the checklist at the start of Phase 2. It contains all checks organized by category with pass/fail criteria and specific fix instructions. **Substitute project brand values** from the Brand Profile for any generic defaults. --- ## Integration with Other Skills If these skills are available in the project, test-improve draws criteria from them: | Skill | What test-improve borrows | |-------|--------------------------| | `taste` | Anti-slop patterns, brand lock rules, tinted shadows, spring physics | | `design-motion-principles` | whileTap checks, stagger timing, scroll reveal consistency | | `landing-page-auditor` | Above-fold checks, CTA placement, social proof visibility | | `frontend-design` | Typography hierarchy, distinctive layout, background variety | If deeper analysis is needed in any category, invoke the specialized skill directly (if available). --- ## Constraints - Works with any local or production URL - Screenshots use Playwright (not Chrome MCP tools) - Max 3 iterations prevents infinite loops on subjective preferences - Phase 3 fixes require user approval before applying - Don't audit files you haven't read — always read source before reporting issues - Don't report issues below 80% confidence - Adapt all brand checks to the detected project context — never assume a specific brand