Accessibility Checker Skill

This skill ensures all HTML content meets WCAG2AA accessibility standards.

Quick Reference

Element	Requirement
Images	Must have `alt` attribute
Form inputs	Must have associated `<label>`
Links	Must have descriptive text (not "click here")
Navigation	Use `<nav>` with `aria-label`
Main content	Use `<main>` with `id` for skip link
Headings	Follow hierarchy (h1 → h2 → h3)
Tables	Use `<th scope="col/row">`

Forms (MUST follow)

Every input MUST have a label:

<!-- Method 1: for/id association -->
<label for="email">Email Address</label>
<input type="email" id="email" name="email"/>

<!-- Method 2: wrapping -->
<label>
  Email Address
  <input type="email" name="email"/>
</label>

Use fieldset for related inputs:

<fieldset>
  <legend>Shipping Address</legend>
  <label for="street">Street</label>
  <input type="text" id="street" name="street"/>
  <label for="city">City</label>
  <input type="text" id="city" name="city"/>
</fieldset>

Images (MUST follow)

All images MUST have alt text:

<!-- Informative image -->
<img src="chart.png" alt="Sales increased 20% in Q4"/>

<!-- Decorative image (empty alt) -->
<img src="decoration.png" alt=""/>

<!-- Complex image (use figure) -->
<figure>
  <img src="diagram.png" alt="System architecture diagram"/>
  <figcaption>Figure 1: Three-tier architecture with load balancer</figcaption>
</figure>

Navigation (MUST follow)

Provide skip links and landmarks:

<body>
  <a href="#main" class="skip-link">Skip to main content</a>

  <nav aria-label="Main navigation">
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>

  <main id="main">
    <!-- Content -->
  </main>
</body>

Links (MUST follow)

Links need descriptive, unique text:

<!-- Bad -->
<a href="/products">Click here</a>
<a href="/docs">Read more</a>

<!-- Good -->
<a href="/products">View all products</a>
<a href="/docs">Read the documentation</a>

Headings

Follow logical hierarchy:

<h1>Page Title</h1>
  <h2>Section One</h2>
    <h3>Subsection</h3>
  <h2>Section Two</h2>

Never skip levels (h1 → h3 is wrong).

WCAG AAA Enhanced Accessibility (Optional)

WCAG AAA provides enhanced accessibility beyond the AA baseline. Use when targeting users with more significant accessibility needs.

Contrast Requirements

Level	Normal Text	Large Text
AA (default)	4.5:1	3:1
AAA (enhanced)	7:1	4.5:1

Large text is 18pt+ (24px) or 14pt+ bold (18.5px).

Enabling AAA in pa11y

Edit .pa11yci to use AAA standard:

{
  "defaults": {
    "standard": "WCAG2AAA",
    "timeout": 30000,
    "wait": 1000
  }
}

AAA-Specific Requirements

Requirement	AAA Criterion
7:1 contrast ratio	1.4.6 Contrast (Enhanced)
No images of text	1.4.9 Images of Text (No Exception)
Sign language for video	1.2.6 Sign Language
Extended audio description	1.2.7 Extended Audio Description
Live captions	1.2.9 Audio-only (Live)
Reading level (lower secondary)	3.1.5 Reading Level
Pronunciation help	3.1.6 Pronunciation
Context-sensitive help	3.3.5 Help
Error prevention (all)	3.3.6 Error Prevention (All)

CSS for AAA Contrast

:root {
  /* AAA-compliant color pairs */
  --text-color: #1a1a1a;        /* On white: 16.1:1 */
  --text-muted: #525252;        /* On white: 7.1:1 */
  --background: #ffffff;

  /* Links need 3:1 contrast against surrounding text */
  --link-color: #0047ab;        /* On white: 8.5:1 */
}

/* High contrast mode support */
@media (prefers-contrast: more) {
  :root {
    --text-color: #000000;
    --background: #ffffff;
    --border-color: #000000;
  }
}

When to Use AAA

Scenario	Recommendation
Government/public services	Consider AAA
Healthcare applications	Consider AAA
Educational content	Consider AAA
Elderly user base	Consider AAA
Legal requirements	Check jurisdiction
General websites	AA is sufficient

Partial AAA Adoption

You can adopt specific AAA criteria without full compliance:

{
  "defaults": {
    "standard": "WCAG2AA",
    "rules": [
      "WCAG2AAA.Principle1.Guideline1_4.1_4_6"
    ]
  }
}

Testing AAA Compliance

# Run with AAA standard
npx pa11y --standard WCAG2AAA src/index.html

# Check specific criterion
npx pa11y --standard WCAG2AAA --include-notices src/index.html

See FORMS.md, IMAGES.md, NAVIGATION.md for details.

Related Skills

xhtml-author - Write valid XHTML-strict HTML5 markup
forms - HTML-first form patterns with CSS-only validation
custom-elements - Define and use custom HTML elements
i18n - Write internationalization-friendly HTML pages

accessibility-checker