browser-debug

name	browser-debug
description	Browser debugging workflows for Chrome DevTools, Firefox DevTools, and AI agent debugging. Use when debugging UI issues, inspecting elements, analyzing performance, or troubleshooting rendering problems in the browser. Triggers: "debug", "devtools", "inspect", "console", "network", "performance", "memory", "render", "layout", "css issue", "js error".
category	web-ui

Skill: browser-debug

What This Covers

Browser debugging using Chrome DevTools, Firefox DevTools, and programmatic debugging with Puppeteer/Playwright. Covers DOM inspection, CSS debugging, JavaScript debugging, performance analysis, network monitoring, memory profiling, and accessibility auditing.

Core Tools

Chrome DevTools

Panel	Purpose	Shortcut
Elements	DOM/CSS inspection	Ctrl+Shift+C
Console	JS execution/logs	Ctrl+Shift+J
Sources	JS debugging/breakpoints	Ctrl+Shift+F
Network	Request monitoring	Ctrl+Shift+E
Performance	Runtime profiling	Ctrl+Shift+Q
Memory	Heap snapshots	Ctrl+Shift+M
Lighthouse	Audits	Ctrl+Shift+P → "Lighthouse"
Accessibility	A11y tree	Ctrl+Shift+P → "Accessibility"

Firefox DevTools

Panel	Purpose	Shortcut
Inspector	DOM/CSS inspection	Ctrl+Shift+C
Console	JS execution/logs	Ctrl+Shift+K
Debugger	JS debugging	Ctrl+Shift+Z
Network	Request monitoring	Ctrl+Shift+E
Performance	Runtime profiling	Ctrl+Shift+I → Performance
Accessibility	A11y inspector	Ctrl+Shift+I → Accessibility

Debugging Workflows

CSS Layout Issues

1. Open Elements panel → select element
2. Check Computed tab for actual values
3. Use Box Model overlay to verify padding/margin
4. Toggle CSS properties to test changes
5. Check for conflicting selectors in Specificity view

# Check for CSS issues programmatically
npx impeccable detect src/ examples/

JavaScript Errors

1. Open Console panel
2. Filter by "Errors" level
3. Click error to jump to Sources panel
4. Set breakpoint at error location
5. Inspect stack trace and variables

# Check for JS errors in source
grep -rE "console\.(error|warn)" src/ examples/ --include='*.js'

Performance Issues

1. Open Performance panel → Record
2. Interact with page (click, scroll, type)
3. Stop recording → analyze flame chart
4. Look for long tasks (>50ms)
5. Check for layout thrashing (forced reflows)

# Check source weight
find src/ examples/ -name '*.js' -o -name '*.css' | xargs wc -c

Network Issues

1. Open Network panel → check "Disable cache"
2. Reload page → analyze waterfall
3. Filter by type (JS, CSS, Image, XHR)
4. Check for slow requests (>1s)
5. Verify CSP headers in Response tab

Memory Leaks

1. Open Memory panel → take Heap Snapshot
2. Perform actions that might leak
3. Take another Heap Snapshot
4. Compare snapshots → look for growing objects
5. Check for detached DOM nodes

Accessibility Issues

1. Open Accessibility panel (Chrome) or Accessibility Inspector (Firefox)
2. Check for missing names on interactive elements
3. Verify contrast ratios
4. Check ARIA attributes
5. Run axe-core audit

# Run accessibility audit
npx axe-core src/ examples/

AI Agent Debugging Patterns

Console Logging

// Structured logging with context
console.error('[Module]', { action: 'fetch', error: err.message });

// Performance timing
console.time('render');
renderComponent();
console.timeEnd('render');

Error Boundaries

window.addEventListener('error', (e) => {
  console.error('[App]', e.error || e.message);
});
window.addEventListener('unhandledrejection', (e) => {
  console.error('[App] Unhandled', e.reason);
});

DOM Inspection

// Query elements
document.querySelectorAll('[aria-label]');

// Check computed styles
getComputedStyle(element).getPropertyValue('color');

// Verify visibility
element.getBoundingClientRect();

Common Issues and Fixes

Issue	Symptom	Fix
Layout thrash	Janky scrolling	Batch DOM reads/writes
CLS shift	Content jumping	Set explicit dimensions
Memory leak	Growing heap	Remove event listeners
CSP blocked	Resources not loading	Update CSP headers
Contrast fail	A11y audit errors	Use design tokens
Overflow clip	Dropdowns hidden	Use position: fixed

Commands

# Run impeccable detect for anti-patterns
npx impeccable detect src/ examples/

# Check for console errors in source
grep -rE "console\.(error|warn)" src/ examples/ --include='*.js'

# Check ARIA usage
grep -rE "aria-label|role=" src/ examples/ --include='*.html' --include='*.js' | wc -l

# Check CSP headers
grep -rE "Content-Security-Policy" src/ examples/ --include='*.html'

# Check source weight
find src/ examples/ -name '*.js' -o -name '*.css' | xargs wc -c

# Run full quality gate
bash scripts/quality-gate.sh

Rules

• Always check Console for errors before debugging
• Use Device Mode to test responsive layouts
• Record Performance traces for runtime issues
• Take Heap Snapshots before and after actions for memory leaks
• Verify ARIA attributes in Accessibility panel
• Check Network tab for blocked requests and CSP violations
• Use Lighthouse for comprehensive audits
• Prefer transform/opacity for animations (GPU-accelerated)
• Test with prefers-reduced-motion enabled