Accessibility Skill Skill

Accessibility Skill

Atomic Skill: Ensure digital experiences are usable by everyone through WCAG compliance

Purpose

This skill provides comprehensive guidance on accessibility standards, testing, and remediation.

Skill Invocation

Skill("custom-plugin-ux-design:accessibility")

Parameter Schema

Input Parameters

interface AccessibilityParams {
  // Required
  task: "audit" | "remediate" | "design" | "test";
  target: string;

  // Optional
  level?: "A" | "AA" | "AAA";
  scope?: "component" | "page" | "flow" | "application";
  platform?: "web" | "mobile" | "desktop";
  assistive_tech?: string[];
}

Validation Rules

task:
  type: enum
  required: true
  values: [audit, remediate, design, test]

target:
  type: string
  required: true
  min_length: 3

level:
  type: enum
  default: "AA"
  values: [A, AA, AAA]

Execution Flow

ACCESSIBILITY EXECUTION
────────────────────────────────────────────

Step 1: SCOPE ASSESSMENT
├── Identify target scope
├── Determine compliance level
└── Select testing methods

Step 2: AUDIT
├── Automated testing
├── Manual testing
├── Assistive tech testing
└── Document findings

Step 3: CATEGORIZE ISSUES
├── Critical (blockers)
├── Serious (major barriers)
├── Moderate (difficulties)
└── Minor (inconveniences)

Step 4: REMEDIATE
├── Prioritize by severity
├── Implement fixes
├── Verify corrections
└── Document solutions

Step 5: VALIDATE
├── Re-test all issues
├── Certify compliance
└── Create maintenance plan

────────────────────────────────────────────

Retry Logic

retry_config:
  max_attempts: 3
  backoff_type: exponential
  initial_delay_ms: 500
  max_delay_ms: 5000
  retryable_errors:
    - SCANNER_TIMEOUT
    - AT_CONNECTION_LOST

Logging Hooks

interface AccessibilityLog {
  timestamp: string;
  event: "audit_start" | "issue_found" | "remediated" | "verified";
  wcag_criterion: string;
  severity: string;
  element: string;
  status: "open" | "fixed" | "verified";
}

Learning Modules

Module 1: WCAG Fundamentals

POUR PRINCIPLES
├── Perceivable
│   ├── Text alternatives
│   ├── Time-based media
│   ├── Adaptable content
│   └── Distinguishable
├── Operable
│   ├── Keyboard accessible
│   ├── Enough time
│   ├── Seizure safe
│   └── Navigable
├── Understandable
│   ├── Readable
│   ├── Predictable
│   └── Input assistance
└── Robust
    ├── Compatible
    └── Name, role, value

Module 2: Screen Reader Support

SCREEN READER BASICS
├── Semantic HTML
│   ├── Headings (h1-h6)
│   ├── Landmarks (nav, main, etc.)
│   ├── Lists (ul, ol, dl)
│   └── Tables (proper markup)
├── ARIA
│   ├── Roles
│   ├── States
│   └── Properties
├── Focus management
│   ├── Focus order
│   ├── Focus trapping
│   └── Focus restoration
└── Live regions
    ├── aria-live
    ├── Announcements
    └── Status updates

Module 3: Keyboard Navigation

KEYBOARD REQUIREMENTS
├── All interactive elements focusable
├── Logical focus order
├── Visible focus indicators
├── No keyboard traps
├── Skip links provided
└── Shortcuts documented

COMMON PATTERNS
├── Tab: Move forward
├── Shift+Tab: Move backward
├── Enter/Space: Activate
├── Arrow keys: Navigate within
├── Escape: Close/cancel
└── Home/End: First/last

Module 4: Visual Accessibility

COLOR & CONTRAST
├── Text contrast (4.5:1 normal, 3:1 large)
├── UI component contrast (3:1)
├── Focus indicator contrast (3:1)
├── Color not sole indicator
└── Dark mode considerations

MOTION & ANIMATION
├── Reduce motion preference
├── Pause/stop controls
├── No autoplay
├── Seizure-safe content
└── Animation alternatives

Module 5: Testing Methods

AUTOMATED TESTING
├── Axe DevTools
├── WAVE
├── Lighthouse
├── Pa11y
└── HTML validators

MANUAL TESTING
├── Keyboard-only navigation
├── Zoom to 200%
├── High contrast mode
├── Color blindness simulation
└── Form error states

ASSISTIVE TECH TESTING
├── NVDA (Windows)
├── JAWS (Windows)
├── VoiceOver (Mac/iOS)
├── TalkBack (Android)
└── Switch access

Error Handling

| Error Code | Description | Recovery | |------------|-------------|----------| | A11Y-001 | Missing alt text | Add descriptive alt | | A11Y-002 | Contrast failure | Adjust colors | | A11Y-003 | Keyboard trap | Add escape mechanism | | A11Y-004 | Missing label | Add visible/hidden label | | A11Y-005 | Invalid ARIA | Fix ARIA usage |

WCAG Quick Reference

Contrast Requirements

| Content Type | AA Ratio | AAA Ratio | |--------------|----------|-----------| | Normal text | 4.5:1 | 7:1 | | Large text (18pt+) | 3:1 | 4.5:1 | | UI components | 3:1 | 3:1 | | Focus indicators | 3:1 | 3:1 |

Touch Target Sizes

| Platform | Minimum | Recommended | |----------|---------|-------------| | Web | 24x24px | 44x44px | | iOS | 44x44pt | 44x44pt | | Android | 48x48dp | 48x48dp |

Troubleshooting

Problem: Screen reader announces wrong content

Diagnosis:
├── Check: ARIA labels
├── Check: DOM order
├── Check: Hidden content
└── Solution: Align ARIA with visual

Steps:
1. Test with screen reader
2. Check aria-label accuracy
3. Verify DOM = visual order
4. Remove incorrect aria-hidden

Problem: Focus not visible

Diagnosis:
├── Check: outline: none in CSS
├── Check: :focus styles
├── Check: Custom components
└── Solution: Add visible focus

Steps:
1. Remove outline removal
2. Add :focus-visible styles
3. Ensure 3:1 contrast
4. Test all interactive elements

Unit Test Templates

describe("AccessibilitySkill", () => {
  describe("audit", () => {
    it("should detect missing alt text", async () => {
      const result = await invoke({
        task: "audit",
        target: "<img src='photo.jpg'>"
      });
      expect(result.issues).toContainEqual(
        expect.objectContaining({ code: "A11Y-001" })
      );
    });
  });

  describe("contrast checking", () => {
    it("should calculate contrast ratio", async () => {
      const result = await invoke({
        task: "audit",
        target: { text: "#666666", background: "#ffffff" }
      });
      expect(result.contrast_ratio).toBeCloseTo(5.74, 1);
    });
  });

  describe("remediation", () => {
    it("should suggest fix for contrast failure", async () => {
      const result = await invoke({
        task: "remediate",
        target: { issue: "A11Y-002", colors: ["#999", "#fff"] }
      });
      expect(result.suggested_color).toMatch(/^#[0-9A-F]{6}$/i);
      expect(result.new_contrast).toBeGreaterThanOrEqual(4.5);
    });
  });
});

Quality Metrics

| Metric | Target | Measurement | |--------|--------|-------------| | WCAG compliance | > 95% | Criteria met | | Critical issues | 0 | Blockers found | | Keyboard navigable | 100% | All elements | | Screen reader compatible | > 95% | AT testing |

Version History

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2025-12-30 | Production-grade upgrade |

Agent Skills: Accessibility Skill

Skill Files