WordPress Accessibility Audit: Make Any Theme WCAG 2.2 Compliant

WordPress accessibility is one of the most overlooked aspects of site quality. Most themes ship with accessibility problems built in - insufficient color contrast, missing alt text, keyboard navigation gaps, and form labels that screen readers cannot parse. WCAG 2.2 is the current standard and reaching Level AA compliance is achievable for any WordPress site with the right audit and targeted fixes.

This guide walks through a complete WordPress accessibility audit using axe DevTools and manual testing, then covers the most common failures and how to fix them: color contrast, alt text, keyboard navigation, ARIA attributes, skip links, form labels, and heading hierarchy.

Why WCAG 2.2 and Not Just “Accessibility”

WCAG 2.2 (Web Content Accessibility Guidelines 2.2) was published in October 2023. It adds nine new success criteria to WCAG 2.1, mostly focused on cognitive accessibility and mobile users. The levels are A (minimum), AA (standard commercial requirement), and AAA (advanced). WCAG 2.2 Level AA is what legal accessibility requirements in the US (ADA), UK (Equality Act), and EU (EAA) point to.

The new WCAG 2.2 criteria most relevant to WordPress:

• 2.4.11 Focus Appearance (AA): Keyboard focus indicators must be a minimum size and have sufficient contrast. Many WordPress themes have nearly invisible focus outlines.
• 2.5.3 Label in Name (A): Buttons with icons must have an accessible name that includes the visible label text. Icon-only buttons in theme builders often fail this.
• 3.2.6 Consistent Help (A): If help mechanisms (chat, contact, help links) appear on multiple pages, they must be in the same location. Footer chat widgets typically pass this.
• 3.3.7 Redundant Entry (A): Users should not have to re-enter information already provided in the same session. Relevant to multi-step WooCommerce checkout flows.

Running an Automated Accessibility Audit with axe DevTools

Automated testing catches approximately 30-40% of accessibility failures. It is the starting point, not the complete audit. axe DevTools is the best free option and is available as a Chrome and Firefox extension.

Axe DevTools Audit Process

1. Install the axe DevTools browser extension from the Chrome Web Store
2. Open your WordPress site’s homepage while logged out (as a real visitor would see it)
3. Open Chrome DevTools (F12) and find the axe DevTools tab
4. Click “Scan All of My Page”
5. Review the violations list - each violation shows the affected element, the rule violated, and guidance on fixing it
6. Repeat for key pages: homepage, a blog post, contact form page, and checkout (if WooCommerce)

Export results to CSV or use axe DevTools’ issue tracking integration. Track issues by page and severity (critical, serious, moderate, minor).

Other Automated Tools Worth Running

• WAVE (wave.webaim.org): Browser extension that overlays visual indicators directly on the page. Excellent for quick visual review of where issues are on the page.
• Lighthouse (built into Chrome DevTools): Accessibility audit score with automated checks. Not as thorough as axe but convenient for quick checks.
• Sa11y: A WordPress plugin that shows inline accessibility warnings in the editor and front end. Useful for content editors who are not developers.

Color Contrast: The Most Common WCAG Failure

WCAG 2.2 AA requires a contrast ratio of 4.5:1 for normal text and 3:1 for large text (18pt or 14pt bold and above). Most WordPress themes have at least a few color combinations that fail this, typically light gray body text on white backgrounds, or light-colored links on colored backgrounds.

Checking Color Contrast

Use the WebAIM Contrast Checker (webaim.org/resources/contrastchecker/) to check any color pair. Enter the foreground and background colors in hex and it shows the contrast ratio and whether it passes AA or AAA.

Common failing combinations in WordPress themes:

Fixing Color Contrast in WordPress

For block themes, update the theme.json palette with accessible color values. Read the guide on WordPress theme development best practices for a full theme.json reference. For classic themes, override the failing colors in your child theme’s CSS. Target specific elements rather than rewriting the entire stylesheet:

Add these CSS overrides in your child theme’s style.css or via the WordPress Customizer’s Additional CSS section for targeted fixes without a full theme modification.

Alt Text: Beyond “Add a Description”

Alt text is the most widely known accessibility requirement but also the most frequently done wrong. The goal of alt text is to convey the information the image provides to someone who cannot see it. Bad alt text is either missing, or it repeats the filename, or it describes the image appearance without conveying its meaning in context.

Alt Text by Image Type

• Informative images: Describe what the image communicates. A screenshot of a plugin settings screen should describe the key settings visible, not just “plugin settings screenshot.”
• Decorative images: Use empty alt text (alt=””). Do not use alt=”decorative” - that reads aloud to screen reader users unnecessarily. Decorative images are those that add no information - dividers, decorative backgrounds, purely aesthetic illustrations.
• Functional images (linked images): The alt text should describe the destination or action, not the image. The logo that links to the homepage: alt=”Home” or alt=”Company Name home page.”
• Images of text: Repeat the text in the image as the alt text. If the image contains text that is not repeated in surrounding content, that text must be in alt.
• Complex images (charts, graphs): Alt text is insufficient for complex data visualizations. Provide a full text description nearby or as a linked long description.

Auditing Alt Text in WordPress

The Media Library does not give you a complete view of alt text status across your site. Use the Image SEO report in RankMath, or the “Images without alt text” filter in WP Accessibility Helper to get a list of images missing alt text.

Keyboard Navigation

Keyboard navigation testing is manual work that automated tools cannot fully replace. Test by pressing Tab through your site with a keyboard only and verify:

• Every interactive element (links, buttons, form fields, dropdowns, modal triggers) can be reached with Tab
• The focus order follows the visual reading order (left to right, top to bottom)
• Focus is never trapped - after pressing Tab or Shift+Tab, focus always moves to the next or previous element
• Modal dialogs trap focus within the modal when open (this is correct behavior - focus should cycle within the modal until it is closed)
• Dropdown menus are operable with arrow keys per ARIA patterns
• The current focus position is visually clear at all times

Focus Indicator Requirements (WCAG 2.2)

WCAG 2.2 AA (2.4.11) requires focus indicators to have a minimum area of a CSS pixel perimeter around the focused component, and sufficient contrast between focused and unfocused states. Many WordPress themes set outline: none on focused elements to “improve visual design” - this completely removes the focus indicator and is a WCAG failure.

Fix in child theme CSS: Remove any outline: none or outline: 0 overrides. Set a visible focus style instead using :focus-visible for modern browsers while keeping :focus as a fallback.

ARIA: When to Use It and When Not To

ARIA (Accessible Rich Internet Applications) attributes add semantic meaning to elements that HTML alone does not convey. The first rule of ARIA: do not use ARIA when native HTML semantics work. A <button> element is already accessible. Adding ARIA to a div to make it behave like a button is always worse than using a real button.

Common ARIA Issues in WordPress

• Missing aria-label on icon buttons: Buttons that contain only an SVG icon or an icon font character need aria-label=”Close” or aria-hidden=”true” on the icon with a visually hidden text label.
• Incorrect role assignment: Some WordPress themes add role=”navigation” to non-nav elements or role=”main” to multiple elements. There should be only one main landmark per page.
• Missing aria-expanded on toggles: Accordion elements and mobile menu toggles must have aria-expanded=”true/false” that updates dynamically when the controlled content opens or closes.
• aria-label on the wrong element: aria-label on a div with no interactive role has no effect. It only works on interactive elements, landmark regions, and elements with explicit roles.

Skip Links

Skip links are the first focusable element on the page and allow keyboard users to skip past repeated navigation to reach the main content. WCAG 2.4.1 (A) requires a mechanism to skip repeated blocks.

WordPress themes should include a skip link that appears when focused. The standard implementation is a link pointing to #main-content (or whatever the main content container’s ID is) that is visually hidden until focused:

Most modern WordPress themes include skip links but they are often misconfigured - the href target does not match the actual main content ID, or the link is hidden with display:none (which removes it from keyboard access entirely) rather than a clip/position method that only hides it visually.

Test skip links by pressing Tab on your homepage. The first focus should be on the skip link. Press Enter to activate it - focus and scroll should jump to the main content area.

Form Labels and Error Identification

Every form input needs an associated label. The label must be programmatically linked to the input, not just visually near it. Contact Form 7, WPForms, Gravity Forms, and Ninja Forms all support accessible labels - but they must be configured correctly.

Label Association Methods

• for/id pairing: <label for=”email”>Email</label> <input id=”email”>. The label’s for attribute matches the input’s id.
• Wrapping label: Wrap the input inside the label element. Works but for/id is more explicit.
• aria-labelledby: Points to the ID of an existing element that serves as the label. Use when the label is not a <label> element.
• aria-label: Directly provides the label text. Use for inputs where a visible label cannot be placed (like a search field with a button).

Placeholders are NOT labels. Many WordPress form plugins use placeholder text as the only label, removing it when the user starts typing. This fails WCAG 1.3.1 and 3.3.2.

Heading Hierarchy

Screen reader users navigate pages by jumping between headings - this is their equivalent of scanning a page visually. Heading levels must follow a logical hierarchy: one H1 per page, H2 for main sections, H3 for subsections within H2 sections. Skipping heading levels (H1 to H3 with no H2) or using headings for visual styling instead of structure breaks this navigation.

Common WordPress heading hierarchy issues:

• Widget titles set to H2 even though they are in sidebars (disrupts content heading structure)
• Blog post titles set to H1 on archive pages (multiple H1s per page)
• Decorative text styled as H2 or H3 when it is not a section heading
• Post content starting with H3 because the post title is H1 and a subtitle is H2 in the theme template

Use the browser’s Accessibility Tree (DevTools - Elements - Accessibility) or the WAVE tool to visualize the heading structure on any page. The heading outline should read like a logical table of contents.

Accessibility Audit Summary Checklist

• Run axe DevTools scan on homepage, a post, and contact/checkout pages
• Check all color combinations for 4.5:1 contrast ratio (text) and 3:1 (large text)
• Verify all images have meaningful alt text (or empty alt=”” for decorative)
• Tab through the site - every interactive element reachable and focus visible
• Skip link present and working (first Tab press on homepage)
• All form inputs have associated labels (not just placeholders)
• Heading hierarchy logical (one H1, H2/H3 for structure)
• aria-expanded on accordion and menu toggles
• Icon buttons have aria-label or visible text
• No outline: none on :focus or :focus-visible
• Modal dialogs trap focus when open
• Error messages identify the specific field and describe what to fix