accessibility-remediation

What this skill does

# Accessibility Remediation Skill

## Overview

Automatically detect and fix accessibility issues in components with AI-powered analysis, context-aware fix suggestions, and one-click application. Goes beyond detection to provide ranked remediation options based on WCAG 2.2 best practices.

This skill transforms accessibility from a manual checklist into an automated workflow with intelligent fix suggestions.

## What This Skill Provides

### Real-Time Accessibility Analysis
Automatically check components for WCAG 2.2 violations:
- **Missing accessible names**: Buttons, links, form inputs
- **Color contrast**: WCAG AA (4.5:1) and AAA (7:1) compliance
- **Keyboard navigation**: Focus management, tab order
- **ARIA usage**: Proper roles, labels, live regions
- **Semantic HTML**: Use of proper HTML5 elements
- **Form accessibility**: Labels, error messages, validation

### Context-Aware Fix Suggestions
AI understands component purpose and suggests appropriate fixes:
- **Ranked by best practice**: Best → Good → Acceptable
- **Explains trade-offs**: Pros and cons of each approach
- **Considers context**: Close button vs Submit button vs generic action
- **Provides code**: Ready-to-apply fix snippets
- **Educational**: Explains why each fix works

### One-Click Application
Apply fixes instantly without manual implementation:
- **Auto-detection**: Triggers on component creation/edit
- **Interactive prompts**: Choose from ranked suggestions
- **Automatic application**: Updates component code
- **Verification**: Confirms fix resolves issue
- **Learning system**: Remembers user preferences

### WCAG 2.2 Compliance
Built-in support for latest accessibility standards:
- **Level A**: Essential accessibility (mandatory)
- **Level AA**: Recommended compliance (standard)
- **Level AAA**: Enhanced accessibility (optional)
- **ARIA 1.2**: Latest ARIA patterns and practices
- **Section 508**: US federal compliance

## How It Works

### Automatic Detection (PostToolUse Hook)

When you create or edit a component, the accessibility-auditor agent automatically:

1. **Parses component code** (JSX/TSX/Vue/Svelte)
2. **Analyzes for violations** using WCAG 2.2 rules
3. **Generates fix suggestions** ranked by best practice
4. **Presents options** for user selection
5. **Applies chosen fix** and verifies success

### Manual Invocation

You can also explicitly request accessibility analysis:

```bash
User: "Check this Button component for accessibility issues"
Claude: [Runs accessibility-auditor agent]

User: "Fix the accessibility violations in Modal.tsx"
Claude: [Analyzes, suggests fixes, applies selected fix]
```

## Common Accessibility Issues & Fixes

### Issue 1: Missing Accessible Name

**Problem:** Buttons, links, or inputs without labels

**Examples:**

```tsx
// ❌ Bad: Button has no accessible name
<button onClick={handleClose}>×</button>

// ✅ Fix Option 1: Visible text with icon (BEST)
<button onClick={handleClose}>
  <span aria-hidden="true">×</span>
  <span className="sr-only">Close dialog</span>
</button>

// ✅ Fix Option 2: aria-label (GOOD)
<button onClick={handleClose} aria-label="Close dialog">×</button>

// ✅ Fix Option 3: title attribute (ACCEPTABLE)
<button onClick={handleClose} title="Close dialog">×</button>
```

**AI Suggestion:**
```
Context: Close button in modal header
Recommendation: Option 1 (best for all users - visible + announced)
WCAG: 4.1.2 Name, Role, Value (Level A)
```

### Issue 2: Poor Color Contrast

**Problem:** Text/UI elements don't meet WCAG contrast ratios

**Examples:**

```tsx
// ❌ Bad: Contrast ratio 2.1:1 (fails WCAG AA)
<button style={{ color: '#999', background: '#fff' }}>Submit</button>

// ✅ Fix: Contrast ratio 4.6:1 (passes AA)
<button style={{ color: '#666', background: '#fff' }}>Submit</button>

// ✅ Better: Contrast ratio 7.2:1 (passes AAA)
<button style={{ color: '#333', background: '#fff' }}>Submit</button>
```

**AI Suggestion:**
```
Issue: Text color #999 on white background (2.1:1 - fails)
Required: 4.5:1 for normal text (WCAG AA)
Suggested colors:
  - #666 (4.6:1) ✓ WCAG AA
  - #555 (5.8:1) ✓ WCAG AA
  - #333 (7.2:1) ✓ WCAG AAA
WCAG: 1.4.3 Contrast (Minimum) (Level AA)
```

### Issue 3: Missing Form Labels

**Problem:** Form inputs without associated labels

**Examples:**

```tsx
// ❌ Bad: No label association
<input type="email" placeholder="Email" />

// ✅ Fix Option 1: Proper label element (BEST)
<label htmlFor="email">
  Email address
  <input id="email" type="email" placeholder="[email protected]" />
</label>

// ✅ Fix Option 2: Label with nesting (GOOD)
<label>
  Email address
  <input type="email" placeholder="[email protected]" />
</label>

// ✅ Fix Option 3: aria-label (ACCEPTABLE)
<input type="email" aria-label="Email address" placeholder="Email" />
```

**AI Suggestion:**
```
Context: Email input in login form
Recommendation: Option 1 (explicit label with htmlFor - most robust)
WCAG: 3.3.2 Labels or Instructions (Level A)
```

### Issue 4: Missing Focus Indicators

**Problem:** Interactive elements lack visible focus state

**Examples:**

```tsx
// ❌ Bad: Focus outline removed
<button style={{ outline: 'none' }} onClick={handleClick}>
  Click me
</button>

// ✅ Fix Option 1: Custom focus-visible (BEST)
<button
  className="focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
  onClick={handleClick}
>
  Click me
</button>

// ✅ Fix Option 2: Custom outline (GOOD)
<button
  style={{ outline: 'none' }}
  className="focus:outline-blue focus:outline-2 focus:outline-offset-2"
  onClick={handleClick}
>
  Click me
</button>

// ✅ Fix Option 3: Default outline (ACCEPTABLE)
<button onClick={handleClick}>Click me</button>
```

**AI Suggestion:**
```
Issue: outline: none removes focus indicator
Solution: Use :focus-visible for keyboard-only focus styling
WCAG: 2.4.7 Focus Visible (Level AA)
```

### Issue 5: Invalid ARIA Usage

**Problem:** Incorrect or redundant ARIA attributes

**Examples:**

```tsx
// ❌ Bad: Redundant role on button
<button role="button" onClick={handleClick}>Submit</button>

// ✅ Fix: Remove redundant role (native button already has role)
<button onClick={handleClick}>Submit</button>

// ❌ Bad: Invalid ARIA attribute
<div role="button" onClick={handleClick}>Click</div>

// ✅ Fix: Use semantic button element (BEST)
<button onClick={handleClick}>Click</button>

// ✅ Fix: Add keyboard support if div required (ACCEPTABLE)
<div
  role="button"
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
  tabIndex={0}
>
  Click
</div>
```

**AI Suggestion:**
```
Issue: Redundant role="button" on <button> element
Solution: Remove role attribute (native HTML provides this)
WCAG: 4.1.2 Name, Role, Value (Level A)
```

### Issue 6: Missing Alt Text

**Problem:** Images without alternative text

**Examples:**

```tsx
// ❌ Bad: No alt attribute
<img src="/avatar.jpg" />

// ✅ Fix Option 1: Descriptive alt (BEST - informative images)
<img src="/avatar.jpg" alt="Profile photo of John Doe" />

// ✅ Fix Option 2: Empty alt (GOOD - decorative images)
<img src="/decorative-pattern.png" alt="" aria-hidden="true" />

// ✅ Fix Option 3: aria-label (ACCEPTABLE - when alt insufficient)
<img
  src="/complex-chart.png"
  alt="Sales data visualization"
  aria-label="Bar chart showing 40% increase in Q4 sales"
/>
```

**AI Suggestion:**
```
Context: User avatar in profile card
Recommendation: Descriptive alt text with user name
WCAG: 1.1.1 Non-text Content (Level A)
```

## Workflow Example

### Scenario: Creating a Modal Component

```tsx
// User creates Modal component
export function Modal({ isOpen, onClose, children }) {
  if (!isOpen) return null;

  return (
    <div className="modal-overlay" onClick={onClose}>
      <div className="modal-content">
        <button onClick={onClose}>×</button>
        {children}
      </div>
    </div>
  );
}
```

**AI Detection (Automatic):**

```
❌ 4 accessibility issues detected in Modal.tsx

Issue 1: Missing accessible name (Line 7)
  Elem