browser-debugger

# Browser Debugger This Skill provides comprehensive browser-based UI testing, visual analysis, and debugging capabilities using Chrome DevTools MCP server and optional external vision models via Claudish. ## When to Use This Skill Claude and agents (developer, reviewer, tester, ui-developer) should invoke this Skill when: - **Validating Own Work**: After implementing UI features, agents should verify their work in a real browser - **Design Fidelity Checks**: Comparing implementation screenshots against design references - **Visual Regression Testing**: Detecting layout shifts, styling issues, or visual bugs - **Console Error Investigation**: User reports console errors or warnings - **Form/Interaction Testing**: Verifying user interactions work correctly - **Pre-Commit Verification**: Before committing or deploying code - **Bug Reproduction**: User describes UI bugs that need investigation ## Prerequisites ### Required: Chrome DevTools MCP This skill requires Chrome DevTools MCP. Check availability and install if needed: ```bash # Check if available mcp__chrome-devtools__list_pages 2>/dev/null && echo "Available" || echo "Not available" # Install via claudeup (recommended) npm install -g claudeup@latest claudeup mcp add chrome-devtools ``` ### Optional: External Vision Models (via OpenRouter) For advanced visual analysis, use external vision-language models via Claudish: ```bash # Check OpenRouter API key [[ -n "${OPENROUTER_API_KEY}" ]] && echo "OpenRouter configured" || echo "Not configured" # Install claudish npm install -g claudish ``` --- ## Visual Analysis Models (Recommended) For best visual analysis of UI screenshots, use these models via Claudish: ### Tier 1: Best Quality (Recommended for Design Validation) | Model | Strengths | Cost | Best For | |-------|-----------|------|----------| | **qwen/qwen3-vl-32b-instruct** | Best OCR, spatial reasoning, GUI automation, 32+ languages | ~$0.06/1M input | Design fidelity, OCR, element detection | | **google/gemini-2.5-flash** | Fast, excellent price/performance, 1M context | ~$0.05/1M input | Real-time validation, large pages | | **openai/gpt-4o** | Most fluid multimodal, strong all-around | ~$0.15/1M input | Complex visual reasoning | ### Tier 2: Fast & Affordable | Model | Strengths | Cost | Best For | |-------|-----------|------|----------| | **qwen/qwen3-vl-30b-a3b-instruct** | Good balance, MoE architecture | ~$0.04/1M input | Quick checks, multiple iterations | | **google/gemini-2.5-flash-lite** | Ultrafast, very cheap | ~$0.01/1M input | High-volume testing | ### Tier 3: Free Options | Model | Notes | |-------|-------| | **openrouter/polaris-alpha** | FREE, good for testing workflows | ### Model Selection Guide ``` 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) ``` --- ## Visual Analysis Model Selection (Interactive) **Before the first screenshot analysis in a session, ask the user which model to use.** ### Step 1: Check for Saved Preference First, check if user has a saved model preference: ```bash # Check for saved preference in project settings SAVED_MODEL=$(cat .claude/settings.json 2>/dev/null | jq -r '.pluginSettings.frontend.visualAnalysisModel // empty') # Or check session-specific preference if [[ -f "ai-docs/sessions/${SESSION_ID}/session-meta.json" ]]; then SESSION_MODEL=$(jq -r '.visualAnalysisModel // empty' "ai-docs/sessions/${SESSION_ID}/session-meta.json") fi ``` ### Step 2: If No Saved Preference, Ask User Use **AskUserQuestion** with these options: ```markdown ## Visual Analysis Model Selection For screenshot analysis and design validation, which AI vision model would you like to use? **Your choice will be remembered for this session.** ``` **AskUserQuestion options:** | Option | Label | Description | |--------|-------|-------------| | 1 | `qwen/qwen3-vl-32b-instruct` (Recommended) | Best for design fidelity - excellent OCR, spatial reasoning, detailed analysis. ~$0.06/1M tokens | | 2 | `google/gemini-2.5-flash` | Fast & affordable - great balance of speed and quality. ~$0.05/1M tokens | | 3 | `openai/gpt-4o` | Most capable - best for complex visual reasoning. ~$0.15/1M tokens | | 4 | `openrouter/polaris-alpha` (Free) | No cost - good for testing, basic analysis | | 5 | Skip visual analysis | Use embedded Claude only (no external models) | **Recommended based on task type:** - Design validation → Option 1 (Qwen VL) - Quick iterations → Option 2 (Gemini Flash) - Complex layouts → Option 3 (GPT-4o) - Budget-conscious → Option 4 (Free) ### Step 3: Save User's Choice After user selects, save their preference: **Option A: Save to Session (temporary)** ```bash # Update session metadata jq --arg model "$SELECTED_MODEL" '.visualAnalysisModel = $model' \ "ai-docs/sessions/${SESSION_ID}/session-meta.json" > tmp.json && \ mv tmp.json "ai-docs/sessions/${SESSION_ID}/session-meta.json" ``` **Option B: Save to Project Settings (persistent)** ```bash # Update project settings for future sessions jq --arg model "$SELECTED_MODEL" \ '.pluginSettings.frontend.visualAnalysisModel = $model' \ .claude/settings.json > tmp.json && mv tmp.json .claude/settings.json ``` ### Step 4: Use Selected Model Store the selected model in a variable and use it for all subsequent visual analysis: ```bash # VISUAL_MODEL is now set to user's choice # Use it in all claudish calls: npx claudish --model "$VISUAL_MODEL" --stdin --quiet <<EOF [visual analysis prompt] EOF ``` ### Model Selection Flow (Decision Tree) ``` ┌─────────────────────────────────────────────────────┐ │ Screenshot Analysis Requested │ └─────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ Check: Is VISUAL_MODEL already set this session? │ └─────────────────────────────────────────────────────┘ │ ┌───────────┴───────────┐ │ YES │ NO ▼ ▼ ┌───────────────────┐ ┌─────────────────────────────┐ │ Use saved model │ │ Check project settings │ │ Skip to analysis │ │ .claude/settings.json │ └───────────────────┘ └─────────────────────────────┘ │ ┌───────────┴───────────┐ │ FOUND │ NOT FOUND ▼ ▼ ┌───────────────────┐ ┌─────────────────────────┐ │ Use saved model │ │ Check OpenRouter API │ │ Remember for │ │ key availability │ │ session │ └─────────────────────────┘ └───────────────────┘ │ ┌───────────┴───────────┐ │ AVAILABLE │ NOT AVAILABLE ▼ ▼ ┌───────────────────┐ ┌─────────────────────┐ │ AskUserQuestion: │ │ Inform user: │ │ Select vision │ │ "Using embedded │ │ model │ │ Claude only" │ └───────────────────┘ └─────────────────────┘ │ ▼ ┌───────────────────────────────────┐ │ Save choice to session │ │ Ask: "Save as default?" (optional)│ └───────────────────────────────────┘ │ ▼ ┌───────────────────────────────────┐ │ Proceed with visual analysis │ └───────────────────────────────────┘ ``` ### Example: AskUserQuestion Implementation When prompting the user, use this format: ``` Use AskUserQuestion tool with: question: "Which vision model should I use for screenshot analysis?" header: "Vision Model" multiSelect: false options: - label: "Qwen VL 32B (Recommended)" description: "Best for design fidelity - excellent OCR & spatial reasoning. ~$0.06/1M tokens" - label: "Gemini 2.5 Flash" description: "Fast & affordable - great for quick iterations. ~$0.05/1M tokens" - label: "GPT-4o" description: "Most capable - best for complex visual reasoning. ~$0.15/1M tokens" - label: "Free (Polaris Alpha)" description: "No cost - good for testing and basic analysis" ``` ### Mapping User Choice to Model ID ```bash case "$USER_CHOICE" in "Qwen VL 32B (Recommended)") VISUAL_MODEL="qwen/qwen3-vl-32b-instruct" ;; "Gemini 2.5 Flash") VISUAL_MODEL="google/gemini-2.5-flash" ;; "GPT-4o") VISUAL_MODEL="openai/gpt-4o" ;; "Free (Polaris Alpha)") VISUAL_MODEL="openrouter/polaris-alpha" ;; *) VISUAL_MODEL="" # Skip external analysis ;; esac ``` ### Remember for Future Sessions After first selection, optionally ask: ``` Use AskUserQuestion tool with: question: "Save this as your default vision model for future sessions?" header: "Save Default" multiSelect: false options: - label: "Yes, save as default" description: "Use this model automatically in future sessions" - label: "No, ask each time" description: "Let me choose each session" ``` If user chooses "Yes", update `.claude/settings.json`: ```json { "pluginSettings": { "frontend": { "visualAnalysisModel": "qwen/qwen3-vl-32b-instruct" } } } ``` --- ## Recipe 1: Agent Self-Validation (After Implementation) **Use Case**: Developer/UI-Developer agent validates their own work after implementing a feature. ### Pattern: Implement → Screenshot → Analyze → Report ```markdown ## After Implementing UI Feature 1. **Save file changes** (Edit tool) 2. **Capture implementation screenshot**: ``` mcp__chrome-devtools__navigate_page(url: "http://localhost:5173/your-route") # Wait for page load mcp__chrome-devtools__take_screenshot(filePath: "/tmp/implementation.png") ``` 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: /tmp/implementation.png 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__chrome-devtools__list_console_messages(types: ["error", "warn"]) ``` 6. **Report results to orchestrator** ``` ### Quick Self-Check (5-Point Validation) Agents should perform this quick check after any UI implementation: ```markdown ## Quick Self-Validation Checklist □ 1. Screenshot shows expected UI elements □ 2. No console errors (check: mcp__chrome-devtools__list_console_messages) □ 3. No network failures (check: mcp__chrome-devtools__list_network_requests) □ 4. Interactive elements respond correctly □ 5. Visual styling matches expectations ``` --- ## Recipe 2: Design Fidelity Validation **Use Case**: Compare implementation against Figma design or design reference. ### Pattern: Design Reference → Implementation → Visual Diff ```markdown ## Design Fidelity Check ### Step 1: Capture Design Reference **From Figma**: ``` # Use Figma MCP to export design mcp__figma__get_file_image(fileKey: "abc123", nodeId: "136-5051") # Save to: /tmp/design-reference.png ``` **From URL**: ``` mcp__chrome-devtools__new_page(url: "https://figma.com/proto/...") mcp__chrome-devtools__take_screenshot(filePath: "/tmp/design-reference.png") ``` **From Local File**: ``` # Already have reference at: /path/to/design.png ``` ### Step 2: Capture Implementation ``` mcp__chrome-devtools__navigate_page(url: "http://localhost:5173/component") mcp__chrome-devtools__resize_page(width: 1440, height: 900) # Match design viewport mcp__chrome-devtools__take_screenshot(filePath: "/tmp/implementation.png") ``` ### Step 3: 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: /tmp/implementation.png 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 4: Generate Fix Recommendations Parse vision model output and create actionable fixes for ui-developer agent.