browser-validator

Browser Validator Skill

Purpose

Validate design implementations in real browsers using Chrome DevTools MCP to ensure quality, accessibility, and responsiveness.

Philosophy

Real browser testing catches issues that code review cannot.

Core Beliefs

1. Test in Real Environments: Browsers behave differently than localhost
2. Multiple Breakpoints Required: Mobile, tablet, desktop have different challenges
3. Accessibility Requires Manual Verification: Automated tools miss context-dependent issues
4. Visual QA Prevents Surprises: Screenshots catch layout breaks before users see them

Why Browser Validation Matters

• Cross-Browser Consistency: Ensure components work everywhere
• Responsive Behavior: Verify breakpoints function correctly
• Accessibility Compliance: Check keyboard navigation and screen reader compatibility
• Professional Quality: Catch visual regressions before deployment

When This Skill Activates

This skill automatically activates when:

• User says "test this", "validate", "check if it works"
• After component implementation is complete
• User asks "does it look right?"
• User mentions "browser", "Chrome", or "DevTools"
• Component is ready for QA
• Before submitting for review

Decision Framework

Before validating in browser, determine:

What Needs Validation?

1. Responsive behavior → Test layout at 320px, 768px, 1024px breakpoints
2. Accessibility → Check contrast, keyboard nav, ARIA, focus indicators
3. Interactions → Test hover, click, focus states
4. Visual accuracy → Compare with design reference (if provided)
5. Functionality → Verify buttons, forms, links work correctly

What Are the Test URLs?

Local development:

• http://localhost:8000/component
• http://site.ddev.site/test-page
• http://site.test/node/123

Staging/production:

• https://staging.example.com/feature
• https://production.com/public-page

URL must be:

• Accessible from your machine
• Fully loaded (not 404, not auth-protected)
• Stable (not constantly changing)

What Breakpoints to Test?

Standard breakpoints (always test):

• ✅ Mobile: 320px x 568px (minimum, iPhone SE)
• ✅ Tablet: 768px x 1024px (iPad)
• ✅ Desktop: 1024px x 768px (laptop)
• ⚠️ Large desktop: 1920px x 1080px (optional)

What to check at each breakpoint:

• Layout doesn't break
• No horizontal scrolling
• Text is readable (no overflow)
• Touch targets ≥ 44px (mobile), ≥ 40px (desktop)
• Images don't extend beyond viewport

What Accessibility Checks?

WCAG 2.1 Level AA (always check):

• ✅ Color contrast: Calculate exact ratios (4.5:1 normal, 3:1 large)
• ✅ Keyboard navigation: Tab through all interactive elements
• ✅ Focus indicators: Visible 2px minimum
• ✅ Semantic HTML: Proper headings, landmarks, ARIA
• ✅ Alt text: Content images have descriptive alt, decorative have alt=""

How to test:

• Use mcp__chrome-devtools__press_key to Tab through page
• Use mcp__chrome-devtools__take_snapshot to check DOM structure
• Calculate contrast ratios from screenshots

What Interactions to Test?

Interactive states:

• :hover - Use mcp__chrome-devtools__hover on elements
• :focus - Tab to elements with keyboard
• :active - Click elements with mcp__chrome-devtools__click

Capture screenshots:

• Initial state
• Each breakpoint
• Hover/focus states
• Any dynamic behavior

What Errors to Check?

Console errors:

• Use mcp__chrome-devtools__list_console_messages
• Check for JavaScript errors
• Report with stack traces

Network issues:

• Use mcp__chrome-devtools__list_network_requests
• Check for 404s, failed requests
• Note slow-loading resources

Decision Tree

User requests browser validation
    ↓
Check: Chrome DevTools MCP available?
    ↓ Yes
Navigate to test URL
    ↓
Test each breakpoint (320/768/1024px)
    ↓
Capture screenshots at each breakpoint
    ↓
Check accessibility (contrast/keyboard/ARIA)
    ↓
Test interactions (hover/focus/click)
    ↓
Check console & network errors
    ↓
Generate detailed technical report

Required MCP Integration

This skill requires Chrome DevTools MCP integration. Correct tool names to use:

Navigation & Pages:

• mcp__chrome-devtools__navigate_page - Navigate to URL
• mcp__chrome-devtools__list_pages - Get available pages
• mcp__chrome-devtools__new_page - Create new tab

Viewport & Screenshots:

• mcp__chrome-devtools__resize_page - Change viewport size
• mcp__chrome-devtools__take_screenshot - Capture screenshot
• mcp__chrome-devtools__take_snapshot - Get DOM structure

Interaction:

• mcp__chrome-devtools__click - Click element by UID
• mcp__chrome-devtools__hover - Hover over element
• mcp__chrome-devtools__fill - Fill form field
• mcp__chrome-devtools__press_key - Press keyboard key

Debugging:

• mcp__chrome-devtools__list_console_messages - Get JavaScript errors
• mcp__chrome-devtools__list_network_requests - Check network activity

Validation Process

Phase 1: Initial Setup

// Navigate to test page
await mcp__chrome-devtools__navigate_page({
  url: testUrl,
  type: "url"
});

// Wait for page load (built-in)

// Take initial full-page screenshot
await mcp__chrome-devtools__take_screenshot({
  filePath: "screenshots/component/initial-fullpage.png",
  fullPage: true
});

// Get page structure
const pageSnapshot = await mcp__chrome-devtools__take_snapshot({
  verbose: true
});

Phase 2: DOM Structure Validation

// Get detailed page structure
const pageStructure = await mcp__chrome-devtools__take_snapshot({
  verbose: true
});

// Check for:
// - Proper semantic HTML
// - Heading hierarchy
// - Form labels
// - Image alt attributes
// - ARIA attributes
// - No empty elements

Semantic HTML Checklist:

• <header> for site/section header
• <nav> for navigation
• <main> for main content (only one per page)
• <article> for self-contained content
• <section> for thematic grouping
• <aside> for tangentially related content
• <footer> for site/section footer

Heading Hierarchy Check:

✅ GOOD:
<h1>Page Title</h1>
  <h2>Section 1</h2>
    <h3>Subsection 1.1</h3>
  <h2>Section 2</h2>

❌ BAD:
<h1>Page Title</h1>
  <h3>Section 1</h3>  ← Skipped h2
  <h2>Section 2</h2>

Image Alt Text Check:

✅ Content images: <img src="chart.png" alt="Q3 sales chart showing 25% growth">
✅ Decorative images: <img src="divider.png" alt="">
❌ Missing alt: <img src="photo.png">

Phase 3: Responsive Testing

Test at all standard breakpoints:

// Mobile (320px)
await mcp__chrome-devtools__resize_page({
  width: 320,
  height: 568
});
await mcp__chrome-devtools__take_screenshot({
  filePath: "screenshots/component/mobile-320px.png"
});

// Tablet (768px)
await mcp__chrome-devtools__resize_page({
  width: 768,
  height: 1024
});
await mcp__chrome-devtools__take_screenshot({
  filePath: "screenshots/component/tablet-768px.png"
});

// Desktop (1024px)
await mcp__chrome-devtools__resize_page({
  width: 1024,
  height: 768
});
await mcp__chrome-devtools__take_screenshot({
  filePath: "screenshots/component/desktop-1024px.png"
});

// Large Desktop (1920px) - optional
await mcp__chrome-devtools__resize_page({
  width: 1920,
  height: 1080
});
await mcp__chrome-devtools__take_screenshot({
  filePath: "screenshots/component/large-1920px.png"
});

Mobile Validation (320px-767px):

• No horizontal scrolling
• Text is readable (minimum 16px)
• Touch targets are 44px minimum
• Images scale properly
• Content stacks vertically
• Navigation is accessible
• Forms are usable

Tablet Validation (768px-1023px):

• Layout transitions smoothly
• Multi-column layouts work
• Navigation adapts appropriately
• Images maintain aspect ratio
• Spacing increases appropriately

Desktop Validation (1024px+):

• Full layout displays correctly
• Hover states function
• Maximum width constraints work
• Multi-column content aligns
• No excessive white space

Phase 4: Interactive Elements Testing

Test all interactive elements:

// Get page snapshot with element UIDs
const snapshot = await mcp__chrome-devtools__take_snapshot({
  verbose: false
});

// Find buttons by UID from snapshot
const buttons = snapshot.elements.filter(el => el.role === 'button');

// Test each button
for (const button of buttons) {
  // Hover test
  await mcp__chrome-devtools__hover({
    uid: button.uid
  });

  await mcp__chrome-devtools__take_screenshot({
    filePath: `screenshots/component/button-${button.uid}-hover.png`
  });

  // Click test
  await mcp__chrome-devtools__click({
    uid: button.uid
  });

  // Check result (wait for any changes)
  // Take screenshot if needed
}

// Test form interactions
const formInputs = snapshot.elements.filter(el => el.role === 'textbox');

for (const input of formInputs) {
  // Fill input
  await mcp__chrome-devtools__fill({
    uid: input.uid,
    value: "Test Value"
  });

  // Verify input accepted
}

// Test keyboard navigation
await mcp__chrome-devtools__press_key({
  key: "Tab"
});

// Check focus moved to next element

Button/Link Checklist:

• All buttons are clickable
• Links navigate to correct URLs
• Hover states appear
• Focus states are visible
• Disabled states are clear
• Loading states work (if applicable)

Phase 5: Keyboard Navigation Testing

Test complete keyboard navigation flow:

// Start from top of page
await mcp__chrome-devtools__navigate_page({
  url: testUrl,
  type: "reload"
});

// Tab through interactive elements
for (let i = 0; i < 10; i++) {
  await mcp__chrome-devtools__press_key({
    key: "Tab"
  });

  // Take snapshot to see what's focused
  const snapshot = await mcp__chrome-devtools__take_snapshot({
    verbose: false
  });

  // Check that focus indicator is visible
  // Check focus order is logical
}

// Test other keyboard interactions
await mcp__chrome-devtools__press_key({
  key: "Enter"  // Activate button
});

await mcp__chrome-devtools__press_key({
  key: "Escape"  // Close modal
});

await mcp__chrome-devtools__press_key({
  key: "Space"  // Activate button/checkbox
});

Keyboard Navigation Checklist:

• All interactive elements are focusable
• Focus order is logical (top→bottom, left→right)
• Focus indicators are visible (2px outline minimum)
• Enter/Space activates buttons
• Escape closes modals/dialogs
• Arrow keys work for custom components
• No keyboard traps

Phase 6: Color Contrast Analysis

Check all text meets WCAG AA requirements:

// Get all text elements from snapshot
const textElements = snapshot.elements.filter(el => el.text);

// For each text element:
// 1. Get computed foreground color
// 2. Get computed background color
// 3. Calculate contrast ratio
// 4. Compare against WCAG requirements

// WCAG AA Requirements:
// - Normal text (< 18pt or < 14pt bold): 4.5:1
// - Large text (≥ 18pt or ≥ 14pt bold): 3:1
// - UI components: 3:1

Contrast Ratio Calculation:

Relative Luminance (L) = 0.2126 * R + 0.7152 * G + 0.0722 * B
(where R, G, B are gamma corrected)

Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
(where L1 is lighter, L2 is darker)

Example:

Text: #666666 (rgb(102, 102, 102))
Background: #ffffff (rgb(255, 255, 255))

L1 = 1.0 (white)
L2 = 0.132 (gray)

Ratio = (1.0 + 0.05) / (0.132 + 0.05) = 3.8:1
Result: ❌ Fails WCAG AA (need 4.5:1)

Fix: Use #595959 instead
New ratio = 4.54:1 ✅ Passes

Phase 7: Console and Network Analysis

Check for JavaScript errors and network issues:

// Get console messages
const consoleMessages = await mcp__chrome-devtools__list_console_messages({
  types: ["error", "warn"],
  pageSize: 100
});

// Analyze errors
const errors = consoleMessages.filter(msg => msg.type === "error");
const warnings = consoleMessages.filter(msg => msg.type === "warn");

// Get network requests
const networkRequests = await mcp__chrome-devtools__list_network_requests({
  resourceTypes: ["document", "script", "stylesheet", "image"],
  pageSize: 100
});

// Find failed requests
const failedRequests = networkRequests.filter(req => req.status >= 400);

Console Issues to Report:

• ❌ JavaScript errors (with stack traces)
• ⚠️ Console warnings
• ❌ 404 errors (missing resources)
• ❌ CORS errors
• ⚠️ Deprecated API usage
• ❌ Network failures

Phase 8: Accessibility Audit

Comprehensive accessibility checks:

Focus Indicators:

// Check all focusable elements have visible indicators
// Minimum 2px outline
// High contrast color
// Non-hidden

ARIA Usage:

// Check proper ARIA attributes:
// - aria-label on icon-only buttons
// - aria-describedby for complex widgets
// - aria-live for dynamic content
// - aria-hidden for decorative elements
// - role attributes where needed

Touch Targets:

// Measure all interactive elements
// Must be ≥ 44x44px on mobile viewports
// Spacing between targets ≥ 8px

Report Format

Generate detailed technical report:

# Validation Report: Component Name
**URL**: {test-url}
**Date**: {timestamp}

## 📊 Summary
✅ Passed: {N} checks
⚠️  Warnings: {N} checks
❌ Failed: {N} checks

## 📱 Responsive Behavior

### Mobile (320px)
Screenshot: screenshots/component/mobile-320px.png
**Issues:**
❌ Text overflow in heading
   File: components/hero.scss:45
   Current: font-size: 2rem;
   Fix: font-size: clamp(1.5rem, 5vw, 2rem);

### Tablet (768px)
✅ Layout optimal

### Desktop (1024px)
✅ Layout optimal

## ♿ Accessibility

### Color Contrast
❌ Body text: 3.8:1 (need 4.5:1)
   File: components/hero.scss:23
   Current: color: #666
   Fix: color: #595959
   Calculation: (255+0.05)/(89+0.05) = 4.54:1 ✅

### Keyboard Navigation
✅ All elements focusable
⚠️  Focus indicator weak (1px)
   File: base/buttons.scss:15
   Fix: outline: 2px solid; outline-offset: 2px;

### ARIA
⚠️  Icon button missing label
   File: patterns/hero.php:42
   Fix: Add aria-label="Close banner"

## 🖱️  Interactions
✅ Hover states working
✅ Click handlers functioning

## 🐛 Console & Network
✅ No JavaScript errors
✅ All resources loaded

## 📝 Recommendations (Priority Order)

🔴 CRITICAL
1. Fix body text contrast (hero.scss:23)
2. Add aria-label to icon button (hero.php:42)

🟡 IMPORTANT
3. Fix mobile text overflow (hero.scss:45)
4. Strengthen focus indicators (buttons.scss:15)

🟢 NICE TO HAVE
5. Increase touch target size (hero.scss:67)

Error Handling

Chrome DevTools MCP Not Available

If Chrome DevTools MCP is not connected, provide manual checklist:

❌ Chrome DevTools MCP not connected

Browser validation requires Chrome DevTools MCP.

**To enable:**
1. Install: https://github.com/anthropics/claude-chrome-mcp
2. Configure in Claude Code settings
3. Restart Claude Code
4. Retry validation

**Alternative: Manual Validation Checklist**

Test URL: {test-url}

📋 Responsive Testing:
□ View at 320px width (mobile)
□ View at 768px width (tablet)
□ View at 1024px+ width (desktop)
□ No horizontal scrolling on mobile
□ Touch targets ≥ 44px on mobile

📋 Accessibility:
□ Check contrast: https://webaim.org/resources/contrastchecker/
□ Test Tab key navigation
□ Verify focus indicators visible
□ Check heading hierarchy
□ Verify alt text on images

📋 Interactions:
□ Test all hover states
□ Test all click actions
□ Check console for errors
□ Verify network requests successful

Test URL Not Accessible

❌ Cannot access test URL: {url}

**Possible issues:**
- Local dev server not running
- URL typo
- Network/firewall restrictions
- HTTPS certificate issues

**Solutions:**
1. Verify URL in browser first
2. Check dev server is running
3. Try alternate URL
4. Check /etc/hosts for local domains

Best Practices

1. Test Early: Don't wait until implementation is complete
2. Test Often: Validate after each significant change
3. Fix Critical First: Address WCAG failures before UX issues
4. Re-validate: Always re-run after applying fixes
5. Real Devices: Follow up automated tests with real device testing
6. Document Issues: Save reports for reference and tracking

Integration with Commands

This skill is used by:

/design-to-block Command

• Validates WordPress block patterns after creation
• Checks responsive behavior
• Ensures accessibility compliance

/design-to-paragraph Command

• Validates Drupal paragraph types after creation
• Tests responsive layouts
• Verifies accessibility

/design-validate Command

• Standalone validation of any implementation
• Can compare against design reference
• Generates detailed technical report

Common Validation Failures

Text Overflow on Mobile

Symptom: Heading text wraps awkwardly or extends beyond container Fix: Use fluid typography with clamp()

Low Contrast

Symptom: Text difficult to read, fails WCAG AA Fix: Darken text color or lighten background

Weak Focus Indicators

Symptom: Hard to see which element has keyboard focus Fix: Increase outline to 2px, add offset

Small Touch Targets

Symptom: Buttons/links difficult to tap on mobile Fix: Increase padding to ensure 44px minimum

Missing ARIA Labels

Symptom: Screen readers can't identify icon-only buttons Fix: Add aria-label with descriptive text

JavaScript Errors

Symptom: Console shows errors, functionality broken Fix: Debug and fix JavaScript, verify asset paths

Testing Scope

What this validates:

• ✅ Responsive layouts at multiple breakpoints
• ✅ WCAG AA accessibility (contrast, keyboard nav, ARIA)
• ✅ Interactive element functionality
• ✅ JavaScript console errors
• ✅ Network request failures
• ✅ Visual accuracy (if design reference provided)

What this does NOT validate:

• ❌ Cross-browser compatibility (Chrome only)
• ❌ Performance metrics (use performance tools)
• ❌ Security vulnerabilities
• ❌ Code quality
• ❌ SEO