madappgang/claude-code/browser-debugging

# Check OpenRouter API key
[[ -n "${OPENROUTER_API_KEY}" ]] && echo "OpenRouter configured" || echo "Not configured"
 
# Install claudish
npm install -g claudish

Design Fidelity Validation → qwen/qwen3-vl-32b-instruct (best OCR & spatial)
Quick Smoke Tests → google/gemini-2.5-flash (fast & cheap)
Complex Layout Analysis → openai/gpt-4o (best reasoning)
High Volume Testing → google/gemini-2.5-flash-lite (ultrafast)
Budget Conscious → openrouter/polaris-alpha (free)

## After Implementing UI Feature
 
1.**Save file changes** (Edit tool)
 
2.**Capture implementation screenshot**:
   \`\`\`
   mcp__claude-in-chrome__navigate(url: "http://localhost:5173/your-route")
   # Wait for page load
   mcp__claude-in-chrome__computer(action: "screenshot")
   \`\`\`
 
3.**Analyze with embedded Claude** (always available):
   -Describe what you see in the screenshot
   -Check for obvious layout issues
   -Verify expected elements are present
 
4.**Optional: Enhanced analysis with vision model**:
   \`\`\`bash
   # Use Qwen VL for detailed visual analysis
   npx claudish --model qwen/qwen3-vl-32b-instruct --stdin --quiet <<EOF
   Analyze this UI screenshot and identify any visual issues:
 
   IMAGE: [screenshot from previous step]
 
   Check for:
   -Layout alignment issues
   -Spacing inconsistencies
   -Typography problems (font sizes, weights)
   -Color contrast issues
   -Missing or broken elements
   -Responsive design problems
 
   Provide specific, actionable feedback.
   EOF
   \`\`\`
 
5.**Check console for errors**:
   \`\`\`
   mcp__claude-in-chrome__read_console_messages()
   # Filter for errors in response
   \`\`\`
 
6.**Check network for failures**:
   \`\`\`
   mcp__claude-in-chrome__read_network_requests()
   # Look for failed requests (status >= 400)
   \`\`\`
 
7.**Report results to orchestrator**

## Quick Self-Validation Checklist
 
□ 1. Screenshot shows expected UI elements
□ 2. No console errors (check: mcp__claude-in-chrome__read_console_messages)
□ 3. No network failures (check: mcp__claude-in-chrome__read_network_requests)
□ 4. Interactive elements respond correctly
□ 5. Visual styling matches expectations

## Design Fidelity Check
 
### Step 1: Capture Implementation
\`\`\`
mcp__claude-in-chrome__navigate(url: "http://localhost:5173/component")
mcp__claude-in-chrome__resize_window(width: 1440, height: 900)
mcp__claude-in-chrome__computer(action: "screenshot")
\`\`\`
 
### Step 2: Visual Analysis with Vision Model
 
\`\`\`bash
npx claudish --model qwen/qwen3-vl-32b-instruct --stdin --quiet <<EOF
Compare these two UI screenshots and identify design fidelity issues:
 
DESIGN REFERENCE: /tmp/design-reference.png
IMPLEMENTATION: [screenshot from step 1]
 
Analyze and report differences in:
 
## Colors & Theming
-Background colors (exact hex values)
-Text colors (headings, body, muted)
-Border and divider colors
-Button/interactive element colors
 
## Typography
-Font families
-Font sizes (px values)
-Font weights (regular, medium, bold)
-Line heights
-Letter spacing
 
## Spacing & Layout
-Padding (top, right, bottom, left)
-Margins between elements
-Gap spacing in flex/grid
-Container max-widths
-Alignment (center, left, right)
 
## Visual Elements
-Border radius values
-Box shadows (blur, spread, color)
-Icon sizes and colors
-Image aspect ratios
 
## Component Structure
-Missing elements
-Extra elements
-Wrong element order
 
For EACH difference found, provide:
1.Category (colors/typography/spacing/visual/structure)
2.Severity (CRITICAL/MEDIUM/LOW)
3.Expected value (from design)
4.Actual value (from implementation)
5.Specific Tailwind CSS fix
 
Output as structured markdown.
EOF
\`\`\`
 
### Step 3: Generate Fix Recommendations
 
Parse vision model output and create actionable fixes for ui-developer agent.

## Interactive Testing Flow
 
### Step 1: Get Page Structure
\`\`\`
mcp__claude-in-chrome__read_page()
# Returns DOM structure with element references
\`\`\`
 
### Step 2: Test Each Interactive Element
 
**Button Test**:
\`\`\`
# Before
mcp__claude-in-chrome__computer(action: "screenshot")
 
# Find and click button (natural language)
mcp__claude-in-chrome__find(description: "submit button")
mcp__claude-in-chrome__computer(action: "left_click", coordinate: [x, y])
 
# OR click by reference
mcp__claude-in-chrome__computer(action: "click", ref: "button[type=submit]")
 
# After (wait for response)
# Wait a moment for response
mcp__claude-in-chrome__computer(action: "screenshot")
 
# Check results
mcp__claude-in-chrome__read_console_messages()
mcp__claude-in-chrome__read_network_requests()
\`\`\`
 
**Form Test**:
\`\`\`
# Fill form fields
mcp__claude-in-chrome__form_input(
  selector: "#email",
  value: "test@example.com"
)
mcp__claude-in-chrome__form_input(
  selector: "#password",
  value: "SecurePass123!"
)
 
# Submit (click button)
mcp__claude-in-chrome__find(description: "submit button")
mcp__claude-in-chrome__computer(action: "left_click", coordinate: [x, y])
 
# Verify success
mcp__claude-in-chrome__read_page()
# Check for success indicators
\`\`\`
 
**Hover State Test**:
\`\`\`
mcp__claude-in-chrome__computer(action: "screenshot")
mcp__claude-in-chrome__find(description: "primary button")
mcp__claude-in-chrome__computer(action: "hover", coordinate: [x, y])
mcp__claude-in-chrome__computer(action: "screenshot")
# Compare screenshots for hover state changes
\`\`\`
 
### Step 3: Analyze Interaction Results
 
Use vision model to compare before/after screenshots:
\`\`\`bash
npx claudish --model google/gemini-2.5-flash --stdin --quiet <<EOF
Compare these before/after screenshots and verify the interaction worked:
 
BEFORE: [screenshot before interaction]
AFTER: [screenshot after interaction]
 
Expected behavior: [describe what should happen]
 
Verify:
1.Did the expected UI change occur?
2.Are there any error states visible?
3.Did loading states appear/disappear correctly?
4.Is the final state correct?
 
Report: PASS/FAIL with specific observations.
EOF
\`\`\`

## Responsive Testing
 
### Breakpoints to Test
 
| Breakpoint | Width | Description |
|------------|-------|-------------|
| Mobile | 375px | iPhone SE |
| Mobile L | 428px | iPhone 14 Pro Max |
| Tablet | 768px | iPad |
| Desktop | 1280px | Laptop |
| Desktop L | 1920px | Full HD |
 
### Automated Responsive Check
 
\`\`\`bash
#!/bin/bash
# Test all breakpoints
 
BREAKPOINTS=(375 428 768 1280 1920)
URL="http://localhost:5173/your-route"
 
for width in "\${BREAKPOINTS[@]}"; do
  echo "Testing \${width}px..."
 
  # Navigate (once)
  mcp__claude-in-chrome__navigate(url: "$URL")
 
  # Resize and screenshot
  mcp__claude-in-chrome__resize_window(width: $width, height: 900)
  mcp__claude-in-chrome__computer(action: "screenshot")
  # Save/analyze screenshot
done
\`\`\`
 
### Visual Analysis for Responsive Issues
 
\`\`\`bash
npx claudish --model qwen/qwen3-vl-32b-instruct --stdin --quiet <<EOF
Analyze these responsive screenshots for layout issues:
 
MOBILE (375px): [screenshot 1]
TABLET (768px): [screenshot 2]
DESKTOP (1280px): [screenshot 3]
 
Check for:
1.Text overflow or truncation
2.Elements overlapping
3.Improper stacking on mobile
4.Touch targets too small (<44px)
5.Hidden content that shouldn't be hidden
6.Horizontal scroll issues
7.Image scaling problems
 
Report issues by breakpoint with specific CSS fixes.
EOF
\`\`\`

## Accessibility Check
 
### Automated A11y Testing
 
\`\`\`
# Get full page content for accessibility tree analysis
mcp__claude-in-chrome__read_page()
 
# Get all text content
mcp__claude-in-chrome__get_page_text()
 
# Check for common issues:
# - Missing alt text (look for img without alt in read_page)
# - Missing ARIA labels
# - Incorrect heading hierarchy
# - Missing form labels
\`\`\`
 
### Visual Contrast Analysis
 
\`\`\`bash
npx claudish --model qwen/qwen3-vl-32b-instruct --stdin --quiet <<EOF
Analyze this screenshot for accessibility issues:
 
IMAGE: [screenshot]
 
Check WCAG 2.1 AA compliance:
 
1.**Color Contrast**
   -Text contrast ratio (need 4.5:1 for normal, 3:1 for large)
   -Interactive element contrast
   -Focus indicator visibility
 
2.**Visual Cues**
   -Do links have underlines or other visual differentiation?
   -Are error states clearly visible?
   -Are required fields indicated?