Web Accessibility (A11y)

When to use this skill

• New UI Component Development: Designing accessible components
• Accessibility Audit: Identifying and fixing accessibility issues in existing sites
• Form Implementation: Writing screen reader-friendly forms
• Modals/Dropdowns: Focus management and keyboard trap prevention
• WCAG Compliance: Meeting legal requirements or standards

Input Format

Required Information

• Framework: React, Vue, Svelte, Vanilla JS, etc.
• Component Type: Button, Form, Modal, Dropdown, Navigation, etc.
• WCAG Level: A, AA, AAA (default: AA)

Optional Information

• Screen Reader: NVDA, JAWS, VoiceOver (for testing)
• Automated Testing Tool: axe-core, Pa11y, Lighthouse (default: axe-core)
• Browser: Chrome, Firefox, Safari (default: Chrome)

Input Example

Make a React modal component accessible:
- Framework: React + TypeScript
- WCAG Level: AA
- Requirements:
  - Focus trap (focus stays inside the modal)
  - Close with ESC key
  - Close by clicking the background
  - Title/description read by screen readers

Instructions

Step 1: Use Semantic HTML

Use meaningful HTML elements to make the structure clear.

Tasks:

• Use semantic tags: <button>, <nav>, <main>, <header>, <footer>, etc.
• Avoid overusing <div> and <span>
• Use heading hierarchy (<h1> ~ <h6>) correctly
• Connect <label> with <input>

Example (❌ Bad vs ✅ Good):

<!-- ❌ Bad example: using only div and span -->
<div class="header">
  <span class="title">My App</span>
  <div class="nav">
    <div class="nav-item" onclick="navigate()">Home</div>
    <div class="nav-item" onclick="navigate()">About</div>
  </div>
</div>

<!-- ✅ Good example: semantic HTML -->
<header>
  <h1>My App</h1>
  <nav aria-label="Main navigation">
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>
</header>

Form Example:

<!-- ❌ Bad example: no label -->
<input type="text" placeholder="Enter your name">

<!-- ✅ Good example: label connected -->
<label for="name">Name:</label>
<input type="text" id="name" name="name" required>

<!-- Or wrap with label -->
<label>
  Email:
  <input type="email" name="email" required>
</label>

Step 2: Implement Keyboard Navigation

Ensure all features are usable without a mouse.

Tasks:

• Move focus with Tab and Shift+Tab
• Activate buttons with Enter/Space
• Navigate lists/menus with arrow keys
• Close modals/dropdowns with ESC
• Use tabindex appropriately

Decision Criteria:

• Interactive elements → tabindex="0" (focusable)
• Exclude from focus order → tabindex="-1" (programmatic focus only)
• Do not change focus order → avoid using tabindex="1+"

Example (React Dropdown):

import React, { useState, useRef, useEffect } from 'react';

interface DropdownProps {
  label: string;
  options: { value: string; label: string }[];
  onChange: (value: string) => void;
}

function AccessibleDropdown({ label, options, onChange }: DropdownProps) {
  const [isOpen, setIsOpen] = useState(false);
  const [selectedIndex, setSelectedIndex] = useState(0);
  const buttonRef = useRef<HTMLButtonElement>(null);
  const listRef = useRef<HTMLUListElement>(null);

  // Keyboard handler
  const handleKeyDown = (e: React.KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        if (!isOpen) {
          setIsOpen(true);
        } else {
          setSelectedIndex((prev) => (prev + 1) % options.length);
        }
        break;

      case 'ArrowUp':
        e.preventDefault();
        if (!isOpen) {
          setIsOpen(true);
        } else {
          setSelectedIndex((prev) => (prev - 1 + options.length) % options.length);
        }
        break;

      case 'Enter':
      case ' ':
        e.preventDefault();
        if (isOpen) {
          onChange