---

name: wcag-compliance description: WCAG 2.2 AA accessibility compliance patterns for web applications. Use when auditing accessibility or implementing WCAG requirements. context: fork agent: accessibility-specialist version: 1.0.0 tags: [accessibility, wcag, a11y, aria, screen-reader, compliance] allowed-tools: [Read, Write, Grep, Glob, Bash] author: OrchestKit user-invocable: false

WCAG Compliance

Web Content Accessibility Guidelines 2.2 AA implementation for inclusive, legally compliant web applications.

Overview

• Building accessible UI components from scratch
• Auditing applications for ADA/Section 508 compliance
• Implementing keyboard navigation and focus management
• Supporting screen readers and assistive technologies
• Fixing color contrast and visual accessibility issues

Quick Reference

Semantic HTML Structure

Copy<main>
  <article>
    <header><h1>Page Title</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
      <ul><li>Feature 1</li></ul>
    </section>
    <aside aria-label="Related content">...</aside>
  </article>
</main>

ARIA Labels and States

Copy// Icon-only button
<button aria-label="Save document">
  <svg aria-hidden="true">...</svg>
</button>

// Form field with error
<input
  id="email"
  aria-required="true"
  aria-invalid={!!error}
  aria-describedby={error ? "email-error" : "email-hint"}
/>
{error && <p id="email-error" role="alert">{error}</p>}

Color Contrast (CSS)

Copy:root {
  --text-primary: #1a1a1a;   /* 16.1:1 on white - normal text */
  --text-secondary: #595959; /* 7.0:1 on white - secondary */
  --focus-ring: #0052cc;     /* 7.3:1 - focus indicator */
}
:focus-visible {
  outline: 3px solid var(--focus-ring);
  outline-offset: 2px;
}

WCAG 2.2 AA Checklist

Key Decisions

Anti-Patterns (FORBIDDEN)

• Div soup: Using <div> instead of semantic elements (<nav>, <main>, <article>)
• Color-only information: Status indicated only by color without icon/text
• Missing labels: Form inputs without associated <label> or aria-label
• Keyboard traps: Focus that cannot escape without mouse
• Auto-playing media: Audio/video that plays without user action
• Removing focus outline: outline: none without replacement indicator
• Positive tabindex: Using tabindex > 0 (disrupts natural order)
• Empty links/buttons: Interactive elements without accessible names
• ARIA overuse: Using ARIA when semantic HTML suffices

Related Skills

• a11y-testing - Automated accessibility testing with axe-core and Playwright
• design-system-starter - Accessible component library patterns
• i18n-date-patterns - RTL layout and locale-aware formatting
• motion-animation-patterns - Reduced motion and animation accessibility

Capability Details

semantic-html

Keywords: semantic, landmark, heading, structure, html5, main, nav, article Solves:

• Proper document structure with landmarks
• Heading hierarchy (h1-h6 in order)
• Form fieldsets and legends
• Lists for grouped content

aria-patterns

Keywords: aria, role, state, property, live-region, alert, status Solves:

• Custom widget accessibility (tabs, menus, dialogs)
• Dynamic content announcements
• Expanded/collapsed states
• Error/validation messaging

focus-management

Keywords: keyboard, focus, tab, trap, modal, skip-link, roving Solves:

• Modal focus trapping
• Skip links for navigation
• Roving tabindex for widgets
• Focus restoration after dialogs

color-contrast

Keywords: contrast, color, wcag, perceivable, vision, ratio Solves:

• Text contrast ratios (4.5:1 / 3:1)
• UI component contrast (3:1)
• Focus indicator visibility
• Non-color status indicators