accessibility-patterns

Accessibility Patterns

Reference guide for building inclusive, accessible web interfaces that comply with WCAG 2.1 AA standards.

Core Principles (POUR)

| Principle | Meaning | Key Question | |-----------|---------|-------------| | Perceivable | Content is available to all senses | Can users see, hear, or read it? | | Operable | Interface works with all input methods | Can users navigate with keyboard only? | | Understandable | Content and UI are predictable | Can users understand and recover from errors? | | Robust | Works across assistive technologies | Does it work with screen readers and future tools? |

Semantic HTML Reference

Use the right element for the job. Semantic HTML provides accessibility for free.

Document Structure

<header>     <!-- Site/section header, landmarks for screen readers -->
<nav>        <!-- Navigation links, announced as "navigation" -->
<main>       <!-- Primary content, skip-to target -->
<article>    <!-- Self-contained content (blog post, card) -->
<section>    <!-- Thematic grouping with heading -->
<aside>      <!-- Tangentially related (sidebar, callout) -->
<footer>     <!-- Site/section footer -->

Interactive Elements

| Need | Use | NOT | |------|-----|-----| | Clickable action | <button> | <div onclick> or <span onclick> | | Navigation link | <a href="..."> | <div onclick="navigate()"> | | Text input | <input type="text"> | <div contenteditable> | | Selection | <select> + <option> | Custom dropdown without ARIA | | Toggle | <input type="checkbox"> | <div class="toggle"> | | Form group | <fieldset> + <legend> | <div class="form-group"> |

Heading Hierarchy

<!-- CORRECT: Logical hierarchy, no skipped levels -->
<h1>Page Title</h1>
  <h2>Section</h2>
    <h3>Subsection</h3>
    <h3>Subsection</h3>
  <h2>Another Section</h2>

<!-- WRONG: Skipped levels, multiple h1, heading for styling -->
<h1>Title</h1>
<h1>Another Title</h1>  <!-- Only one h1 per page -->
  <h4>Jumped from h1 to h4</h4>  <!-- Skipped h2, h3 -->

ARIA Roles, States, and Properties

ARIA supplements HTML semantics. The first rule of ARIA: do not use ARIA if native HTML provides the semantics.

Landmark Roles

Most of these are already implied by semantic HTML.

| Role | HTML Equivalent | When to Use ARIA | |------|----------------|-----------------| | banner | <header> (top-level) | Nested headers needing landmark | | navigation | <nav> | Rarely needed | | main | <main> | Rarely needed | | complementary | <aside> | Rarely needed | | contentinfo | <footer> (top-level) | Nested footers needing landmark | | search | <search> | Browsers without <search> support | | form | <form> (with name) | Forms without accessible name | | region | <section> (with name) | Generic labeled regions |

Common ARIA Attributes

| Attribute | Purpose | Example | |-----------|---------|---------| | aria-label | Invisible label for element | <button aria-label="Close dialog">X</button> | | aria-labelledby | Points to visible label element | <div aria-labelledby="heading-id"> | | aria-describedby | Points to descriptive text | <input aria-describedby="password-help"> | | aria-expanded | Toggle/disclosure state | <button aria-expanded="false">Menu</button> | | aria-hidden | Hide from assistive tech | <span aria-hidden="true">decorative icon</span> | | aria-live | Announce dynamic content | <div aria-live="polite">Status: Saved</div> | | aria-required | Field is required | <input aria-required="true"> (prefer required attr) | | aria-invalid | Field has validation error | <input aria-invalid="true"> | | aria-current | Current item in a set | <a aria-current="page">Home</a> | | aria-disabled | Disabled but focusable | <button aria-disabled="true">Submit</button> |

Live Regions

For content that updates dynamically (notifications, status messages, chat).

<!-- Polite: announced after current speech finishes -->
<div aria-live="polite" aria-atomic="true">
  3 items in your cart
</div>

<!-- Assertive: interrupts current speech (use sparingly) -->
<div aria-live="assertive" role="alert">
  Error: Payment failed. Please try again.
</div>

<!-- Status: polite + role=status (form feedback, progress) -->
<div role="status">
  Saving... Done!
</div>

| Politeness | When to Use | |------------|------------| | polite | Status updates, cart counts, non-urgent info | | assertive | Errors, warnings, time-sensitive alerts | | off | Disable announcements (default) |

Keyboard Navigation

Focus Management Rules

| Rule | Implementation | |------|---------------| | All interactive elements are focusable | Use native HTML elements or tabindex="0" | | Focus order matches visual order | Source order = visual order, avoid CSS reordering | | Focus is visible | Never outline: none without a visible alternative | | No keyboard traps | User can always Tab away (except modal dialogs) | | Skip links available | First focusable element skips to main content |

Skip Link Pattern

<!-- First element in <body>, visually hidden until focused -->
<a href="#main-content" class="skip-link">
  Skip to main content
</a>

<!-- ... navigation ... -->

<main id="main-content" tabindex="-1">
  <!-- Content starts here -->
</main>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px 16px;
  background: #000;
  color: #fff;
  z-index: 100;
  transition: top 0.2s;
}

.skip-link:focus {
  top: 0;
}

Key Bindings Reference

| Pattern | Expected Keys | |---------|--------------| | Buttons | Enter or Space to activate | | Links | Enter to follow | | Checkboxes | Space to toggle | | Radio buttons | Arrow keys to move, Space to select | | Tabs | Arrow keys to switch, Tab to exit tab list | | Menus | Arrow keys to navigate, Enter to select, Escape to close | | Dialogs | Escape to close, Tab trapped inside, focus on close or first element | | Dropdowns | Arrow keys to navigate, Enter to select, Escape to close |

Tab Trap for Modals

function trapFocus(dialog) {
  const focusable = dialog.querySelectorAll(
    'a[href], button:not([disabled]), input:not([disabled]), ' +
    'select:not([disabled]), textarea:not([disabled]), [tabindex="0"]'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  dialog.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;

    if (e.shiftKey) {
      if (document.activeElement === first) {
        last.focus();
        e.preventDefault();
      }
    } else {
      if (document.activeElement === last) {
        first.focus();
        e.preventDefault();
      }
    }
  });

  first.focus();
}

Color Contrast Requirements

WCAG 2.1 AA Minimums

| Content Type | Minimum Ratio | Example | |-------------|--------------|---------| | Normal text (<18px / <14px bold) | 4.5:1 | #595959 on #FFFFFF = 7:1 | | Large text (>=18px / >=14px bold) | 3:1 | #767676 on #FFFFFF = 4.5:1 | | UI components & graphical objects | 3:1 | Borders, icons, focus indicators | | Decorative / logos | No requirement | Brand logos are exempt |

Testing Contrast

# Browser DevTools: Inspect element > Color picker shows ratio
# Chrome: Lighthouse > Accessibility audit
# Firefox: Accessibility Inspector > Check for issues

Do Not Rely on Color Alone

<!-- BAD: Color is the only indicator -->
<span style="color: red;">Error in this field</span>

<!-- GOOD: Color + icon + text -->
<span class="error">
  <svg aria-hidden="true"><!-- error icon --></svg>
  Error: Email address is required
</span>

<!-- BAD: Link distinguished only by color -->
<p>Read our <span style="color: blue;">terms of service</span></p>

<!-- GOOD: Link has underline (and color) -->
<p>Read our <a href="/terms">terms of service</a></p>

Form Accessibility

Labels and Instructions