Skip to main content
skill CX Codex

Accessibility Engineer — Claude Code skill: what it does

The Accessibility Engineer skill guides accessible UI implementation and audits against WCAG 2.1 AA. Use it while building interfaces or reviewing their accessibility.

MIT 181 installs ★ 39 updated 2025-12-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daffy0208/ai-dev-standards --skill accessibility-engineer -a claude-code
Open on GitHub

What Accessibility Engineer does

The skill covers semantic HTML, heading structure, page landmarks and keyboard access. It also explains focus handling in modal dialogs and links that let keyboard users bypass navigation. The examples show why native buttons are preferable to clickable div elements.

Other sections address ARIA and forms, including labels, required fields and errors associated with their inputs. The guidance is to use ARIA when semantic HTML does not provide what a custom widget needs; adding role="button" to a native button is shown as unnecessary.

Its stated target is WCAG 2.1 AA. Treat that as the skill’s implementation goal, not as evidence that it runs an automated audit or certifies a project.

What it helps with

  • structure page headings and landmarks semantically
  • make interactive controls usable with a keyboard
  • manage focus when a modal opens
  • connect form inputs to labels and error messages
  • choose ARIA attributes for dynamic interface content

Example prompts for the agent

  • Review this interface against WCAG 2.1 AA and suggest code changes.
  • Make this modal work for keyboard users and manage focus when it opens.
  • Check whether each form field has a label and an associated error message.

How to install Accessibility Engineer

1Skills CLI (Vercel)

npx skills add daffy0208/ai-dev-standards --skill accessibility-engineer -a claude-code

2Manually: put the files in place

~/.claude/skills/accessibility-engineer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/accessibility-engineer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about Accessibility Engineer

How do I install Accessibility Engineer in Claude Code?

Run npx skills add daffy0208/ai-dev-standards --skill accessibility-engineer -a claude-code. The skill file is installed at ~/.claude/skills/accessibility-engineer/SKILL.md.

What does Accessibility Engineer do?

It provides implementation guidance for accessible markup, keyboard navigation, ARIA and forms. Its stated target is WCAG 2.1 AA.

When should I use ARIA according to the skill?

Use ARIA when native semantic HTML cannot express what a custom widget needs. The examples use role="tab", aria-selected and aria-controls for a tab.

Source text

SKILL.md · MIT
---
name: Accessibility Engineer
description: Implement accessibility (a11y) best practices to make applications usable by everyone. Use when building UIs, conducting accessibility audits, or ensuring WCAG compliance. Covers screen readers, keyboard navigation, ARIA attributes, and inclusive design patterns.
version: 1.0.0
---

# Accessibility Engineer

Build for everyone - accessibility is not optional.

## Core Principle

**Accessibility is a civil right, not a feature.**

1 in 4 adults in the US has a disability. Accessible design benefits everyone:

- Blind users (screen readers)
- Low vision users (zoom, high contrast)
- Deaf users (captions)
- Motor disabilities (keyboard-only)
- Cognitive disabilities (clear language)
- Temporary disabilities (broken arm)
- Situational limitations (bright sunlight, noisy environment)

## WCAG Compliance Levels

**Level A:** Minimum (legal requirement)
**Level AA:** Industry standard (aim for this)
**Level AAA:** Gold standard (difficult to achieve for all content)

**Target: WCAG 2.1 AA compliance**

---

## Pillar 1: Semantic HTML

### Use the Right Elements

```jsx
// ❌ Bad: Divs for everything (no semantic meaning)
<div onClick={handleClick}>Click me</div>
<div>Menu</div>

// ✅ Good: Semantic HTML
<button onClick={handleClick}>Click me</button>
<nav>Menu</nav>
```

### Document Structure

```jsx
// ✅ Proper heading hierarchy
<h1>Page Title</h1>
  <h2>Section 1</h2>
    <h3>Subsection 1.1</h3>
  <h2>Section 2</h2>

// ❌ Bad: Skipping levels
<h1>Page Title</h1>
  <h4>Section 1</h4> // Skipped h2, h3
```

### Landmarks

```jsx
<header>
  <nav aria-label="Main navigation">
    {/* Navigation links */}
  </nav>
</header>

<main>
  <article>
    {/* Main content */}
  </article>

  <aside>
    {/* Sidebar */}
  </aside>
</main>

<footer>
  {/* Footer content */}
</footer>
```

---

## Pillar 2: Keyboard Navigation

### All Interactive Elements Must Be Keyboard Accessible

```jsx
// ✅ Button is keyboard accessible by default
<button onClick={handleClick}>Click me</button>

// ❌ Div requires extra work
<div onClick={handleClick}>Click me</div> // Can't tab to it!

// ✅ If you must use div, add keyboard support
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick()
    }
  }}
>
  Click me
</div>
```

### Tab Order

```jsx
// ✅ Natural tab order (follows DOM order)
<input />
<button>Submit</button>
<a href="/help">Help</a>

// ❌ Don't use tabIndex > 0 (breaks natural order)
<button tabIndex={5}>Button</button> // Anti-pattern!

// ✅ tabIndex=-1 to remove from tab order
<div tabIndex={-1}>Not keyboard focusable</div>
```

### Focus Management

```jsx
// Modal: Trap focus inside
function Modal({ isOpen, onClose, children }) {
  const modalRef = useRef()

  useEffect(() => {
    if (!isOpen) return

    // Focus first focusable element
    const firstFocusable = modalRef.current.querySelector('button, input, a')
    firstFocusable?.focus()

    // Trap focus
    function handleTab(e) {
      if (e.key !== 'Tab') return

      const focusableElements = modalRef.current.querySelectorAll(
        'button, input, a, [tabindex]:not([tabindex="-1"])'
      )

      const first = focusableElements[0]
      const last = focusableElements[focusableElements.length - 1]

      if (e.shiftKey) {
        if (document.activeElement === first) {
          last.focus()
          e.preventDefault()
        }
      } else {
        if (document.activeElement === last) {
          first.focus()
          e.preventDefault()
        }
      }
    }

    document.addEventListener('keydown', handleTab)
    return () => document.removeEventListener('keydown', handleTab)
  }, [isOpen])

  return isOpen ? (
    <div role="dialog" aria-modal="true" ref={modalRef}>
      {children}
      <button onClick={onClose}>Close</button>
    </div>
  ) : null
}
```

### Skip Links

```jsx
// Allow keyboard users to skip navigation
<a href="#main-content" className="skip-link">
  Skip to main content
</a>

<nav>{/* Navigation */}</nav>

<main id="main-content">
  {/* Main content */}
</main>

// CSS
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px;
}

.skip-link:focus {
  top: 0;
}
```

---

## Pillar 3: ARIA Attributes

### Only Use ARIA When Semantic HTML Isn't Enough

```jsx
// ✅ Semantic HTML (no ARIA needed)
<button>Click me</button>

// ❌ Unnecessary ARIA
<button role="button" aria-label="Click me">Click me</button>

// ✅ ARIA needed (custom widget)
<div role="tab" aria-selected={isActive} aria-controls="panel-1">
  Tab 1
</div>
```

### Common ARIA Attributes

**aria-label** - Provides accessible name:

```jsx
<button aria-label="Close dialog">
  <XIcon /> {/* Visual only */}
</button>

<input type="search" aria-label="Search products" />
```

**aria-labelledby** - References another element:

```jsx
<h2 id="dialog-title">Delete Account</h2>
<div role="dialog" aria-labelledby="dialog-title">
  {/* Dialog content */}
</div>
```

**aria-describedby** - Additional description:

```jsx
<input
  type="password"
  aria-describedby="password-requirements"
/>
<div id="password-requirements">
  Must be at least 8 characters
</div>
```

**aria-live** - Announce dynamic content:

```jsx
// Polite: Wait for user to finish
<div aria-live="polite">
  {itemsAddedToCart} items added to cart
</div>

// Assertive: Interrupt immediately (use sparingly)
<div aria-live="assertive" role="alert">
  Error: Payment failed
</div>
```

**aria-expanded** - Collapsible content:

```jsx
<button
  aria-expanded={isOpen}
  aria-controls="dropdown-menu"
  onClick={() => setIsOpen(!isOpen)}
>
  Menu
</button>

<div id="dropdown-menu" hidden={!isOpen}>
  {/* Menu items */}
</div>
```

**aria-hidden** - Hide from screen readers:

```jsx
// Decorative icons
<span aria-hidden="true">★</span>

// Don't hide interactive elements!
// ❌ Bad
<button aria-hidden="true">Click me</button>
```

---

## Pillar 4: Forms & Inputs

### Labels

```jsx
// ✅ Good: Explicit label
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// ✅ Good: Implicit label
<label>
  Email
  <input type="email" />
</label>

// ❌ Bad: No label (placeholder is not a label!)
<input type="email" placeholder="Email" />
```

### Error Messages

```jsx
function EmailInput({ error }) {
  const errorId = 'email-error'

  return (
    <>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
      />
      {error && (
        <div id={errorId} role="alert">
          {error}
        </div>
      )}
    </>
  )
}
```

### Required Fields

```jsx
<label htmlFor="name">
  Name <span aria-label="required">*</span>
</label>
<input id="name" type="text" required aria-required="true" />
```

---

## Pillar 5: Color & Contrast

### Minimum Contrast Ratios (WCAG AA)

- Normal text (< 18pt): 4.5:1
- Large text (≥ 18pt or 14pt bold): 3:1
- UI components: 3:1

```jsx
// ❌ Bad: Insufficient contrast
<button style={{ background: '#ddd', color: '#aaa' }}>
  Submit // 1.5:1 contrast - fails!
</button>

// ✅ Good: Sufficient contrast
<button style={{ background: '#0066cc', color: '#ffffff' }}>
  Submit // 8:1 contrast - passes!
</button>
```

### Don't Use Color Alone

```jsx
// ❌ Bad: Color only
<span style={{ color: 'red' }}>Error</span>
<span style={{ color: 'green' }}>Success</span>

// ✅ Good: Color + icon/text
<span style={{ color: 'red' }}>
  <ErrorIcon aria-hidden="true" />
  Error
</span>
```

---

## Pillar 6: Images & Media

### Alt Text

```jsx
// ✅ Informative images
<img src="chart.png" alt="Sales increased 50% in Q4" />

// ✅ Decorative images
<img src="decorative-border.png" alt="" /> // Empty alt

// ❌ Bad: No alt or redundant alt
<img src="photo.jpg" /> // Missing alt
<img src="photo.jpg" alt="Photo" /> // Useless
```

### Complex Images

```jsx
<figure>
  <img src="complex-chart.png" alt="Sales data for 2024" />
  <figcaption>
    <details>
      <summary>Detailed description</summary>
      <p>Q1: $100k, Q2: $150k, Q3: $180k, Q4: $220k. Shows 50% growth year-over-year.</p>
    </details>
  </figcaption>
</figure>
```

### Video Captions

```jsx
<video controls>
  <source src="video.mp4" type="video/mp4" />
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default />
</video>
```

---

## Pillar 7: Testing

### Automated Testing

```bash
# Lighthouse accessibility audit
lighthouse https://example.com --only-categories=accessibility

# axe-core (Jest)
npm install --save-dev @axe-core/react jest-axe
```

```typescript
// Test with jest-axe
import { axe, toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

it('has no accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>)
  const results = await axe(container)

  expect(results).toHaveNoViolations()
})
```

### Manual Testing

**Keyboard Navigation:**

- Tab through entire page
- Enter/Space to activate buttons
- Arrow keys for radio groups
- Esc to close modals

**Screen Reader Testing:**

- **NVDA** (Windows, free)
- **JAWS** (Windows, paid)
- **VoiceOver** (Mac, built-in)

**Screen Reader Shortcuts:**

- Navigate by headings: H (next), Shift+H (previous)
- Navigate by landmarks: D (next), Shift+D (previous)
- List all links: Insert+F7 (NVDA)

---

## Common Patterns

### Accessible Button

```jsx
<button
  type="button"
  onClick={handleClick}
  disabled={isDisabled}
  aria-busy={isLoading}
  aria-label={ariaLabel}
>
  {children}
</button>
```

### Accessible Modal

```jsx
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-description"
>
  <h2 id="dialog-title">Dialog Title</h2>
  <p id="dialog-description">Dialog description</p>

  <button onClick={onClose}>Close</button>
</div>
```

### Accessible Tabs

```jsx
<div>
  <div role="tablist">
    <button
      role="tab"
      aria-selected={activeTab === 'tab1'}
      aria-controls="panel1"
      onClick={() => setActiveTab('tab1')}
    >
      Tab 1
    </button>
    <button
      role="tab"
      aria-selected={activeTab === 'tab2'}
      aria-controls="panel2"
      onClick={() => setActiveTab('tab2')}
    >
      Tab 2
    </button>
  </div>

  <div id="panel1" role="tabpanel" hidden={activeTab !== 'tab1'}>
    Panel 1 content
  </div>

  <div id="panel2" role="tabpanel" hidden={activeTab !== 'tab2'}>
    Panel 2 content
  </div>
</div>
```

---

## Accessibility Checklist

### Semantic HTML

- [ ] Proper heading hierarchy (h1 → h2 → h3)
- [ ] Semantic landmarks (header, nav, main, footer)
- [ ] Lists use ul/ol/li
- [ ] Buttons for actions, links for navigation

### Keyboard

- [ ] All interactive elements keyboard accessible
- [ ] Visible focus indicators
- [ ] Logical tab order
- [ ] Skip links provided
- [ ] No keyboard traps

### ARIA

- [ ] Semantic HTML used first (ARIA only when needed)
- [ ] All interactive widgets have roles
- [ ] Dynamic content has aria-live
- [ ] Forms have proper labels and descriptions

### Color & Contrast

- [ ] Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large)
- [ ] Don't use color alone to convey info
- [ ] Focus indicators visible

### Images & Media

- [ ] All images have alt text
- [ ] Decorative images have empty alt
- [ ] Videos have captions
- [ ] Audio has transcripts

### Forms

- [ ] All inputs have labels
- [ ] Error messages associated with inputs
- [ ] Required fields indicated

### Testing

- [ ] Keyboard navigation tested
- [ ] Screen reader tested
- [ ] Automated tools run (axe, Lighthouse)
- [ ] Color blindness simulation tested

---

## Tools

- **axe DevTools** - Browser extension
- **Lighthouse** - Built into Chrome DevTools
- **WAVE** - Web accessibility evaluation tool
- **Color Contrast Analyzer** - Desktop app
- **NVDA** - Free screen reader (Windows)
- **VoiceOver** - Built-in screen reader (Mac)

---

## Related Resources

**Skills:**

- `ux-designer` - Accessible design patterns
- `frontend-builder` - Accessible React components
- `testing-strategist` - Accessibility testing

**External:**

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [MDN Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
- [A11y Project](https://www.a11yproject.com/)
- [WebAIM](https://webaim.org/)

---

**Build for everyone.** ♿

© daffy0208 · MIT · daffy0208/ai-dev-standards

Similar skills

All skills for Frontend and UI →

From the same set63

The whole set →
RAG Implementer RAG Implementer — a skill that walks the agent through eight phases of a RAG build, from knowledge-base design to retrieval, after checking that RAG is the right call. CX Codex +1 189installs usability-tester usability-tester designs observational usability studies, crafts task scenarios without leading instructions, and scores UX issue severity. CX Codex +1 188installs Supabase Developer Supabase Developer guides full-stack Supabase setup: PostgreSQL schemas with RLS, auth flows, storage buckets, and Edge Functions. CX Codex +1 187installs voice-interface-builder voice-interface-builder is a Claude Code skill for adding speech recognition, voice commands, and spoken output to web interfaces. It comes into play when building voice controls or accessibility features. CX Codex +1 187installs forensic-data-engineer forensic-data-engineer turns your agent into a data-forensics pair: audit trails, odd transaction patterns, fraud signals, breach root cause. Handy when you have to explain what changed and who did it. CX Codex +1 181installs data-engineer data-engineer guides agents in designing data pipelines, batch or streaming ETL workflows, and analytics aggregation logic. CX Codex +1 181installs pricing-strategist pricing-strategist gives an agent a working framework for SaaS pricing: the value metric, tier structure, feature packaging and price tests. CX Codex +1 180installs Testing Strategist Testing Strategist — a skill for planning test coverage on the 70/20/10 pyramid, with worked Jest and React Testing Library examples for units, integration and E2E. CX Codex +1 176installs

Project sponsors

Companies that keep this analytics open