Accessibility (a11y) Skill

Overview

This skill centralizes accessibility guidelines and best practices for all technologies and frameworks used in the project, including HTML, CSS, React, MUI, Astro, React Native, and more. It covers semantic structure, ARIA usage, color contrast, keyboard navigation, and compliance with WCAG and WAI-ARIA standards.

Objective

Ensure all user interfaces meet accessibility standards (WCAG 2.1/2.2 Level AA minimum) across all technologies. This skill provides universal accessibility guidance that technology-specific skills can reference.

When to Use

Use this skill when:

• Building UI components with interactive elements
• Implementing forms, modals, or custom widgets
• Adding dynamic content or live regions
• Ensuring keyboard navigation
• Reviewing accessibility compliance
• Testing with screen readers

Don’t use this skill for:

• Technology-specific implementation (delegate to react, html, etc.)
• General coding patterns (use conventions skill)
• Pure backend logic (no UI)

Critical Patterns

✅ REQUIRED: Semantic HTML Elements

<!-- ✅ CORRECT: Semantic elements -->
<nav>
  <a href="/home">Home</a>
</nav>
<main>
  <article>Content</article>
</main>
<button onClick="{action}">Submit</button>

<!-- ❌ WRONG: Non-semantic divs -->
<div class="nav">
  <div onClick="{navigate}">Home</div>
</div>
<div class="main">
  <div>Content</div>
</div>
<div onClick="{action}">Submit</div>

✅ REQUIRED: Keyboard Accessibility

// ✅ CORRECT: Keyboard events
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>

// ❌ WRONG: Mouse-only events
<div onClick={handleClick}> // Not keyboard accessible

✅ REQUIRED: Form Labels

<!-- ✅ CORRECT: Associated label -->
<label htmlFor="email">Email Address</label>
<input id="email" type="email" />

<!-- ❌ WRONG: No label association -->
<div>Email Address</div>
<input type="email" />

✅ REQUIRED: Alt Text for Images

<!-- ✅ CORRECT: Descriptive alt for informative images -->
<img src="chart.png" alt="Sales increased 25% in Q4" />

<!-- ✅ CORRECT: Empty alt for decorative images -->
<img src="decorative-border.png" alt="" />

<!-- ❌ WRONG: Missing alt -->
<img src="chart.png" />

Conventions

Semantic HTML

• Use semantic elements (<nav>, <main>, <article>, <aside>, <footer>)
• Proper heading hierarchy (h1 → h2 → h3, no skipping levels)
• Use <button> for actions, <a> for navigation
• Form labels must be associated with inputs

ARIA

• Use ARIA only when semantic HTML is insufficient
• Prefer native elements over ARIA roles
• Common patterns: aria-label, aria-labelledby, aria-describedby
• Required for dynamic content: aria-live, aria-atomic

Keyboard Navigation

• All interactive elements must be keyboard accessible
• Logical tab order (use tabindex only when necessary)
• Visible focus indicators
• Escape key closes modals/dropdowns

Color and Contrast

• Text contrast ratio 4.5:1 minimum (7:1 for Level AAA)
• Large text (18pt+) minimum 3:1
• Don’t rely solely on color to convey information
• Test with color blindness simulators
• UI component contrast 3:1 (WCAG 2.1)
• Focus indicators contrast 3:1 (WCAG 2.2)

Touch Targets & Interaction

• Touch target size minimum 24x24px (WCAG 2.2)
• Recommend 44x44px for better usability (WCAG 2.1 AAA)
• Adequate spacing between targets
• No dragging movements required unless essential (WCAG 2.2)

Screen Readers

• Provide alternative text for images (alt attribute)
• Use aria-hidden="true" for decorative elements
• Announce dynamic content changes with aria-live
• Test with screen readers (NVDA, JAWS, VoiceOver)

Decision Tree

Interactive element (button, link)? → Ensure keyboard accessible (Tab, Enter/Space), visible focus indicator, proper role and semantic element.

Form field? → Associate <label> with input (htmlFor/id), provide error messages with aria-describedby, announce errors with aria-live.

Dynamic content change? → Use aria-live="polite" for non-urgent updates, aria-live="assertive" for critical alerts, aria-atomic="true" if entire region should be read.

Custom widget (dropdown, modal, tabs)? → Follow WAI-ARIA Authoring Practices patterns, implement keyboard navigation (Arrow keys, Escape, Enter), manage focus properly.

Image or icon? → Decorative: alt="" or aria-hidden="true". Informative: descriptive alt text. Icon-only button: aria-label.

Color conveys meaning? → Add text label, icon, or pattern. Verify 4.5:1 contrast ratio for text, 3:1 for UI components.

Modal or overlay? → Trap focus inside modal, restore focus on close, allow Escape to dismiss, use aria-modal="true" and role="dialog".

Loading or status change? → Use aria-busy="true" during loading, role="status" for status messages, ensure screen reader announces completion.

Edge Cases

WCAG 2.2 updates:**

• 24x24px minimum target size (lowered from 44×44, but 44×44 still recommended)
• Focus appearance: Focus indicators must have 3:1 contrast ratio
• Dragging movements: Provide single-pointer alternatives for drag operations
• Redundant entry: Don’t make users re-enter information already provided
• Accessible authentication: Don’t require cognitive function tests (CAPTCHAs should have alternatives)

** Skip links: Provide “Skip to main content” link as first focusable element for keyboard users to bypass navigation.

Focus trap issues: Libraries like React may interfere with focus management. Test focus trap explicitly in modals.

ARIA live regions throttling: Rapid updates may be throttled by screen readers. Debounce updates or use atomic regions.

Touch target size: Minimum 44×44 pixels for touch targets (WCAG 2.1). Use padding to increase clickable area.

Hidden content: Use aria-hidden="true" for visual-only elements. Use sr-only class for screen-reader-only text.

Custom controls: For complex widgets (datepickers, sliders), follow WAI-ARIA Authoring Practices patterns exactly.

References

• https://www.w3.org/WAI/WCAG21/quickref/
• https://www.w3.org/WAI/ARIA/apg/