DOMAIN:ACCESSIBILITY:COMPONENT_PATTERNS

OWNER: julian (compliance), alexander (design) ALSO_USED_BY: floris, floor, antje UPDATED: 2026-03-26 SCOPE: accessible implementation patterns for common UI components REFERENCE: WAI-ARIA Authoring Practices Guide (APG) — w3.org/WAI/ARIA/apg/patterns/

---

COMPONENT_PATTERNS:PRINCIPLE

RULE_1: use native HTML elements before ARIA — no ARIA is better than bad ARIA RULE_2: every custom component must match the WAI-ARIA APG keyboard interaction pattern RULE_3: every custom component must be tested with NVDA and VoiceOver RULE_4: component implementations must be documented in DESIGN.md with accessibility notes

---

PATTERN:FORMS

FORM_FIELD_BASICS

RULE: every input must have a visible, associated label RULE: never use placeholder as the only label — it disappears on input RULE: group related fields with fieldset + legend RULE: mark required fields with aria-required="true" AND visual indicator RULE: describe constraints with aria-describedby

PATTERN — TEXT_INPUT:

<div class="field">
  <label for="email">Email address <span aria-hidden="true">*</span></label>
  <input type="email" id="email" name="email"
         autocomplete="email"
         aria-required="true"
         aria-describedby="email-hint email-error">
  <p id="email-hint" class="hint">We will use this for login</p>
  <p id="email-error" class="error" role="alert" hidden>
    Please enter a valid email address
  </p>
</div>

PATTERN — FIELD_GROUP:

<fieldset>
  <legend>Billing address</legend>
  <label for="street">Street</label>
  <input type="text" id="street" autocomplete="street-address">
  <label for="city">City</label>
  <input type="text" id="city" autocomplete="address-level2">
  <label for="postal">Postal code</label>
  <input type="text" id="postal" autocomplete="postal-code">
</fieldset>

FORM_VALIDATION

RULE: display errors in text, not color alone RULE: associate errors with fields via aria-describedby RULE: use aria-invalid="true" on invalid fields RULE: announce errors with role="alert" or aria-live="assertive" RULE: move focus to first error field on form submission failure RULE: provide error summary at top of form for complex forms

PATTERN — ERROR_STATE:

<label for="phone">Phone number</label>
<input type="tel" id="phone"
       aria-invalid="true"
       aria-describedby="phone-error">
<p id="phone-error" class="error" role="alert">
  Phone number must include country code (e.g., +31 6 12345678)
</p>

PATTERN — ERROR_SUMMARY:

<div role="alert" aria-labelledby="error-heading" tabindex="-1">
  <h2 id="error-heading">There are 2 errors in this form</h2>
  <ul>
    <li><a href="#email">Email address is required</a></li>
    <li><a href="#phone">Phone number format is invalid</a></li>
  </ul>
</div>

SELECT / COMBOBOX

NATIVE_SELECT: use for simple lists (up to ~15 options) CUSTOM_COMBOBOX: use WAI-ARIA combobox pattern for searchable/autocomplete

PATTERN — NATIVE_SELECT:

<label for="country">Country</label>
<select id="country" name="country" autocomplete="country">
  <option value="">Select a country</option>
  <option value="NL">Netherlands</option>
  <option value="DE">Germany</option>
  <option value="BE">Belgium</option>
</select>

COMBOBOX_ARIA: - role="combobox" on the input - aria-expanded="true/false" based on list visibility - aria-controls pointing to the listbox ID - aria-activedescendant pointing to highlighted option - role="listbox" on the options container - role="option" on each option

KEYBOARD: - Down Arrow — open list, move to next option - Up Arrow — move to previous option - Enter — select highlighted option, close list - Escape — close list without selecting - Type ahead — filter options

---

PATTERN:MODAL_DIALOG

ARIA_REQUIREMENTS

ROLE: role="dialog" on the modal container MODAL: aria-modal="true" — tells assistive tech content behind is inert LABEL: aria-labelledby pointing to the modal title DESCRIPTION: aria-describedby pointing to modal description (optional)

FOCUS_MANAGEMENT

RULE: on open — move focus to first focusable element (or modal title if content is long) RULE: trap focus inside modal — Tab and Shift+Tab cycle within modal only RULE: on close — return focus to the element that triggered the modal RULE: Escape key closes the modal RULE: clicking backdrop closes the modal (optional but expected)

PATTERN:

<div role="dialog" aria-modal="true"
     aria-labelledby="modal-title"
     aria-describedby="modal-desc">
  <h2 id="modal-title">Delete project?</h2>
  <p id="modal-desc">
    This action cannot be undone. All project data will be permanently removed.
  </p>
  <div class="modal-actions">
    <button type="button" data-action="cancel">Cancel</button>
    <button type="button" data-action="confirm">Delete project</button>
  </div>
</div>

FOCUS_TRAP_IMPLEMENTATION

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

  modal.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
    if (e.key === 'Escape') {
      closeModal(modal);
    }
  });

  first.focus();
}

KEYBOARD: - Tab — cycle through focusable elements inside modal - Shift+Tab — reverse cycle - Escape — close modal - Enter/Space — activate buttons

TESTING: open modal → verify focus is inside modal TESTING: Tab to last element → Tab again → verify focus wraps to first element TESTING: press Escape → verify modal closes and focus returns to trigger TESTING: verify content behind modal is inert (not focusable)

---

PATTERN:NAVIGATION_MENU

LANDMARK

RULE: wrap primary navigation in