Accessibility Skill

WCAG 2.2 compliance and ARIA implementation for inclusive, accessible web experiences.

🎯 Purpose

Provide atomic, single-responsibility operations for:

• WCAG 2.2 Level A/AA/AAA auditing
• ARIA roles, states, and properties
• Keyboard navigation patterns
• Screen reader optimization
• Focus management
• Color contrast verification

📥 Input Schema

interface AccessibilityInput {
  operation: 'audit' | 'fix' | 'pattern' | 'explain';
  audit_level: 'A' | 'AA' | 'AAA';
  markup?: string;
  component_type?: ComponentType;
  context?: {
    user_agents: string[];     // Target screen readers
    focus_management: boolean;
    color_scheme: 'light' | 'dark' | 'both';
  };
}

type ComponentType =
  | 'interactive'   // Buttons, links, controls
  | 'form'          // Form elements
  | 'navigation'    // Menus, breadcrumbs
  | 'media'         // Images, video, audio
  | 'content'       // Text, headings, lists
  | 'widget';       // Custom components

📤 Output Schema

interface AccessibilityOutput {
  success: boolean;
  wcag_level: 'A' | 'AA' | 'AAA';
  score: number;              // 0-100
  issues: A11yIssue[];
  fixes: A11yFix[];
  passed_criteria: string[];
  failed_criteria: string[];
}

interface A11yIssue {
  criterion: string;          // e.g., "1.4.3"
  level: 'A' | 'AA' | 'AAA';
  impact: 'critical' | 'serious' | 'moderate' | 'minor';
  element: string;
  message: string;
  fix: string;
}

🛠️ WCAG 2.2 Quick Reference

The Four Principles (POUR)

┌─────────────────────────────────────────────────────────────┐
│                        WCAG POUR                             │
├────────────────┬────────────────┬────────────────┬──────────┤
│   PERCEIVABLE  │   OPERABLE     │ UNDERSTANDABLE │  ROBUST  │
├────────────────┼────────────────┼────────────────┼──────────┤
│ Text alt       │ Keyboard       │ Readable       │ Compatible│
│ Captions       │ Enough time    │ Predictable    │ Parsing  │
│ Adaptable      │ Seizures       │ Input assist   │          │
│ Distinguishable│ Navigable      │                │          │
│                │ Input modality │                │          │
└────────────────┴────────────────┴────────────────┴──────────┘

WCAG 2.2 New Success Criteria (AA)

🎨 ARIA Patterns

1. Interactive Widgets

Button

<!-- Native button (preferred) -->
<button type="button">Click me</button>

<!-- Custom button (when native not possible) -->
<div role="button"
     tabindex="0"
     aria-pressed="false"
     onkeydown="handleKeydown(event)">
  Toggle
</div>

Dialog (Modal)

<div role="dialog"
     aria-modal="true"
     aria-labelledby="dialog-title"
     aria-describedby="dialog-desc">
  <h2 id="dialog-title">Confirm Action</h2>
  <p id="dialog-desc">Are you sure you want to proceed?</p>
  <button>Cancel</button>
  <button>Confirm</button>
</div>

Tabs

<div role="tablist" aria-label="Settings">
  <button role="tab"
          aria-selected="true"
          aria-controls="panel-1"
          id="tab-1">
    General
  </button>
  <button role="tab"
          aria-selected="false"
          aria-controls="panel-2"
          id="tab-2"
          tabindex="-1">
    Privacy
  </button>
</div>

<div role="tabpanel"
     id="panel-1"
     aria-labelledby="tab-1">
  General settings content...
</div>

<div role="tabpanel"
     id="panel-2"
     aria-labelledby="tab-2"
     hidden>
  Privacy settings content...
</div>

2. Live Regions

<!-- Polite announcement (waits for pause) -->
<div aria-live="polite" aria-atomic="true">
  3 items in cart
</div>

<!-- Assertive announcement (interrupts) -->
<div role="alert" aria-live="assertive">
  Error: Please fix the form errors
</div>

<!-- Status message -->
<div role="status" aria-live="polite">
  File uploaded successfully
</div>

3. Form Patterns

<form>
  <!-- Required field -->
  <label for="email">Email (required)</label>
  <input type="email"
         id="email"
         name="email"
         required
         aria-required="true"
         aria-describedby="email-hint email-error">
  <p id="email-hint">We'll never share your email</p>
  <p id="email-error" role="alert" aria-live="polite"></p>

  <!-- Field with error -->
  <label for="password">Password</label>
  <input type="password"
         id="password"
         aria-invalid="true"
         aria-errormessage="pwd-error">
  <p id="pwd-error" role="alert">
    Password must be at least 8 characters
  </p>

  <!-- Checkbox group -->
  <fieldset>
    <legend>Notifications</legend>
    <label>
      <input type="checkbox" name="notify" value="email">
      Email
    </label>
    <label>
      <input type="checkbox" name="notify" value="sms">
      SMS
    </label>
  </fieldset>
</form>

⚠️ Error Handling

Error Codes

Impact Levels

🔍 Troubleshooting

Problem: Screen reader not announcing content

Debug Checklist:
□ Element has accessible name?
□ ARIA role correct?
□ aria-hidden not incorrectly set?
□ Content not CSS display:none?
□ Live region set up correctly?

Problem: Keyboard navigation broken

Debug Checklist:
□ All interactive elements focusable?
□ Tab order logical?
□ No keyboard traps?
□ Focus visible?
□ Custom widgets have key handlers?
□ Arrow key navigation for widgets?

Problem: Form not accessible

Debug Checklist:
□ All inputs have labels?
□ Required fields marked?
□ Errors announced via live region?
□ Error linked with aria-errormessage?
□ Fieldsets for groups?
□ Autocomplete attributes set?

Keyboard Navigation Patterns

📊 Audit Scoring

Score Interpretation:

• 90-100: Excellent (WCAG AA likely compliant)
• 70-89: Good (some issues to address)
• 50-69: Moderate (significant work needed)
• <50: Poor (major accessibility barriers)

📋 Usage Examples

# Audit markup for WCAG AA
skill: accessibility
operation: audit
audit_level: "AA"
markup: "<form>...</form>"

# Get accessible pattern
skill: accessibility
operation: pattern
component_type: widget
context:
  user_agents: ["NVDA", "VoiceOver"]

# Fix accessibility issues
skill: accessibility
operation: fix
audit_level: "AA"
markup: "<img src='photo.jpg'>"
output_format: both

🔗 References

• WCAG 2.2 Quick Reference
• ARIA Authoring Practices Guide
• WebAIM Checklist
• Deque axe Rules