Stop Breaking the Web: A Dev's Guide to ARIA Accessibility

<!-- This looks fine, works fine, but breaks for 1 billion users -->
<div class="btn" onclick="submit()">
  Submit Form
</div>

<!-- This actually works for everyone -->
<button type="submit">Submit Form</button>

// Role: What is it?
role="button"

// Property: What's it like?  
aria-required="true"

// State: What's happening?
aria-expanded="false"

# Terminal test
npm install -g @axe-core/cli
axe https://yoursite.com

# Manual tests (do these right now)
# 1. Tab through your site (no mouse)
# 2. Turn on high contrast mode
# 3. Zoom to 200%
# 4. Use VoiceOver (Mac: Cmd+F5) or NVDA (Windows: free)

<!-- Don't reinvent the wheel -->
<button>Native Button</button>

<!-- But if you must... -->
<div role="button" 
     tabindex="0"
     aria-label="Close dialog"
     onKeyPress="handleEnterSpace(event)"
     onClick="handleClick()">
  ×
</div>

<script>
function handleEnterSpace(e) {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handleClick();
  }
}
</script>

<!-- Before: Silent failures -->
<input type="email" required>
<span class="error hidden">Invalid email</span>

<!-- After: Accessible feedback -->
<label for="email">Email Address</label>
<input id="email" 
       type="email" 
       aria-required="true"
       aria-invalid="false"
       aria-describedby="email-error">
<div id="email-error" 
     role="alert" 
     aria-live="assertive"
     class="error hidden">
  Invalid email format
</div>

<!-- Status container -->
<div id="status" role="status" aria-live="polite"></div>

<script>
// This announces to screen readers
document.getElementById('status').textContent = 'Changes saved!';

// For urgent updates
document.getElementById('status').setAttribute('aria-live', 'assertive');
</script>

<!-- Accessible dropdown -->
<nav>
  <button aria-expanded="false" 
          aria-controls="nav-menu"
          aria-haspopup="true">
    Menu
  </button>
  <ul id="nav-menu" hidden>
    <li><a href="/home">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

import { useState, useRef, useEffect } from 'react';

function AccessibleModal({ isOpen, onClose, title, children }) {
  const modalRef = useRef(null);
  const previousFocus = useRef(null);

  useEffect(() => {
    if (isOpen) {
      previousFocus.current = document.activeElement;
      modalRef.current?.focus();
    } else {
      previousFocus.current?.focus();
    }
  }, [isOpen]);

  const handleKeyDown = (e) => {
    if (e.key === 'Escape') {
      onClose();
    }
  };

  if (!isOpen) return null;

  return (
    <div 
      className="modal-overlay"
      onClick={onClose}
    >
      <div
        ref={modalRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby="modal-title"
        tabIndex={-1}
        onKeyDown={handleKeyDown}
        onClick={(e) => e.stopPropagation()}
      >
        <h2 id="modal-title">{title}</h2>
        {children}
        <button onClick={onClose}>Close</button>
      </div>
    </div>
  );
}

// Usage
<AccessibleModal 
  isOpen={showModal} 
  onClose={() => setShowModal(false)}
  title="Confirm Action"
>
  <p>Are you sure you want to delete this item?</p>
</AccessibleModal>

// Find missing labels
console.log('Unlabeled inputs:', 
  Array.from(document.querySelectorAll('input, textarea, select'))
    .filter(el => !el.labels?.length && 
                  !el.getAttribute('aria-label') && 
                  !el.getAttribute('aria-labelledby'))
);

// Check for bad tabindex
console.log('Positive tabindex (avoid these):', 
  Array.from(document.querySelectorAll('[tabindex]'))
    .filter(el => el.tabIndex > 0)
);

// Find interactive elements without ARIA
console.log('Interactive divs/spans missing roles:',
  Array.from(document.querySelectorAll('div[onclick], span[onclick]'))
    .filter(el => !el.getAttribute('role'))
);

<!-- ❌ Redundant -->
<button role="button">Click me</button>

<!-- ✅ Native semantics -->
<button>Click me</button>

<!-- ❌ Mouse-only -->
<div role="button" onclick="handleClick()">Submit</div>

<!-- ✅ Keyboard accessible -->
<div role="button" 
     tabindex="0" 
     onclick="handleClick()"
     onkeydown="handleKeyPress(event)">Submit</div>

<!-- ❌ Focus disappears -->
<button onclick="this.remove()">Delete</button>

<!-- ✅ Focus moves logically -->
<button onclick="deleteAndFocus()">Delete</button>

<!-- ❌ Unnecessary -->
<h1 aria-label="Page Title">Page Title</h1>

<!-- ✅ Only when needed -->
<button aria-label="Close dialog">×</button>

# Lighthouse accessibility audit
lighthouse https://yoursite.com --only-categories=accessibility

# Color contrast check (if you have node)
npx @adobe/leonardo-contrast-colors --bg "#ffffff" --colors "#0066cc"