accessibility

Accessibility

Overview

Every user-facing UI must meet WCAG 2.1 AA. Keyboard, labels, contrast, and semantics are required — not optional polish.

When to Use

• /design audits
• Light check during /ui builds
• Dedicated accessibility fixes

Workflow

1. Keyboard

• All interactive elements focusable (native <button>, <a>, or tabIndex={0} + key handler)
• Logical focus order; visible focus indicators (focus-visible outline)
• Focus trapped in modals; restore to trigger on close
• Skip link to main content when long nav exists

Recipe — focus trap (vanilla):

// Trap focus inside a modal
function trapFocus(modal) {
  const focusable = modal.querySelectorAll(
    'a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];
  
  modal.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  });
  first?.focus();
}

Recipe — skip link:

<a href="#main-content" class="skip-link">Skip to main content</a>
<!-- In CSS: .skip-link { position: absolute; top: -100%; }
     .skip-link:focus { top: 0; z-index: 9999; } -->
<main id="main-content">...</main>

2. ARIA / labels

• Form inputs have visible labels (<label for="id"> or wrapping <label>)
• Icon-only buttons have aria-label
• Toggle states use aria-pressed, aria-expanded, aria-selected
• Loading announced via aria-busy="true" on the loading container
• Live regions (aria-live="polite") for dynamic content updates (toasts, search results count)

Recipe — live region for dynamic count:

<div aria-live="polite" aria-atomic="true" class="sr-only">
  <!-- JS updates this when results change -->
  <span id="result-count">12 results found</span>
</div>