UX Accessibility

UX Accessibility Skill

Accessibility-first design patterns for WCAG 2.2 AA compliance. This skill provides implementation guidance for making interactive components accessible to all users.

Related Skills

• material-symbols-v3: Icon accessibility patterns (aria-hidden, aria-label)
• ux-iconography: Icon button patterns and screen reader text
• ux-component-states: ARIA state attributes for interactive elements

Project Accessibility Tokens

This project defines accessibility tokens in css/styles/accessibility.css:

:root {
  --focus-ring-width: 2px;
  --focus-ring-offset: 2px;
  --focus-ring-color: var(--color-primary);
  --min-touch-target: 44px;
  --transition-fast: 150ms ease;
}

Focus Management

Focus Ring Implementation

Always use the project's focus tokens for consistent visible focus:

.interactive:focus-visible {
  outline: var(--focus-ring-width) solid var(--focus-ring-color);
  outline-offset: var(--focus-ring-offset);
}

Focus Trap for Modals

When implementing modals or dialogs, trap focus using direct element references (NO querySelector):

class ModalDialog extends HTMLElement {
  // Store focusable elements as direct references during construction
  #closeBtn;
  #confirmBtn;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    // Build DOM imperatively, storing references
    this.#closeBtn = document.createElement('button');
    this.#closeBtn.className = 'close-btn';
    this.#closeBtn.textContent = '×';
    this.#closeBtn.setAttribute('part', 'close');

    this.#confirmBtn = document.createElement('button');
    this.#confirmBtn.className = 'confirm-btn';
    this.#confirmBtn.textContent = 'Confirm';
    this.#confirmBtn.setAttribute('part', 'confirm');

    const container = document.createElement('div');
    container.className = 'modal';
    container.setAttribute('part', 'container');
    container.appendChild(this.#closeBtn);
    container.appendChild(document.createElement('slot'));
    container.appendChild(this.#confirmBtn);

    this.shadowRoot.appendChild(container);
  }

  connectedCallback() {
    this.addEventListener('keydown', this);
  }

  disconnectedCallback() {
    this.removeEventListener('keydown', this);
  }

  handleEvent(e) {
    if (e.type === 'keydown' && e.key === 'Tab') {
      const active = this.shadowRoot.activeElement;

      if (e.shiftKey && active === this.#closeBtn) {
        e.preventDefault();
        this.#confirmBtn.focus();
      } else if (!e.shiftKey && active === this.#confirmBtn) {
        e.preventDefault();
        this.#closeBtn.focus();
      }
    }
  }
}

Return Focus After Close

Store and restore focus when closing overlays:

#previouslyFocused = null;

open() {
  this.#previouslyFocused = document.activeElement;
  this.showModal();
}

close() {
  this.close();
  this.#previouslyFocused?.focus();
}

Keyboard Navigation

Standard Patterns

Implementation Example (Web Component)

class KeyboardNav extends HTMLElement {
  // Direct element references - NO querySelector
  #items = [];
  #currentIndex = 0;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    // Build items during construction, store direct references
  }

  connectedCallback() {
    this.setAttribute('role', 'menu');
    this.setAttribute('tabindex', '0');
    this.addEventListener('keydown', this);
  }

  disconnectedCallback() {
    this.removeEventListener('keydown', this);
  }

  handleEvent(e) {
    if (e.type === 'keydown') {
      switch (e.key) {
        case 'Enter':
        case ' ':
          e.preventDefault();
          this.#activate();
          break;
        case 'Escape':
          this.#close();
          break;
        case 'ArrowDown':
          e.preventDefault();
          this.#focusNext();
          break;
        case 'ArrowUp':
          e.preventDefault();
          this.#focusPrevious();
          break;
      }
    }
  }

  #focusNext() {
    this.#currentIndex = Math.min(this.#currentIndex + 1, this.#items.length - 1);
    this.#items[this.#currentIndex]?.focus();
  }

  #focusPrevious() {
    this.#currentIndex = Math.max(this.#currentIndex - 1, 0);
    this.#items[this.#currentIndex]?.focus();
  }

  #activate() {
    this.dispatchEvent(new CustomEvent('item-activated', {
      bubbles: true,
      composed: true,
      detail: { index: this.#currentIndex }
    }));
  }

  #close() {
    this.dispatchEvent(new CustomEvent('menu-close', {
      bubbles: true,
      composed: true
    }));
  }
}

Screen Reader Support

ARIA Attributes

Required ARIA for interactive components:

<!-- Button with state -->
<button
  role="button"
  aria-pressed="false"
  aria-label="Toggle menu">

<!-- Live region for announcements -->
<div role="status" aria-live="polite" aria-atomic="true">
  Score updated: 42 points
</div>

<!-- Dialog -->
<dialog
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title">

Live Regions

Use for dynamic content updates. Store the announcer as a direct reference (NO querySelector):

class AnnouncingComponent extends HTMLElement {
  #announcer;

  constructor() {
    super();
    this.attachShadow({ mode: 'open' });

    // Create and store direct reference during construction
    this.#announcer = document.createElement('div');
    this.#announcer.setAttribute('role', 'status');
    this.#announcer.setAttribute('aria-live', 'polite');
    this.#announcer.setAttribute('aria-atomic', 'true');
    this.#announcer.className = 'sr-only';

    this.shadowRoot.appendChild(this.#announcer);
  }

  announce(message) {
    // Use direct reference - never querySelector
    this.#announcer.textContent = '';
    requestAnimationFrame(() => {
      this.#announcer.textContent = message;
    });
  }
}

Screen Reader Only Content

Use the .sr-only utility for visually hidden but accessible content:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Reduced Motion

Respecting User Preferences

Always check for reduced motion preference:

/* In component styles */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

JavaScript Animation Check

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

if (!prefersReducedMotion) {
  animate(element, { scale: [1, 1.1, 1], duration: 200 });
} else {
  // Apply instant state change
  element.classList.add('active');
}

High Contrast Mode

Forced Colors Support

@media (forced-colors: active) {
  .button {
    border: 2px solid ButtonText;
    background: ButtonFace;
    color: ButtonText;
  }

  .button:focus {
    outline: 3px solid Highlight;
  }

  .icon {
    forced-color-adjust: auto;
  }
}

Touch Targets

Minimum Size Requirements

WCAG requires 44x44px minimum touch targets:

.touch-target {
  min-width: var(--min-touch-target);
  min-height: var(--min-touch-target);
  padding: var(--space-xs);
}

/* For smaller visual elements, expand hit area */
.small-button {
  position: relative;
}

.small-button::after {
  content: '';
  position: absolute;
  inset: -8px; /* Expand clickable area */
}

Color Contrast

Minimum Ratios

• Normal text: 4.5:1 contrast ratio
• Large text (18pt+): 3:1 contrast ratio
• UI components: 3:1 contrast ratio

Testing Contrast

Use project semantic colors which are pre-validated:

• --color-text on --theme-surface: Meets AA
• --color-muted for secondary text: Meets AA for large text
• --color-primary for interactive: Meets 3:1 for UI

Skip Links

For keyboard users to bypass navigation:

<a href="#main-content" class="skip-link">Skip to main content</a>

<style>
.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  z-index: 1000;
  padding: var(--space-s) var(--space-m);
  background: var(--theme-surface);
  color: var(--color-text);
}

.skip-link:focus {
  top: 0;
}
</style>

Checklist

Before shipping any interactive component:

• Focus visible on all interactive elements
• Keyboard operable (Enter, Space, Escape, Arrows)
• ARIA roles and labels present
• Color contrast meets 4.5:1 (text) or 3:1 (UI)
• Touch targets are 44x44px minimum
• Reduced motion respected
• High contrast mode tested
• Screen reader announcement for state changes