How to Fix WCAG 2.2 AA Accessibility Violations on Your Site

Your page failed an automated accessibility scan that runs the full axe-core rule set against WCAG 2.2 AA and related best practices. This guide shows you how to reproduce the exact list of violations, triage them by severity, fix the most common failures in your templates, and re-test until the page comes back clean.

By Updated ⏱ 2-6 hours for a typical template-based site🎯 Intermediate● High impactAccessibility
Illustration: WCAG 2.2 AA violations overall fix guide
ACCESSIBILITY · FIX GUIDE WCAG 2.2 AA violations overall IMPACTEFFORT TIME2-6 hours for a typical template-based site LEVELIntermediate

Why it matters

About one in six people live with a disability, and automated violations such as unlabeled buttons, missing alt text and low-contrast text block screen reader, keyboard and low-vision users from reading or buying. The same issues weaken the machine-readable signals search engines and AI assistants rely on: images without alt text, links with no accessible name and broken heading structure give crawlers less context. Accessibility failures also carry legal risk under the European Accessibility Act (enforced since June 2025), the ADA in the US and similar laws, and plaintiffs' firms routinely use the same automated tools to find targets.

✕Beforeaxe reports 23 violations onhttps://example.com/: 4 critical(button-name, image-alt), 12 serious✓Afteraxe reports 0 violations onhttps://example.com/ across all rules,and new pull requests fail CI if any

What you need

Admin or code access to your site's theme, templates or CMS
Google Chrome or Microsoft Edge with the free axe DevTools extension (Deque)
Node.js 18+ if you want to scan from the command line or in CI
A contrast checker such as the WebAIM Contrast Checker

Step-by-step fix

1

Reproduce the violation list with axe

Open the failing page, press F12, choose the axe DevTools tab and click Scan ALL of my page. Our check runs every axe rule, including best-practice rules (like region, landmark-one-main and heading-order), so make sure best practices are enabled under the extension's settings. For a repeatable report, run the CLI version below and save the output.

text
npx @axe-core/cli https://example.com/ --save axe-home.json
# Strict WCAG-only view:
npx @axe-core/cli https://example.com/ --tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa
Pro tip: Scan pages at both desktop and mobile widths: hidden mobile menus and sticky bars often produce violations that only appear at one breakpoint.
2

Triage by impact and group by rule

Every axe result has an impact (critical, serious, moderate, minor) and a rule id. Sort by impact and fix critical and serious first. Then group by rule id: 40 color-contrast nodes usually come from two or three CSS classes, and 15 link-name failures are often one icon component in the header or footer.

  • Fix the shared template or component, not each page instance.
  • Note the CSS selector axe gives for each node to locate it in your theme.
Pro tip: Headers, footers, cookie banners and navigation menus appear on every page, so fixing them first removes the most violations site-wide.
3

Give images, buttons and links accessible names

Fix image-alt, button-name, link-name and input-image-alt. Informative images need alt text that describes their content or purpose; decorative images get alt="". Icon-only buttons and links (search, cart, social icons, carousel arrows) need an aria-label or visually hidden text, and the SVG inside should be hidden from assistive tech.

html
<img src="/img/team.jpg" alt="Example Co support team at the Leeds office">
<img src="/img/divider.svg" alt="">

<button type="button" aria-label="Open search">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

<a href="https://social.example.com/exampleco" aria-label="Example Co on social media">
  <svg aria-hidden="true" focusable="false">...</svg>
</a>
Pro tip: Avoid alt text like "image" or the file name; axe passes it, but users and search engines get no value from it.
4

Label form fields and set page language

Fix label, select-name, html-has-lang, html-lang-valid and document-title. Every input needs a programmatic label: a <label for> matching the input id, or an aria-label when a visible label is not possible. Placeholder text alone does not count.

Add a valid lang attribute to the <html> element and a unique <title>.

html
<html lang="en">
<head><title>Contact us | Example Co</title></head>
...
<label for="email">Email address</label>
<input id="email" name="email" type="email" autocomplete="email">

<input type="search" name="q" aria-label="Search products">
Pro tip: Add the correct `autocomplete` values on personal-data fields; it supports WCAG 1.3.5 and speeds up checkout.
5

Raise text contrast to 4.5:1

Fix color-contrast. 66px bold and up) needs 3:1. Use the foreground and background colours axe reports, test alternatives in a contrast checker, then update the CSS variables or theme settings that produce them.

Check placeholder text, disabled-looking links, text over hero images and sale badges.

html
:root {
  --text-muted: #595959;   /* was #999999, 2.8:1 on white -> now 7:1 */
  --brand-link: #0b5fa5;   /* 6.1:1 on white */
}
.hero__caption {
  background: rgba(0, 0, 0, 0.65); /* solid overlay behind text on images */
  color: #ffffff;
}
Pro tip: Change the colour token once in your design system instead of overriding individual elements, or the problem will come back with the next component.
6

Fix ARIA, IDs and page structure

Work through structural rules: aria-allowed-attr, aria-required-children, aria-hidden-focus, aria-valid-attr-value, duplicate-id-aria, list, listitem, heading-order, landmark-one-main, region and page-has-heading-one.

  • Remove ARIA roles you don't need; native <button>, <nav> and <ul> are safer.
  • Never put aria-hidden="true" on an element that contains focusable links or buttons.
  • Wrap primary content in one <main> and keep headings in order (h1, h2, h3).
  • Make every id unique, especially in repeated product cards.
html
<header>...</header>
<nav aria-label="Main">...</nav>
<main id="main">
  <h1>Running shoes</h1>
  <h2>Best sellers</h2>
</main>
<footer>...</footer>
Pro tip: If a third-party widget (chat, reviews, cookie banner) causes ARIA errors, check its settings for an accessible mode or report it to the vendor; you are still responsible for it.
7

Meet WCAG 2.2 target size and focus rules

8 Target Size (Minimum)**: clickable targets must be at least 24×24 CSS pixels or have enough spacing. axe flags this as target-size. Enlarge small icon links, pagination dots and inline close buttons with padding.

11 Focus Not Obscured** manually: tab through the page and confirm sticky headers or cookie bars never fully cover the focused element.

html
.icon-link,
.carousel__dot,
.modal__close {
  min-width: 24px;
  min-height: 24px;
  padding: 4px;
}
html {
  scroll-padding-top: 80px; /* height of sticky header so focused items stay visible */
}
:focus-visible {
  outline: 3px solid #0b5fa5;
  outline-offset: 2px;
}
Pro tip: Aim for 44×44px on mobile tap targets; it exceeds the AA minimum and reduces mis-taps.
8

Re-scan and block regressions in CI

Clear any page and CDN caches, then rescan the same URLs with axe DevTools or the CLI and confirm zero violations. Scan a sample of each template type (home, category, product, article, contact, checkout). To keep it clean, add an automated axe test to your pipeline so new code fails the build when it introduces a violation.

javascript
// tests/a11y.spec.js (npm i -D @playwright/test @axe-core/playwright)
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

for (const path of ['/', '/products/', '/contact/']) {
  test(`no axe violations on ${path}`, async ({ page }) => {
    await page.goto(`https://example.com${path}`);
    const results = await new AxeBuilder({ page }).analyze();
    expect(results.violations).toEqual([]);
  });
}
Pro tip: Automated tools catch roughly a third of WCAG issues; follow up with a keyboard-only pass and a quick screen reader test (NVDA or VoiceOver).

Platform-specific notes

WordPress

Most violations come from the theme and page builder. Set image alt text in Media > Library > Attachment details > Alternative Text, fix contrast in Appearance > Editor > Styles (block themes) or Appearance > Customize > Colors, and label forms in your form plugin's field settings. Remove `user-scalable=no` from the viewport meta if your theme adds it (`meta-viewport` rule).

Shopify

Edit alt text in Products > [product] > Media > Add alt text and in Content > Files. Contrast and colour schemes are under Online Store > Themes > Customize > Theme settings > Colors. Icon-button labels and ARIA live in theme files (Edit code > snippets/sections .liquid); Dawn-based themes are a good accessible baseline. Check installed apps, which often inject unlabeled widgets.

Wix

Use Settings > Accessibility Wizard to scan for missing alt text, headings and language. Set alt text via image Settings > 'What's in the image?'. Contrast and tag (H1-H6) choices are per-element in the Editor; you cannot edit raw HTML, so replace inaccessible third-party widgets.

Webflow

Set alt text in the Assets panel or image settings (mark decorative images as Decorative). Add aria-label through Element settings > Custom attributes. Use the built-in Audit panel to flag missing alt text and labels, and fix contrast in shared Classes or Variables so changes apply site-wide.

Next.js / React

Use `eslint-plugin-jsx-a11y` (included in `eslint-config-next`) to catch issues at build time, give `next/image` a meaningful `alt` prop, set `lang` in `app/layout.tsx` on `<html>`, and run `@axe-core/playwright` against built pages since client-rendered markup only appears after hydration.

Check that it worked

✅ How to verify

  • Run axe DevTools 'Scan ALL of my page' on each fixed template and confirm 0 violations, with best-practice rules enabled.
  • Run `npx @axe-core/cli https://example.com/ https://example.com/contact/` and check the output reports no violations.
  • Tab through each page using only the keyboard: every link, button and field should be reachable, visibly focused and never hidden behind sticky elements.
  • Re-run our audit and confirm the 'WCAG 2.2 AA violations overall' check passes.

⚠️ Common mistakes

  • Installing an accessibility overlay widget instead of fixing the HTML; overlays do not remove the underlying violations and can add new ARIA errors.
  • Fixing individual page instances instead of the shared header, footer or component, so the same violation reappears on every new page.
  • Adding ARIA roles and attributes to divs instead of using native button, nav, label and list elements, which creates new aria-* violations.
  • Testing only the desktop layout and only with the cookie banner dismissed, missing violations in mobile menus and consent dialogs.

Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.

Check my site free

FAQ

What is the difference between critical, serious, moderate and minor accessibility violations?

They are axe-core's impact ratings. Critical issues fully block some users (for example an unlabeled checkout button), serious issues cause major difficulty (low contrast, missing form labels), moderate and minor issues cause friction. Fix critical and serious first, but all of them count toward this check.

Does passing an automated axe scan mean my site is WCAG 2.2 AA compliant?

No. Automated tests reliably detect only a portion of WCAG failures. Issues like meaningful alt text quality, logical focus order, captions and focus-not-obscured need manual review. A clean axe scan is the baseline, not proof of full conformance.

What changed in WCAG 2.2 compared to 2.1?

WCAG 2.2 added nine success criteria, six at level A or AA, including Target Size (Minimum) 2.5.8, Focus Not Obscured 2.4.11, Dragging Movements 2.5.7, Consistent Help 3.2.6, Redundant Entry 3.3.7 and Accessible Authentication 3.3.8. It also removed 4.1.1 Parsing as obsolete.

Do accessibility fixes help SEO?

Indirectly, yes. Descriptive alt text, real link text, a single clear H1, proper headings and a correct lang attribute give search engines and AI systems better context for your content, and the usability gains tend to improve engagement metrics.