accessibility

UI Accessibility (WCAG 2.1)

Overview

This skill guides implementation and review of accessible UI components following WCAG 2.1 Level AA standards. Accessibility ensures your interface is usable by everyone—keyboard users, screen reader users, users with low vision, and users with cognitive disabilities.

Core principle: Semantic HTML first, ARIA last. Keyboard navigation and screen reader support are non-negotiable.

---

When to Use / When NOT to Use

✅ Use This Skill When

• Building new UI components (buttons, modals, dropdowns, forms, tabs)
• Adding keyboard navigation or focus management
• Reviewing code for accessibility violations
• Testing with screen readers or keyboard-only
• Ensuring color contrast and visual focus indicators
• Adding ARIA attributes to dynamic content

❌ Do NOT Use When

• Component is purely decorative (no interaction needed)
• Audience explicitly doesn't include users with accessibility needs (internally impossible—always assume diverse users)
• You're skipping automated testing due to time constraints (violates DoD)

---

Core Concepts

1. Semantic HTML Structure

Foundation: Use meaningful HTML elements to convey structure and purpose.

<!-- ✅ CORRECT: Semantic structure -->
<header role="banner">
  <nav aria-label="Main navigation">
    <ul>
      <li><a href="/home">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>
</header>

<main id="main-content">
  <article>
    <h1>Page Title</h1>
    <section>
      <h2>Section Heading</h2>
      <p>Content...</p>
    </section>
  </article>
</main>

<footer>
  <p>&copy; 2026 Company</p>
</footer>

<!-- ✅ CORRECT: Proper heading hierarchy -->
<h1>Main Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>
<h2>Another Section</h2>

<!-- ❌ WRONG: Non-semantic div soup -->
<div class="header">
  <div class="nav">
    <div>Home</div>
    <div>About</div>
  </div>
</div>
<div class="main">
  <div class="title">Page Title</div>
</div>

<!-- ❌ WRONG: Skipping heading hierarchy -->
<h1>Main Title</h1>
<h3>Jumps to h3 (breaks hierarchy)</h3>