ux-accessibility

Web组件的WCAG 2.2无障碍模式。在实现焦点管理、键盘导航、屏幕阅读器支持、减少动作、高对比度模式或触摸目标时使用。与项目的accessibility.css令牌集成。(项目)

📖 中文导读:Web组件的WCAG 2.2无障碍模式。在实现焦点管理、键盘导航、屏幕阅读器支持、减少动作、高对比度模式或触摸目标时使用。与项目的accessibility.css令牌集成。(项目) 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: ux-accessibility description: WCAG 2.2 accessibility patterns for web components. Use when implementing focus management, keyboard navigation, screen reader support, reduced motion, high contrast mode, or touch targets. Integrates with project's accessibility.css tokens. (project) allowed-tools: - Read - Write - Edit - Glob - Grep

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.

  • 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

Component Key Action
Button Enter, Space Activate
Menu Arrow keys Navigate items
Dialog Escape Close
Tabs Arrow keys Switch tabs
Listbox Arrow keys, Home, End Navigate options

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

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