ThemesCorners
Blog
11 min readby ThemesCorners

WordPress Accessibility Checklist — WCAG 2.2 AA in Practice

A practical checklist of accessibility fixes that compound into a site real users can actually use — and that survives a legal challenge.

Accessibility lawsuits in 2026 are no longer rare. The EU Accessibility Act came into force in mid-2025, and US ADA litigation has shifted to a steady drumbeat against e-commerce specifically. The plugins that promise to make your site "WCAG compliant" with one click do not, and have repeatedly been ruled inadequate in court.

The good news: actual accessibility is achievable with a few weeks of disciplined work. Here is the checklist we run for every theme we ship and every client site we audit.

Run a real audit before you start

Three tools, used together:

  1. axe DevTools (browser extension). Catches roughly 50% of accessibility issues automatically.
  2. NVDA or VoiceOver. Actually navigate your site with a screen reader. The experience teaches you more than any tool report.
  3. Keyboard alone. Disconnect your mouse. Try to complete your site's main flow with Tab, Shift+Tab, Enter, Arrow keys, and Esc.

If you cannot complete the main flow with keyboard alone in under five minutes, the audit results below are noise — fix that first.

The checklist

1. Page structure

  • Exactly one <h1> per page, describing the page.
  • Heading levels do not skip (no jumping from <h2> to <h4>).
  • Landmarks are present: <header>, <nav>, <main>, <footer> — and only one <main>.
  • A "Skip to main content" link is the first focusable element on every page.

2. Colour contrast

  • Body text contrast is at least 4.5:1 against its background.
  • Large text (18px bold or 24px regular) is at least 3:1.
  • Non-text UI (button borders, focus rings, icon-only buttons) is at least 3:1.
  • Run your colour palette through an oklch contrast checker — sRGB checkers undercount on certain hues.

Common WordPress pitfalls:

  • Themes that use text-muted set to slate-400 or lighter. Most do; check yours.
  • Buttons with bg-blue-500 text-white look fine but only just pass — bg-blue-600 is safer.
  • "Disabled" button states often fail contrast and are a real accessibility issue.

3. Focus visibility

  • Every focusable element has a visible focus indicator. Default browser blue ring is fine; many themes remove it.
  • Focus indicators have at least 3:1 contrast against adjacent colours.
  • Focus order matches visual order (no jumping around the page).

In Tailwind: never use outline-none without focus-visible:ring-2 to replace it.

4. Forms

  • Every form input has a <label>. Placeholder text is not a label.
  • Required fields are marked both visually and with aria-required="true".
  • Error messages are tied to inputs with aria-describedby and announced via aria-live="polite".
  • Inputs that accept specific formats include inputmode and autocomplete attributes.

5. Images

  • Every <img> has a meaningful alt attribute, or alt="" if purely decorative.
  • Complex images (charts, diagrams) have longer descriptions adjacent or via aria-describedby.
  • The LCP image should not be decorative — if it is, your hero is doing nothing.

For WordPress: in the media library, the Alt text field is the source. Make adding alt text part of your editorial workflow, not optional.

6. Links and buttons

  • Link text describes the destination ("Read the security guide", not "Click here").
  • Buttons that look like links and links that look like buttons must use the correct element. A <button> triggers actions; an <a> navigates.
  • Icon-only buttons have aria-label.
  • Links that open a new tab announce that (visually with an icon, semantically with aria-label like "Documentation (opens in new tab)").

7. Tables

  • Use <table> only for actual tabular data, never for layout.
  • <th> for headers with scope="col" or scope="row".
  • Captions via <caption>.
  • Avoid merged cells where possible.

8. Dynamic content

  • Modal dialogs trap focus inside themselves, return focus to the trigger when closed, and close on Esc.
  • Tooltip content is reachable via keyboard, not just hover.
  • Carousels (avoid them) need pause controls, focus management on slide change, and announce slide changes.
  • Toast notifications use role="status" for non-urgent or role="alert" for urgent updates.

9. Motion

  • Respect prefers-reduced-motion. All animations should disable or simplify when the user has it set:
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
  • Auto-playing video must have user-accessible controls.
  • Parallax effects need a way to disable.

10. WordPress-specific

  • The block editor itself is the source of much theme accessibility — themes that override editor styles can break accessibility for authors.
  • wp_nav_menu outputs require aria-label when present multiple times.
  • Search forms need a <label> even if visually hidden.
  • The classic comments form is a known accessibility weak point — review and fix it.

What the accessibility plugins do (and don't)

Plugins like UserWay, accessiBe, and EqualWeb advertise one-click WCAG compliance. The reality:

  • They add an overlay menu with toggles for font size, contrast, etc. — which can be helpful for users.
  • They claim to "automatically fix" accessibility issues. They cannot — that fundamentally requires editing the HTML the page produces, which a JS overlay cannot do for static structural issues.
  • They have been ruled inadequate in multiple US ADA lawsuits. Some are now actively counter-recommended by disability advocacy organisations.

Use them only as a layer on top of actually fixing the underlying issues. If you do not fix the underlying issues, the plugin will not save you in court.

What the law actually requires (rough guide)

This is not legal advice — talk to a lawyer for your jurisdiction.

  • EU: European Accessibility Act applies to consumer-facing e-commerce, banking, transport, and a few other categories. Enforcement started June 2025 and ramps over 2026–2027.
  • US: ADA Title III. Applies to "places of public accommodation", which courts have repeatedly extended to commercial websites. Settlements typically require WCAG 2.1 AA compliance.
  • UK: Equality Act 2010. Less aggressively enforced than the US but increasing.
  • Australia: Disability Discrimination Act. Notable Maguire v SOCOG precedent.

Whatever your jurisdiction, WCAG 2.2 Level AA is the practical target. WCAG 2.2 has been the W3C recommendation since late 2023.

A realistic timeline

For a moderate WordPress site (50–200 pages):

  • Week 1: Run all three audits. Fix the top 10 issues axe surfaces.
  • Week 2: Fix focus visibility, contrast issues, missing alt text.
  • Week 3: Fix forms — labels, errors, autocomplete.
  • Week 4: Test with screen reader. Fix what is found.
  • Ongoing: Add accessibility to your editorial checklist. New content must pass before publishing.

Then re-audit every six months. WCAG criteria evolve, your content evolves, third-party plugins introduce regressions. Accessibility is a process, not a state.

How our themes help

Our themes ship with:

  • Semantic HTML5 (correct landmarks, heading hierarchy)
  • Visible focus indicators on every interactive element
  • WCAG AA contrast in all default colour combinations
  • Skip-to-content links
  • Keyboard-navigable menus and accordions
  • prefers-reduced-motion support

That is the baseline you would otherwise pay an accessibility consultant to retrofit. Then it is on you to keep the content accessible — alt text on uploaded images, clear link text, well-structured headings — but the theme will not fight you.

Related articles