Debugging and Troubleshooting

// Steps to debug accessibility in Chrome:

1. Open DevTools (F12 or Cmd+Option+I)
2. Select Elements tab
3. Choose an element in the DOM tree
4. Click "Accessibility" tab in the right panel

// What you can inspect:
- Computed Properties: role, name, description
- ARIA Attributes: all aria-* values
- Accessibility Tree: hierarchical view
- Source order vs. visual order
- Contrast ratio for text elements

// Using Lighthouse for automated testing:
1. DevTools → Lighthouse tab
2. Select "Accessibility" category
3. Choose device (Mobile/Desktop)
4. Click "Generate report"

// Results include:
- Score (0-100)
- Passed audits
- Failed audits with elements affected
- Manual checks to perform
- Detailed documentation links

// Advanced features in Firefox DevTools:

1. Accessibility Panel:
   - Full accessibility tree view
   - Shows all ARIA roles and properties
   - Relationship arrows (labelledby, describedby, controls)
   - Tabbing order visualization

2. Simulation Tools:
   - Simulate: Click "Simulate" dropdown
   - Options: None, Protanopia, Deuteranopia, Tritanopia, 
             Achromatopsia, Contrast loss

3. Keyboard Navigation Checker:
   - Shows tab order with numbers
   - Highlights focusable elements
   - Identifies keyboard traps

4. Check for Issues:
   - Click "Check for issues" button
   - Filters: All issues, Contrast, Keyboard, Text labels
   - Shows count and severity

// Essential NVDA shortcuts for debugging:

NVDA+N              // Open NVDA menu
NVDA+Q              // Quit NVDA
NVDA+T              // Read title
NVDA+B              // Read status bar

// Navigation:
H / Shift+H         // Next/Previous heading
K / Shift+K         // Next/Previous link
F / Shift+F         // Next/Previous form field
B / Shift+B         // Next/Previous button
D / Shift+D         // Next/Previous landmark
1-6 / Shift+1-6     // Next/Previous heading level

// Reading:
Insert+↓            // Say all (read from current position)
NVDA+F7             // Element list (landmarks, headings, links, etc.)
NVDA+Space          // Toggle browse/focus mode

// Debugging specific elements:
NVDA+Tab            // Report current element (role, name, state)
Insert+F            // Report formatting
NVDA+F             // Find text on page

// Testing live regions:
NVDA+Shift+R        // Toggle between live region verbosity modes
NVDA+5 (numpad)     // Report current location

// Common issues to check:
1. Speech Viewer shows actual announcements
2. Browse mode works for static content
3. Focus mode activates for form controls
4. All interactive elements announced correctly
5. ARIA live regions announce changes
6. No unexpected announcement duplication

// Essential VoiceOver shortcuts for debugging:
// (VO = Control+Option)

VO+F5               // Start VoiceOver
VO+F8               // Open VoiceOver Utility
Cmd+F5              // Toggle VoiceOver on/off

// Navigation:
VO+→                // Move to next item
VO+←                // Move to previous item
VO+Shift+↓          // Enter group/container
VO+Shift+↑          // Exit group/container

// Web Rotor (navigate by element type):
VO+U                // Open rotor
← / →               // Switch category (headings, links, landmarks, etc.)
↓ / ↑               // Select item in category
Enter               // Navigate to selected item

// Reading:
VO+A                // Read from current position
VO+Shift+U          // Open Item Chooser (search)

// Debugging:
VO+F3               // Read caption (accessibility label)
VO+F4               // Read hint
VO+Shift+H          // Hear element description
VO+J                // Jump to linked item

// Verbosity settings:
VO+V                // Open Verbosity menu
                    // Adjust announcement detail level

// Testing checklist:
1. All elements reachable with VO+→
2. Rotor shows proper structure (headings, landmarks)
3. Forms mode activates for inputs
4. Buttons announce role and state
5. Live regions announce updates
6. Table headers announced with cells
7. Image alt text read correctly

// Missing alt text - FIX:
<!-- Before: -->
<img src="logo.png">
<!-- After: -->
<img src="logo.png" alt="Company Name Logo">
<!-- Decorative: -->
<img src="decorative.png" alt="">

// Poor contrast - FIX:
/* Before: */
.text { color: #777; background: #fff; } /* 3.3:1 - FAIL */
/* After: */
.text { color: #595959; background: #fff; } /* 4.5:1 - PASS */

// Unlabeled input - FIX:
<!-- Before: -->
<input type="text" placeholder="Enter name">
<!-- After: -->
<label for="name">Name:</label>
<input type="text" id="name" placeholder="e.g., John Smith">

// Non-semantic button - FIX:
<!-- Before: -->
<div onclick="submit()">Submit</div>
<!-- After: -->
<button type="button" onclick="submit()">Submit</button>

// Missing focus indicator - FIX:
/* Before: */
button:focus { outline: none; } /* BAD */
/* After: */
button:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

// Incorrect heading order - FIX:
<!-- Before: -->
<h1>Page Title</h1>
<h3>Section</h3> <!-- Skipped H2 -->
<!-- After: -->
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

// Empty link - FIX:
<!-- Before: -->
<a href="/profile"><img src="user.png"></a>
<!-- After: -->
<a href="/profile">
  <img src="user.png" alt="View profile">
</a>
<!-- Or: -->
<a href="/profile" aria-label="View profile">
  <img src="user.png" aria-hidden="true">
</a>

// Non-descriptive link - FIX:
<!-- Before: -->
<a href="/article1">Read more</a>
<!-- After: -->
<a href="/article1">Read more about Web Accessibility</a>
<!-- Or: -->
<a href="/article1" aria-label="Read more about Web Accessibility">
  Read more
</a>

// Check accessibility tree in Chrome DevTools:
// 1. Select element in Elements panel
// 2. Open Accessibility tab
// 3. Look for:

Computed Properties:
  Name: "Submit form"          // From aria-label, label, or content
  Role: "button"               // Semantic or ARIA role  
  Description: "Save changes"  // From aria-describedby
  
// Common issues to look for:

// Issue: Name is empty
<button></button>  
// Fix: Add text content or aria-label
<button>Submit</button>
<button aria-label="Submit form"><span aria-hidden="true">✓</span></button>

// Issue: Role is "generic" when it should be specific
<div onclick="doSomething()">Click me</div>
// Fix: Add role and make keyboard accessible
<div role="button" tabindex="0" onclick="doSomething()">Click me</div>
// Better: Use semantic HTML
<button onclick="doSomething()">Click me</button>

// Issue: aria-labelledby references non-existent ID
<button aria-labelledby="submit-label">Send</button>
// No element with id="submit-label" exists
// Fix: Create the element or remove the attribute
<span id="submit-label">Submit form</span>
<button aria-labelledby="submit-label">Send</button>

// Issue: Required ARIA attributes missing
<div role="tab">Tab 1</div>
// Missing: aria-selected, aria-controls
// Fix: Add required attributes
<div role="tab" 
     aria-selected="true" 
     aria-controls="panel1"
     tabindex="0">Tab 1</div>

// Validate ARIA with axe DevTools:
const axe = require('axe-core');
axe.run(document, {
  rules: {
    'aria-allowed-attr': { enabled: true },
    'aria-required-attr': { enabled: true },
    'aria-required-children': { enabled: true },
    'aria-required-parent': { enabled: true },
    'aria-valid-attr': { enabled: true },
    'aria-valid-attr-value': { enabled: true }
  }
}, (err, results) => {
  console.log(results.violations);
});

// MISTAKE 1: aria-label on div without role
<div aria-label="Important message">Content</div>
// FIX: Add appropriate role or use semantic element
<div role="region" aria-label="Important message">Content</div>
<section aria-label="Important message">Content</section>

// MISTAKE 2: Hiding focusable element
<button aria-hidden="true">Click me</button>
// FIX: Remove aria-hidden or make non-focusable
<button>Click me</button>
<span aria-hidden="true">Decorative icon</span>

// MISTAKE 3: Using role on semantic element unnecessarily
<button role="button">Submit</button>
<nav role="navigation">...</nav>
// FIX: Remove redundant role
<button>Submit</button>
<nav>...</nav>

// MISTAKE 4: Invalid ARIA attribute value
<button aria-pressed="yes">Toggle</button>
// FIX: Use valid value (true/false/mixed)
<button aria-pressed="true">Toggle</button>

// MISTAKE 5: Missing required children
<div role="list">
  <div>Item 1</div>
  <div>Item 2</div>
</div>
// FIX: Add required child role
<div role="list">
  <div role="listitem">Item 1</div>
  <div role="listitem">Item 2</div>
</div>
// Or use semantic HTML
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

// MISTAKE 6: Live region not in DOM on load
// Wrong: Creating live region dynamically
function announce(message) {
  const live = document.createElement('div');
  live.setAttribute('role', 'status');
  live.textContent = message;
  document.body.appendChild(live);
}
// FIX: Create live region once on page load
<div role="status" aria-live="polite" class="sr-only"></div>
function announce(message) {
  document.querySelector('[role="status"]').textContent = message;
}

// MISTAKE 7: Not updating dynamic ARIA
<button aria-expanded="false" onclick="toggle()">Menu</button>
function toggle() {
  menu.hidden = !menu.hidden;
  // Missing: Update aria-expanded
}
// FIX: Update ARIA attribute
function toggle() {
  const isExpanded = menu.hidden;
  menu.hidden = !menu.hidden;
  button.setAttribute('aria-expanded', isExpanded);
}

// Essential Browser + Screen Reader Combinations:

Windows:
  - NVDA + Firefox (most common free combination)
  - JAWS + Chrome (enterprise standard)
  - Narrator + Edge (built-in Windows)

macOS:
  - VoiceOver + Safari (most accurate pairing)
  - VoiceOver + Chrome (secondary testing)

iOS:
  - VoiceOver + Safari (mobile)

Android:
  - TalkBack + Chrome (mobile)

// Testing workflow:
1. Automated testing (same across browsers):
   - Run Lighthouse in Chrome
   - Run axe DevTools extension
   - Validate HTML with W3C Validator

2. Keyboard testing (each browser):
   ✓ Tab through entire page
   ✓ Shift+Tab reverses correctly
   ✓ Enter activates links/buttons
   ✓ Space activates buttons/toggles
   ✓ Arrow keys work in custom widgets
   ✓ Esc closes modals/menus
   ✓ No keyboard traps

3. Screen reader testing (each combination):
   ✓ Page structure (headings, landmarks)
   ✓ All content reachable
   ✓ Forms properly labeled
   ✓ Error messages announced
   ✓ Dynamic content updates announced
   ✓ Images have appropriate alt text
   ✓ Tables announce headers

4. Visual testing (each browser):
   ✓ Focus indicators visible (3:1 contrast)
   ✓ Text contrast meets WCAG AA
   ✓ Zoom to 200% - no horizontal scroll
   ✓ Dark mode works correctly
   ✓ High contrast mode (Windows)

5. Mobile testing (iOS + Android):
   ✓ Touch targets 44×44px minimum
   ✓ Pinch zoom enabled
   ✓ Screen reader gestures work
   ✓ Content reflows for small screens
   ✓ No reliance on hover

// Safari specific:
// Enable Tab navigation: Safari Preferences → Advanced → 
// "Press Tab to highlight each item on a webpage"

// Test in Safari specifically:
- Tab behavior different from other browsers
- Form validation messages styled differently  
- VoiceOver integration most accurate with Safari
- Some ARIA features work only in Safari+VO

// Firefox specific:
// Best accessibility DevTools
- Most standards-compliant ARIA implementation
- Preferred for NVDA testing
- Focus management most predictable

// Chrome/Edge specific:
// Chromium-based - similar behavior
- Best Lighthouse integration
- Most common browser globally
- Test with JAWS (common enterprise SR)

// Mobile Safari (iOS):
// VoiceOver built-in
- Swipe right/left to navigate
- Two-finger scroll
- Rotor gestures (VO+U equivalent)
- Test zoom and reflow

// Chrome Android:
// TalkBack built-in on most Android
- Swipe right/left to navigate  
- Explore by touch
- Volume key shortcuts
- Test with different screen sizes

// Feature support differences:
// Always check caniuse.com for:
const features = {
  'focus-visible': 'Safari partial support',
  'prefers-reduced-motion': 'IE11 not supported',
  'prefers-color-scheme': 'IE11 not supported',
  'prefers-contrast': 'Limited support',
  'inert': 'Chrome 102+, Safari 15.5+',
  'aria-description': 'Chrome 83+, limited SR support'
};

// Provide fallbacks:
@media (prefers-reduced-motion: reduce) {
  * { animation: none !important; }
}
/* Fallback for older browsers */
.no-prefers-reduced-motion {
  animation: none !important;
}