WordPress accessibility — a practical WCAG 2.1 AA guide

Theme choice matters more than anything

A WP site is only as accessible as its theme. The default bundled themes (Twenty Twenty-Four, Twenty Twenty-Five) are reasonably accessible — they pass axe-core cleanly on a fresh install. Most commercial themes do not.

Common theme-level issues:

• Insufficient contrast on buttons, links in hero sections, and pagination ("light grey on white" aesthetic fails 4.5:1).
• Decorative icons read aloud — SVGs with no aria-hidden attribute.
• Missing focus styles — themes that reset :focus without providing an alternative make keyboard navigation invisible.
• Mobile hamburger menus without proper aria-expanded / focus trap.

If you're starting fresh, use a theme from the official "accessibility-ready" tag. If you're stuck with an existing theme that fails, you can usually fix contrast and focus styles via a child theme without replacing the parent.

Gutenberg — what blocks get wrong

The WordPress block editor is substantially more accessible than the classic editor — but the defaults still let editors ship inaccessible content:

• Image block — the alt field is not required in the UI. Editors routinely upload images without alt text.
• Heading block — editors can pick any H-level, enabling heading-level skips (H1 → H3) that break screen-reader outlines.
• Button block— the text is editable, so "Click here" and "Read more" are common. WCAG 2.4.4 requires link purpose in context.
• Cover / Media & Text — decorative background images can be read as informative; the alt defaults to nothing useful.

The fix is editor education (not a tech fix). Train content editors to: always write alt text, use heading levels sequentially, and write button text that makes sense out of context ("Read our pricing" not "Read more").

Alt text at scale — Media Library practice

Old WordPress sites accumulate thousands of images in the Media Library without alt text. Retrofitting is tedious but one-time. Approach:

1. Run a scan — identify the top 50-100 images appearing on indexed pages (your scanner tool will list them).
2. Alt-text the "informative" ones — images that carry meaning readers would miss without.
3. For purely decorative images (dividers, watermarks, background flourishes), set alt text to empty in the Media Library — this removes them from assistive tech.
4. Don't bulk-generate alt text via AI for informative images without review — auto-alt is notorious for "a person" when the content is actually your CEO headshot, and "a screenshot" when it's a complex diagram.

Forms: Gravity, WPForms, Contact Form 7

Contact-form plugins are the #1 source of WCAG violations on WP sites. Accessibility rankings, roughly:

• Gravity Forms — best out-of-box. Labels, descriptions, error messages all programmatically associated by default.
• WPForms — good for Lite, some weaker patterns in Pro (multi-step forms skip focus).
• Contact Form 7 — default markup is weak. Needs manual fixes: explicit <label>, aria-describedby for errors.
• Formidable Forms — improves with "Accessibility" option turned on, off by default.

If a form has a CAPTCHA, make sure it's accessible: reCAPTCHA v3 is invisible so it's fine; v2 needs an audio-challenge fallback and often fails when the user is keyboard-only.

Menus and focus order

Hamburger menus on mobile, mega menus on desktop, and megamenus in particular trip up keyboard users. Minimum requirements:

• Menu button has aria-expanded reflecting open/closed state.
• When menu opens, focus moves into it; when closed, focus returns to the toggle.
• Escape key closes it.
• Tab order follows visual order.
• Submenu triggers use aria-haspopup="menu" and aria-expanded.

Plugins that help (and the one that hurts)

Helpful:

• Axle Accessibility Scanner — runs axe-core in your browser inside WP admin. Free tier unlimited. Project home.
• WP Accessibility (by Joe Dolson) — fixes small issues like adding skip links, removing duplicate IDs.
• Sa11y — in-page auditor visible to editors while they edit.

Hurts (avoid):

• Accessibility overlay widgets(UserWay, accessiBe, EqualWeb, AudioEye Lite, Equally AI). These inject JavaScript that attempts to "fix" accessibility at runtime — they don't, and they cost accessiBe a $1,000,000 FTC settlement in January 2025. WP.org doesn't ban them, but using one does not provide legal defence under EAA / ADA / תקנה 35.

Scanning your WP site — locally and in CI

If your WP lives behind a public URL you can point any scanner at it. If you're on LocalWP (*.local), staging behind basic auth, or on a VPN-only intranet WP, you need a client-side scanner that loads the page in a browser iframe and runs axe-core in the browser.

Axle's WordPress plugin does exactly this — Tools → axle in WP admin, click Scan Now, axe-core 4.11 runs in your admin browser against your chosen URL. Zero external calls for the scan itself. Daily WP-Cron scan is optional (uses the hosted scanner, requires a public URL).

For dev teams: if your WP site is built with a block theme and deployed via Git, you can also put axle in CI just like any other site — point the scanner at your staging URL and fail the build on regressions.

The statement — WP-specific considerations

WP themes often render the accessibility statement as a Page. A few checks:

• The statement page itself must be accessible — no PDF-only, no image-of-text.
• Link to it from the footer on every page (not just once).
• Keep the "Last updated" date visible — regulators look for stale statements as a signal of non-compliance.
• For multi-language WP (Polylang, WPML), publish a statement in every language the site serves.

axle generates a Hebrew statement aligned with Israeli תקנה 35 that you can paste straight into a WP Page: /statement.