accessibility-excellence

# Accessibility Excellence

## Overview

Accessibility is the practice of making your product usable by everyone, including people with disabilities. It's not a feature to be added later—it's a fundamental requirement that should be built into every decision you make.

This skill teaches you to think about accessibility systematically: understanding WCAG standards, implementing semantic HTML, ensuring keyboard navigation, supporting screen readers, and designing inclusively.

## Core Philosophy: Accessibility is Inclusion

Accessibility benefits everyone, not just people with disabilities:

- **Captions** help people in noisy environments, not just deaf people
- **Keyboard navigation** helps people with motor disabilities, but also power users
- **Clear language** helps people with cognitive disabilities, but also non-native speakers
- **High contrast** helps people with low vision, but also people in bright sunlight
- **Transcripts** help deaf people, but also people who prefer reading

When you design for accessibility, you design for everyone.

## WCAG Standards

The Web Content Accessibility Guidelines (WCAG) define accessibility standards. There are three levels:

**WCAG 2.1 Levels:**
- **Level A** — Basic accessibility
- **Level AA** — Enhanced accessibility (recommended minimum)
- **Level AAA** — Advanced accessibility (ideal, but not always practical)

### The Four Principles (POUR)

**1. Perceivable**
Information must be perceivable to users. It can't be invisible to all senses.

**Guideline 1.1: Text Alternatives**
Provide text alternatives for all non-text content (images, videos, etc.).

```html
<!-- Good -->
<img src="chart.png" alt="Sales increased 25% in Q4" />

<!-- Bad -->
<img src="chart.png" alt="chart" />
<img src="chart.png" /> <!-- No alt text -->
```

**Guideline 1.4: Distinguishable**
Make it easy to see and hear content. Ensure sufficient contrast, readable text, and clear audio.

```css
/* Good - 4.5:1 contrast ratio (WCAG AA) */
color: #030712; /* dark text */
background-color: #F9FAFB; /* light background */

/* Bad - 2.5:1 contrast ratio (fails WCAG AA) */
color: #9CA3AF; /* medium gray text */
background-color: #F9FAFB; /* light background */
```

**2. Operable**
Users must be able to navigate and interact with your product. All functionality must be available from the keyboard.

**Guideline 2.1: Keyboard Accessible**
All functionality must be available from the keyboard.

```html
<!-- Good - keyboard accessible -->
<button onClick={handleClick}>Click Me</button>

<!-- Bad - not keyboard accessible -->
<div onClick={handleClick}>Click Me</div>

<!-- Good - keyboard accessible with proper focus management -->
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click Me
</div>
```

**Guideline 2.4: Navigable**
Users must be able to navigate your product easily. Provide clear navigation, focus indicators, and skip links.

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

<!-- Good - clear heading structure -->
<h1>Page Title</h1>
<h2>Section 1</h2>
<h3>Subsection 1.1</h3>

<!-- Good - focus visible -->
<button style="outline: 2px solid #3B82F6; outline-offset: 2px;">
  Focused Button
</button>
```

**3. Understandable**
Users must be able to understand your content and how to use your product.

**Guideline 3.1: Readable**
Make text readable and understandable.

```html
<!-- Good - clear, simple language -->
<p>Save your document before closing.</p>

<!-- Bad - jargon, unclear -->
<p>Persist your artifact prior to terminating the session.</p>

<!-- Good - define abbreviations -->
<p>The <abbr title="World Wide Web Consortium">W3C</abbr> sets web standards.</p>
```

**Guideline 3.3: Predictable**
Make your product predictable. Users should know what will happen when they interact with it.

```html
<!-- Good - clear form labels -->
<label for="email">Email Address</label>
<input id="email" type="email" />

<!-- Bad - unclear labels -->
<input type="email" placeholder="Enter your email" />

<!-- Good - clear error messages -->
<input type="email" aria-invalid="true" />
<span role="alert">Please enter a valid email address.</span>

<!-- Bad - unclear error messages -->
<input type="email" style="border: 1px solid red;" />
```

**4. Robust**
Your product must be robust enough to be interpreted by a wide variety of assistive technologies.

**Guideline 4.1: Compatible**
Maximize compatibility with assistive technologies. Use semantic HTML and ARIA appropriately.

```html
<!-- Good - semantic HTML -->
<nav>
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

<!-- Bad - non-semantic HTML -->
<div class="nav">
  <div class="nav-item"><span onclick="navigate('/')">Home</span></div>
  <div class="nav-item"><span onclick="navigate('/about')">About</span></div>
</div>

<!-- Good - ARIA for custom components -->
<div
  role="button"
  tabIndex={0}
  aria-pressed={isPressed}
  onClick={toggle}
  onKeyDown={(e) => e.key === 'Enter' && toggle()}
>
  Toggle
</div>
```

## Semantic HTML

Semantic HTML is the foundation of accessibility. Use HTML elements that describe their meaning, not just their appearance.

### Common Semantic Elements

| Element | Purpose | When to Use |
| :--- | :--- | :--- |
| `<header>` | Introductory content | Top of page or section |
| `<nav>` | Navigation links | Main navigation, breadcrumbs |
| `<main>` | Main content | Primary content area |
| `<article>` | Self-contained content | Blog posts, news articles |
| `<section>` | Thematic grouping | Chapters, sections of content |
| `<aside>` | Tangential content | Sidebars, related links |
| `<footer>` | Footer content | Bottom of page or section |
| `<h1>-<h6>` | Headings | Page structure and hierarchy |
| `<button>` | Clickable button | User actions |
| `<a>` | Link | Navigation |
| `<form>` | Form container | Data collection |
| `<label>` | Form label | Associate text with form input |
| `<input>` | Form input | User input |
| `<textarea>` | Multi-line text input | Longer text input |
| `<select>` | Dropdown menu | Option selection |

### Semantic HTML Example

```html
<!-- Good - semantic HTML -->
<body>
  <header>
    <nav>
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
        <li><a href="/contact">Contact</a></li>
      </ul>
    </nav>
  </header>

  <main>
    <article>
      <h1>Article Title</h1>
      <p>Article content...</p>
    </article>

    <aside>
      <h2>Related Articles</h2>
      <ul>
        <li><a href="/article-1">Article 1</a></li>
        <li><a href="/article-2">Article 2</a></li>
      </ul>
    </aside>
  </main>

  <footer>
    <p>&copy; 2026 My Company</p>
  </footer>
</body>
```

## Keyboard Navigation

### Tab Order

Ensure a logical tab order through your page. By default, tab order follows the HTML source order.

```html
<!-- Good - logical tab order -->
<button>First</button>
<button>Second</button>
<button>Third</button>

<!-- Bad - illogical tab order (don't use tabindex > 0) -->
<button tabIndex={3}>Third</button>
<button tabIndex={1}>First</button>
<button tabIndex={2}>Second</button>

<!-- Good - skip interactive elements that aren't visible -->
<a href="#main-content" className="skip-link">Skip to main content</a>
<nav><!-- navigation --></nav>
<main id="main-content"><!-- main content --></main>
```

### Focus Management

Ensure focus is visible and managed appropriately:

```css
/* Good - visible focus indicator */
button:focus-visible {
  outline: 2px solid #3B82F6;
  outline-offset: 2px;
}

/* Bad - no focus indicator */
button:focus {
  outline: none;
}

/* Good - focus trap in modal */
const Modal = () => {
  const firstButtonRef = useRef(null);
  const lastButtonRef = useRef(null);

  const handleKeyDown = (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstButtonRef.current) {
        e.preventDefault();
        lastButtonRef.current?.focus();
      } else if (!e.shiftKey && document.activeElement === lastButtonRef.current) {
        e.preventDefault();
        firstButtonRef.current?.focus();
      }
    }
  };

  return (
    <div role="dialog" onKeyDown={handleKeyDown}>
      <button ref={firstButtonRef}>First</button>
      <button>Middle</button>
      <button ref={lastButtonRef}>Last</button>
    </div>
  );
};
```

### Keyboard Event Handling

Handle keyboard events appropriately:

```typescript
// Good - handle both click and keyboard
const Button = ({ onClick, children }) => {
  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      onClick?.();
    }
  };

  return (
    <button onClick={onClick} onKeyDown={handleKeyDown}>
      {children}
    </button>
  );
};

// Good - handle Escape key in modal
const Modal = ({ onClose }) => {
  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Escape') {
      onClose();
    }
  };

  return (
    <div role="dialog" onKeyDown={handleKeyDown}>
      {/* modal content */}
    </div>
  );
};
```

## Screen Reader Support

### ARIA (Accessible Rich Internet Applications)

ARIA provides additional semantic information for assistive technologies:

```html
<!-- Good - ARIA labels -->
<button aria-label="Close menu">×</button>

<!-- Good - ARIA live regions -->
<div aria-live="polite" aria-atomic="true">
  Item added to cart
</div>

<!-- Good - ARIA roles -->
<div role="alert">Error: Please fill in all required fields.</div>

<!-- Good - ARIA expanded -->
<button aria-expanded={isOpen} aria-controls="menu">
  Menu
</button>
<div id="menu" hidden={!isOpen}>
  {/* menu items */}
</div>

<!-- Good - ARIA current -->
<nav>
  <a href="/" aria-current="page">Home</a>
  <a href="/about">About</a>
</nav>
```

### Screen Reader Testing

Test with actual screen readers:

```html
<!-- Good - descriptive link text -->
<a href="/article">Read more about accessibility</a>

<!-- Bad - vague link text -->
<a href="/article">Read more</a>

<!-- Good - descriptive button text -->
<button>Delete account</button>

<!-- Bad - vague button text -->
<button>Delete</button>

<!-- Good - form labels associated with inputs -->
<label for="email">Email Address</label>
<input id="email" type="email" />

<!-- Bad - unassociated labels -->
<label>Email Address</label>
<input type="email" />
```

## Color Contrast

### Contrast Ratios

Ensure sufficient contrast between text and background:

```css
/* WCAG AA - Normal text (4.5:1) */
color: #030712; /* dark text */
background-color: #F9FAFB; /* light background */
/* Contrast ratio: 19:1 ✓ */

/* WCAG AA - Large text (3:1) */
color: #4B5563; /* medium gray text */
background-color: #F9FAFB; /* light background */
/* Contrast ratio: 6.5:1 ✓ */

/* WCAG AAA - Normal text (7:1) */
color: #030712; /* dark text */
background-color: #F9FAFB; /* light background */
/* Contrast ratio: 19:1 ✓ */

/* Fails WCAG AA */
color: #9CA3AF; /* light gray text */
background-color: #F9FAFB; /* light background */
/* Contrast ratio: 2.5:1 ✗ */
```

### Testing Contrast

Use tools like WebAIM Contrast Checker or Polished:

```javascript
import { readableColor } from 'polished';

const backgroundColor = '#3B82F6';
const textColor = readableColor(backgroundColor); // Returns #FFFFFF or #000000
```

## Inclusive Design Practices

### 1. Don't Rely on Color Alone

Use patterns, icons, or text labels in addition to color:

```html
<!-- Good - color + icon + text -->
<span style="color: green;">
  <CheckIcon />
  Success
</span>

<!-- Bad - color alone -->
<span style="color: green;">Success</span>

<!-- Good - color + pattern -->
<div style="background: repeating-linear-gradient(45deg, #3B82F6, #3B82F6 10px, #2563EB 10px, #2563EB 20px);">
  Pattern
</div>

<!-- Bad - color alone -->
<div style="background-color: #3B82F6;">Color</div>
```

### 2. Provide Alternatives for Images

```html
<!-- Good - descriptive alt text -->
<img src="chart.png" alt="Sales increased 25% in Q4 2025" />

<!-- Bad - no alt text -->
<img src="chart.png" />

<!-- Good - alt text for decorative images -->
<img src="decoration.png" alt="" />

<!-- Good - long description for complex images -->
<img src="complex-chart.png" alt="Chart showing sales trends" />
<a href="/chart-description">View detailed chart description</a>
```

### 3. Provide Captions and Transcripts

```html
<!-- Good - captions for video -->
<video controls>
  <source src="video.mp4" type="video/mp4" />
  <track kind="captions" src="captions.vtt" srclang="en" label="English" />
</video>

<!-- Good - transcript for audio -->
<audio controls>
  <source src="audio.mp3" type="audio/mpeg" />
</audio>
<p><a href="/audio-transcript">Read transcript</a></p>
```

### 4. Design for Readability

```css
/* Good - readable font size */
body {
  font-size: 16px;
  line-height: 1.6;
}

/* Good - readable line length */
main {
  max-width: 65ch;
}

/* Good - sufficient whitespace */
section {
  padding: 2rem;
}

/* Bad - too small */
body {
  font-size: 12px;
  line-height: 1.2;
}
```

## How to Use This Skill with Claude Code

### Audit Accessibility

```
"I'm using the accessibility-excellence skill. Can you audit my product for accessibility?
- Check WCAG AA compliance
- Identify keyboard navigation issues
- Check screen reader compatibility
- Verify color contrast ratios
- Check for missing alt text
- Identify semantic HTML issues"
```

### Implement Accessibility

```
"Can you help me implement accessibility?
- Add semantic HTML
- Add ARIA labels and roles
- Implement keyboard navigation
- Ensure focus management
- Verify color contrast
- Add alt text to images"
```

### Create Accessibility Documentation

```
"Can you create accessibility documentation?
- WCAG AA checklist
- Keyboard navigation guide
- Screen reader testing guide
- Color contrast requirements
- Accessibility best practices"
```

### Test Accessibility

```
"Can you create an accessibility testing plan?
- Keyboard navigation testing
- Screen reader testing
- Color contrast verification
- Semantic HTML validation
- ARIA usage validation"
```

## Design Critique: Evaluating Accessibility

Claude Code can critique your accessibility:

```
"Can you evaluate my accessibility?
- Are my pages WCAG AA compliant?
- Is keyboard navigation working?
- Are my color contrasts sufficient?
- Is my semantic HTML correct?
- What's one thing I could improve immediately?"
```

## Integration with Other Skills

- **design-foundation** — Accessible tokens and design decisions
- **layout-system** — Accessible layouts and responsive design
- **typography-system** — Readable font sizes and line heights
- **color-system** — Sufficient contrast ratios
- **component-architecture** — Accessible components
- **interaction-design** — Accessible interactions

## Key Principles

**1. Accessibility is Inclusion**
Design for everyone, including people with disabilities.

**2. Semantic HTML is Foundation**
Use semantic HTML elements that describe their meaning.

**3. Keyboard Navigation is Essential**
All functionality must be available from the keyboard.

**4. Screen Readers Must Work**
Test with actual screen readers, not just automated tools.

**5. Contrast Matters**
Ensure sufficient contrast for readability.

## Checklist: Is Your Accessibility Ready?

- [ ] All pages are WCAG AA compliant
- [ ] Semantic HTML is used throughout
- [ ] Keyboard navigation works for all functionality
- [ ] Focus indicators are visible
- [ ] All images have descriptive alt text
- [ ] Form labels are associated with inputs
- [ ] Color contrast meets WCAG AA standards
- [ ] ARIA is used appropriately
- [ ] Screen reader testing has been done
- [ ] Videos have captions and transcripts
- [ ] Reduced motion preferences are respected
- [ ] Accessibility is tested regularly

Accessibility is not a feature—it's a fundamental requirement. Make it a priority.