WCAG 2.2 Compliance: Complete Developer Guide

WCAG 2.2 (Web Content Accessibility Guidelines) provides a globally recognized standard for web accessibility with three conformance levels — A, AA, and AAA — and new success criteria for focus appearance, accessible authentication, and pointer targets.

What You’ll Learn

By the end of this tutorial, you’ll understand WCAG levels and conformance, the new WCAG 2.2 success criteria, how to evaluate compliance using automated tools (WAVE, axe, Lighthouse), and how to prioritize and remediate accessibility issues.

Why WCAG Compliance Matters

WCAG 2.2 is referenced by laws worldwide — the ADA, Section 508, the European Accessibility Act, and many others. Achieving WCAG AA compliance is the legal benchmark for most organizations. Beyond legal requirements, WCAG compliance improves SEO, user experience, and brand reputation. At DodaTech, Doda Browser includes an accessibility checker that scans pages against WCAG criteria, helping developers catch issues during development.

WCAG Learning Path

    flowchart LR
  A[Accessibility Overview] --> B[WCAG Compliance]
  B --> C[ARIA Basics]
  B --> D[Keyboard Navigation]
  B --> E[Color Contrast]
  B:::current

  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
  

What Is WCAG?

The Web Content Accessibility Guidelines (WCAG) are developed by the World Wide Web Consortium (W3C) through the Web Accessibility Initiative (WAI). WCAG 2.2 was published in October 2023 as the latest version, building on WCAG 2.1 and 2.0.

WCAG is organized around four principles (POUR: Perceivable, Operable, Understandable, Robust) with 13 guidelines and 86 success criteria across three conformance levels.

WCAG Conformance Levels

Level A — Minimum

Level A is the minimum level of conformance. If you fail any Level A criterion, your site is completely inaccessible to some users. These are the easiest wins:

• 1.1.1 Non-text Content — alt text for images
• 2.1.1 Keyboard — all functionality available via keyboard
• 2.4.4 Link Purpose (In Context) — links must describe their purpose
• 3.3.2 Labels or Instructions — form inputs must have labels
• 4.1.2 Name, Role, Value — custom controls must report their role and state

Level AA — The Legal Standard

Level AA is the most common legal benchmark. Most accessibility lawsuits reference WCAG AA:

• 1.4.3 Contrast (Minimum) — 4.5:1 ratio for normal text
• 2.4.7 Focus Visible — keyboard focus indicator must be visible
• 3.3.3 Error Suggestion — error messages must suggest fixes
• 4.1.3 Status Messages — status changes must be announced to assistive tech

Level AAA — The Highest Standard

Level AAA is the highest conformance level. Not all content can meet AAA, and it’s not required by law:

• 1.4.6 Contrast (Enhanced) — 7:1 ratio
• 2.4.10 Section Headings — organize content with headings
• 3.1.5 Reading Level — content for advanced readers can have a simplified version

New in WCAG 2.2

WCAG 2.2 introduced several new success criteria:

2.4.11 Focus Appearance (AA)

The focus indicator must be at least as large as a 2px thick perimeter of the element, with a contrast ratio of at least 3:1 between the focused and unfocused states.

/* Good focus style — meets WCAG 2.2 Focus Appearance */
button:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}

/* Bad — too thin and low contrast */
button:focus {
  outline: 1px dotted #ccc;
}

3.3.7 Accessible Authentication (AA)

Authentication processes must not rely on cognitive function tests like remembering passwords or solving puzzles. Biometrics, security keys, and paste-supporting password fields are acceptable.

<!-- Good: Allow password manager paste -->
<label for="password">Password</label>
<input type="password" id="password" name="password" autocomplete="current-password">

<!-- Good: Offer WebAuthn / passkey option -->
<button type="button" onclick="webAuthnLogin()">
  Sign in with Passkey
</button>

2.5.8 Dragging Movements (AA)

If an operation requires dragging, there must be an alternative single-pointer method (e.g., click-to-select then click-to-place instead of drag-and-drop).

// Accessible drag-and-drop with single-click alternative
function initDragDrop(container) {
  let items = container.querySelectorAll('.draggable');

  items.forEach(item => {
    // Standard drag support
    item.setAttribute('draggable', 'true');

    // Single-click alternative
    item.addEventListener('click', function(e) {
      if (this.dataset.selected === 'true') {
        // Place the item at the target position
        placeItem(this, getTargetPosition(e));
        this.dataset.selected = 'false';
      } else {
        // Select the item
        selectItem(this);
        this.dataset.selected = 'true';
      }
    });
  });
}

2.5.7 Pointer Target Spacing (AA)

Pointer targets (buttons, links) must be at least 24×24 CSS pixels, with sufficient spacing from adjacent targets.

/* Good — meets 24×24 minimum target size */
.nav-link {
  display: inline-block;
  padding: 12px 16px;    /* generous touch target */
  min-width: 24px;
  min-height: 24px;
}

/* Good — spacing between targets */
.menu-item + .menu-item {
  margin-inline-start: 8px;
}

Evaluating Compliance

Automated Tools

Automated tools catch about 30% of accessibility issues. They’re fast and reliable for detecting structural problems:

# axe-core CLI — run on a local URL
npx axe http://localhost:3000 --save report.json

# Pa11y CI — runs in CI pipeline
npx pa11y-ci --config .pa11yci.json

# Lighthouse — built into Chrome DevTools
# Open DevTools → Lighthouse → Accessibility

// Using axe-core programmatically in tests
const { axe } = require('axe-core');
const { JSDOM } = require('jsdom');

async function checkAccessibility(html) {
  const { window } = new JSDOM(html);
  const results = await axe.run(window.document);
  return results.violations;
}

// Example usage
checkAccessibility(`
  <html>
    <body>
      <button>Click me</button>
      <img src="photo.jpg">
    </body>
  </html>
`).then(violations => {
  console.log(`Found ${violations.length} violations`);
  violations.forEach(v => console.log(`- ${v.help} (${v.impact})`));
});

Expected output:

Found 2 violations
- Images must have alternate text (critical)
- Document must have one main landmark (serious)

Manual Testing Checklist

Automated tools miss many issues. Supplement with manual checks:

    flowchart TD
  A[Accessibility Audit] --> B[Automated Scan]
  A --> C[Manual Testing]
  A --> D[Screen Reader Test]
  A --> E[User Testing]
  B --> F[List of Violations]
  C --> G[Keyboard & Focus Issues]
  D --> H[Screen Reader UX Issues]
  E --> I[Real-world Barriers]
  F --> J[Prioritize & Remediate]
  G --> J
  H --> J
  I --> J
  

Conformance Claims

A WCAG conformance claim is a public statement that a page or set of pages meets WCAG requirements. You can create one using the W3C’s WCAG-EM (Website Accessibility Conformance Evaluation Methodology):

<!-- Example conformance claim (placed in page footer) -->
<div aria-label="Accessibility conformance statement">
  <p>
    This website conforms to
    <a href="https://www.w3.org/TR/WCAG22/">
      WCAG 2.2
    </a>
    at Level AA.
    Last reviewed: June 2026.
  </p>
  <p>
    Evaluation method:
    <a href="https://www.w3.org/WAI/eval/conformance.html">
      WCAG-EM
    </a>
  </p>
</div>

{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "accessibilityFeature": ["alternativeText", "longDescription", "structuredNavigation"],
  "accessibilityHazard": ["noFlashingHazard"],
  "accessibilityAPI": "ARIA",
  "accessibilityControl": ["fullKeyboardControl", "fullMouseControl"],
  "accessMode": ["textual", "visual"],
  "accessModeSufficient": ["textual", "visual"],
  "inAccessible": false
}

Remediation Workflow

When you find accessibility issues, follow this prioritization:

1. Critical (Level A failures) — Fix immediately. Users are blocked entirely.
2. Serious (Level AA failures) — Fix within the sprint. Users are significantly impacted.
3. Moderate (Level AA best practices) — Fix within the next sprint. Users are inconvenienced.
4. Minor (Level AAA suggestions) — Add to backlog. Enhancements for power users.

# Sample remediation tracking with git
git checkout -b fix/a11y-critical-issues

# Fix 1: Add missing alt text to images
git add public/images/
git commit -m "fix(a11y): Add alt text to 15 images

- Added descriptive alt text to 12 informative images
- Added empty alt (alt=\"\") to 3 decorative images
- WCAG SC 1.1.1 Non-text Content"

# Fix 2: Improve focus visibility
git add src/styles/
git commit -m "fix(a11y): Improve keyboard focus indicators

- Added 3px blue outline with offset on :focus-visible
- Ensured 3:1 contrast ratio for focus states
- WCAG SC 2.4.7 Focus Visible, 2.4.11 Focus Appearance"

# Fix 3: Fix heading hierarchy
git add src/components/
git commit -m "fix(a11y): Correct heading hierarchy

- Changed div.heading to proper h1-h6 elements
- Ensured no skipped heading levels
- WCAG SC 1.3.1 Info and Relationships"

Common Mistakes Developers Make

1. Adding aria-label Without Removing Redundant Text

<button aria-label="Close dialog">Close ×</button> — screen readers read “Close dialog Close” because aria-label replaces the visible text, but some screen readers also read the button text.

2. Confusing WCAG Levels

“I passed a Lighthouse audit so I’m WCAG AA compliant.” Lighthouse only checks a subset of criteria. Full conformance requires manual testing and a conformance claim.

3. Using role="alert" on Hidden Elements

A hidden element with role="alert" won’t be announced. The element must be visible (or become visible) for the alert to fire.

4. Ignoring Focus Appearance in WCAG 2.2

The old 1px dotted outline no longer meets the new Focus Appearance criterion. Your focus indicator must be at least 2px thick with 3:1 contrast.

5. Testing Only with One Tool

“I ran WAVE and there were no errors, so the page is accessible.” Automated tools catch only ~30% of issues. You need manual testing, screen reader testing, and ideally user testing.

6. Making Conformance Claims Without Documentation

A conformance claim requires documentation of the evaluation methodology, scope, and date. Simply adding a badge doesn’t constitute a valid claim.

7. Not Testing on Mobile

WCAG applies to all content on all devices. Mobile-specific issues (touch targets, viewport zoom, orientation) are frequently missed.

Practice Questions

1. What are the three conformance levels of WCAG 2.2?

Level A (minimum), Level AA (legal standard), Level AAA (highest). Most legal requirements target Level AA.

2. What is new in WCAG 2.2?

Focus Appearance (AA), Accessible Authentication (AA), Dragging Movements (AA), and Pointer Target Spacing (AA) are the major new success criteria.

3. Why can’t you rely solely on automated accessibility testing tools?

Automated tools catch about 30% of issues. They miss contextual problems like meaningful alt text, keyboard navigation logic, and screen reader announcement order.

4. What does a WCAG conformance claim require?

Documentation of the evaluation method (WCAG-EM), scope of evaluated content, date of evaluation, WCAG version, and conformance level.

5. Challenge: Run axe DevTools on a single page of a site you manage. Document all violations, categorize them by WCAG success criterion and level, and fix the three most critical ones.

Real-World Task

Create a WCAG compliance matrix for your project. List all 86 success criteria. Mark each as Pass, Fail, or Not Applicable. Include testing method used (automated tool, manual check, screen reader test). Create a remediation plan for all failures prioritized by level.

FAQ

Try It Yourself

Create a WCAG 2.2 audit script:

// wcag-audit.js — Run with Node.js
const { JSDOM } = require('jsdom');

function auditPage(html) {
  const { window } = new JSDOM(html);
  const doc = window.document;
  const issues = [];

  // Check 1: Images without alt text (SC 1.1.1)
  doc.querySelectorAll('img:not([alt])').forEach(img => {
    issues.push({
      sc: '1.1.1',
      level: 'A',
      element: img.outerHTML,
      message: 'Image missing alt attribute'
    });
  });

  // Check 2: Missing form labels (SC 3.3.2)
  doc.querySelectorAll('input:not([type="hidden"]):not([aria-label]):not([aria-labelledby])').forEach(input => {
    const id = input.getAttribute('id');
    if (!id || !doc.querySelector(`label[for="${id}"]`)) {
      issues.push({
        sc: '3.3.2',
        level: 'A',
        element: input.outerHTML,
        message: 'Form input without associated label'
      });
    }
  });

  // Check 3: Missing lang attribute (SC 3.1.1)
  if (!doc.documentElement.getAttribute('lang')) {
    issues.push({
      sc: '3.1.1',
      level: 'A',
      element: '<html>',
      message: 'Missing lang attribute on html element'
    });
  }

  return issues;
}

const html = `
<!DOCTYPE html>
<html>
<head><title>Test</title></head>
<body>
  <img src="photo.jpg">
  <input type="text">
</body>
</html>
`;

const results = auditPage(html);
console.log(`Found ${results.length} issues:`);
results.forEach(r => {
  console.log(`[${r.level}] SC ${r.sc}: ${r.message}`);
  console.log(`  Element: ${r.element.substring(0, 80)}`);
});

Expected output:

Found 3 issues:
[A] SC 1.1.1: Image missing alt attribute
  Element: <img src="photo.jpg">
[A] SC 3.3.2: Form input without associated label
  Element: <input type="text">
[A] SC 3.1.1: Missing lang attribute on html element

What’s Next

Congratulations on completing this WCAG Compliance tutorial! Here’s where to go from here:

• Practice daily — Run axe on every page you build
• Build a project — Create a WCAG compliance dashboard for your team
• Explore related topics — Learn ARIA basics next
• Join the community — Discuss with other learners and share your progress

Remember: every expert was once a beginner. Keep coding!