accessibility

skill:accessibility - WCAG 2.1 AA Compliance

Version: 1.0.0

Purpose

Build accessible websites that meet WCAG 2.1 AA standards. This skill audits existing code and generates accessible patterns for semantic HTML, ARIA attributes, focus management, keyboard navigation, color contrast, form labeling, and live regions. Use when building new UI components, auditing existing pages for compliance, or fixing accessibility issues reported by automated tools or manual testing.

File Structure

skills/accessibility/ ├── SKILL.md (this file) └── examples.md

Interface References

Context: Loaded via ContextProvider Interface
Memory: Accessed via MemoryStore Interface
Shared Patterns: Shared Loading Patterns
Schemas: Validated against context_metadata.schema.json and memory_entry.schema.json

Accessibility Focus Areas

This skill evaluates 8 critical dimensions of web accessibility:

Semantic HTML: Correct element usage (<nav> , <main> , <article> , <aside> , <header> , <footer> , <section> ), heading hierarchy, landmark regions
ARIA Attributes: Roles, states, and properties applied correctly — never overriding native semantics
Keyboard Navigation: All interactive elements reachable via Tab, operable via Enter/Space, escape closes modals, arrow keys for composite widgets
Focus Management: Visible focus indicators, focus trapping in modals, focus restoration on close, skip links
Color Contrast: Minimum 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+), 3:1 for UI components and graphical objects
Form Accessibility: Visible labels associated via for /id or wrapping <label> , error messages linked via aria-describedby , required fields indicated
Dynamic Content: Live regions (aria-live ), status messages, loading states announced to screen readers
Media Accessibility: Alt text for images, captions for video, transcripts for audio, no autoplay with sound

Note: Focus on issues that affect real users with disabilities. Automated tools catch ~30% of issues — this skill provides the manual judgment layer.

MANDATORY WORKFLOW (MUST FOLLOW EXACTLY)

Step 1: Initial Analysis

YOU MUST:

Determine the scope of the accessibility review or implementation:
Single component, page, or full application
New build vs. audit of existing code
Specific WCAG criteria to target (default: all AA criteria)
Identify the technology stack (React, Vue, plain HTML, etc.)
Detect any existing accessibility tooling (eslint-plugin-jsx-a11y, axe-core, pa11y, Lighthouse)
Ask clarifying questions:
What assistive technologies must be supported? (Screen readers: NVDA, JAWS, VoiceOver)
Are there specific WCAG criteria the team has been cited for?
What is the target compliance level? (A, AA, or AAA)

DO NOT PROCEED WITHOUT A CLEAR SCOPE

Step 2: Load Memory

Follow Standard Memory Loading with skill="accessibility" and domain="engineering" .

YOU MUST:

Use memoryStore.getSkillMemory("accessibility", "{project-name}") to load project-specific patterns
Use memoryStore.getByProject("{project-name}") for cross-skill insights (component patterns, design tokens)
If memory exists: Review previously documented component patterns, known exceptions, and remediation history
If no memory exists: Note this is the first accessibility pass

Step 3: Load Context

Follow Standard Context Loading for the engineering domain. Stay within the file budget declared in frontmatter.

YOU MUST:

Use contextProvider.getDomainIndex("engineering") for general engineering context
Load framework-specific accessibility patterns if detected (React, Angular, Vue)
Reference WCAG 2.1 criteria directly when citing issues

Step 4: Audit or Implement Accessible Patterns

YOU MUST evaluate ALL categories below:

Semantic Structure:

Heading hierarchy is logical and sequential (no skipped levels)
Landmark regions present: <main> , <nav> , <header> , <footer>
Lists use <ul> /<ol> /<dl> — not styled <div> sequences
Tables use <th> , scope , and <caption> for data tables
No <div> or <span> used where a semantic element exists

ARIA Correctness:

No ARIA role duplicates native HTML semantics (<button role="button"> is redundant)
Required ARIA attributes present for custom widgets (e.g., aria-expanded for accordions)
aria-label or aria-labelledby on elements without visible text
aria-hidden="true" not applied to focusable elements

Keyboard & Focus:

All interactive elements in tab order (no positive tabindex values)
Custom components handle Enter, Space, Escape, Arrow keys appropriately
Focus indicator visible and meets 3:1 contrast ratio
Modal dialogs trap focus and restore on close
Skip-to-content link present as first focusable element

Color & Contrast:

Text contrast meets 4.5:1 (normal) or 3:1 (large text)
Information not conveyed by color alone (use icons, patterns, or text)
Focus indicators meet 3:1 contrast against adjacent colors
Disabled states still visually distinguishable

Forms:

Every input has an associated <label> (visible, not aria-label only unless justified)
Error messages use aria-describedby to link to input
Required fields use aria-required="true" and visual indicator
Form validation errors announced via aria-live="assertive" or focus management

Dynamic Content:

Loading states use aria-live="polite" or role="status"
Error alerts use aria-live="assertive" or role="alert"
Route changes in SPAs manage focus (move to main content or <h1> )
Toast notifications use role="status" with aria-live="polite"

DO NOT SKIP ANY CATEGORY

Step 5: Generate Output

YOU MUST ask the user for preferred output format:

Option A: Structured audit report with findings, WCAG criteria references, and remediation code
Option B: Inline code patches with accessible implementations
Option C (Default): Both audit report and code patches

For EVERY finding, YOU MUST provide:

Severity: Critical / Important / Minor
WCAG Criterion: Specific criterion (e.g., 1.4.3 Contrast, 2.1.1 Keyboard, 4.1.2 Name Role Value)
Description: What is wrong and who it affects
Fix: Concrete code with the accessible implementation
Testing: How to verify the fix (screen reader, keyboard, automated tool)
File:line: Exact location

Output to /claudedocs/accessibility_{project}_{YYYY-MM-DD}.md

Step 6: Update Memory

Follow Standard Memory Update for skill="accessibility" .

Use memoryStore.update("accessibility", "{project-name}", ...) to store:

project_overview.md: Framework, component library, a11y tooling, compliance target
common_patterns.md: Project-specific accessible component patterns discovered
known_issues.md: Documented exceptions, accepted limitations, and remediation timeline
audit_history.md: Summary of audits performed with dates and key findings

Compliance Checklist

Before completing, verify:

Step 1: Scope, stack, and compliance target identified
Step 2: Standard Memory Loading pattern followed
Step 3: Standard Context Loading pattern followed
Step 4: All accessibility categories audited/implemented
Step 5: Output saved with standard naming convention, all findings include WCAG criterion
Step 6: Standard Memory Update pattern followed

FAILURE TO COMPLETE ALL STEPS INVALIDATES THE REVIEW

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

office

responsive-images

jquery-4

angular-architect