accessibility-wcag

Accessibility & WCAG Compliance

Audit web applications for WCAG 2.1/2.2 compliance, fix accessibility barriers, implement proper semantic HTML and ARIA patterns.

BAD: Common Accessibility Violations

// BAD: Div button without keyboard support
<div className="btn" onClick={handleClick}>
  Submit
</div>

// BAD: Color-only error indication
<input className="border-red-500" />
<span style={{color: 'red'}}>Error</span>

// BAD: Image without alt text
<img src="/chart.png" />

// BAD: Aria-label overuse
<button aria-label="Click me">Click me</button>

// BAD: Auto-focus abuse
<input autoFocus />
<Modal open={isOpen}>
  <input autoFocus /> {/* Steals focus */}
</Modal>

// BAD: No heading hierarchy
<h1>Page Title</h1>
<h4>Section</h4> {/* Skips h2, h3 */}

// BAD: Form without labels
<input type="text" placeholder="Email" />
<select>
  <option>Choose...</option>
</select>

// BAD: Custom dropdown without keyboard support
<div onClick={toggle}>
  {options.map(opt => <div onClick={() => select(opt)}>{opt}</div>)}
</div>

GOOD: Accessible Implementations

// GOOD: Semantic button with proper keyboard support
<button type="button" onClick={handleClick}>
  Submit
</button>

// GOOD: Multi-sensory error indication
<input
  className="border-red-500"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" className="text-red-600" role="alert">
  <span className="sr-only">Error:</span>
  Invalid email format
</span>

// GOOD: Descriptive alt text (or empty for decorative)
<img src="/sales-chart.png" alt="Sales increased 40% in Q4" />
<img src="/decorative-line.svg" alt="" role="presentation" />

// GOOD: Redundant aria-label removed
<button>Click me</button>

// GOOD: Managed focus with trap
function Modal({ open, onClose, children }) {
  const modalRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!open) return;

    const previousFocus = document.activeElement as HTMLElement;
    modalRef.current?.focus();

    return () => previousFocus?.focus();
  }, [open]);

  return (
    <div
      ref={modalRef}
      role="dialog"
      aria-modal="true"
      tabIndex={-1}
      onKeyDown={(e) => {
        if (e.key === 'Escape') onClose();
      }}
    >
      {children}
    </div>
  );
}

// GOOD: Proper heading hierarchy
<h1>Page Title</h1>
<h2>Main Section</h2>
<h3>Subsection</h3>
<h2>Another Section</h2>

// GOOD: Labeled form controls
<label htmlFor="email">Email address</label>
<input
  id="email"
  type="email"
  aria-required="true"
  aria-describedby="email-hint"
/>
<span id="email-hint" className="text-gray-600">
  We'll never share your email
</span>

<label htmlFor="country">Country</label>
<select id="country" aria-required="true">
  <option value="">Select a country</option>
  <option value="us">United States</option>
</select>

// GOOD: Accessible custom dropdown
function Dropdown({ options, value, onChange, label }) {
  const [open, setOpen] = useState(false);
  const [activeIndex, setActiveIndex] = useState(0);
  const buttonRef = useRef<HTMLButtonElement>(null);
  const listRef = useRef<HTMLUListElement>(null);

  const handleKeyDown = (e: KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        setActiveIndex(prev => Math.min(prev + 1, options.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        setActiveIndex(prev => Math.max(prev - 1, 0));
        break;
      case 'Enter':
      case ' ':
        e.preventDefault();
        onChange(options[activeIndex]);
        setOpen(false);
        buttonRef.current?.focus();
        break;
      case 'Escape':
        setOpen(false);
        buttonRef.current?.focus();
        break;
    }
  };

  return (
    <div>
      <button
        ref={buttonRef}
        type="button"
        aria-haspopup="listbox"
        aria-expanded={open}
        aria-labelledby="dropdown-label"
        onClick={() => setOpen(!open)}
      >
        <span id="dropdown-label">{label}</span>: {value}
      </button>

      {open && (
        <ul
          ref={listRef}
          role="listbox"
          aria-labelledby="dropdown-label"
          onKeyDown={handleKeyDown}
          tabIndex={-1}
        >
          {options.map((opt, i) => (
            <li
              key={opt}
              role="option"
              aria-selected={i === activeIndex}
              onClick={() => {
                onChange(opt);
                setOpen(false);
                buttonRef.current?.focus();
              }}
            >
              {opt}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}