WordPress Accessibility: Fixing Themes, Blocks and Forms

Where WordPress accessibility faults start

A finding in the report is just a symptom on one page. Before changing anything, decide which part of WordPress wrote the faulty HTML, because that decides where the fix belongs and whether it will survive the next update.

Most sites find that a few template-level faults generate the bulk of the report, because the header, footer and sidebar appear on every URL. Fixing those first makes the remaining list short enough to deal with properly.

Tracing a finding to the theme, a plugin or content

WordPress adds tell-tale class names to almost everything it outputs, which makes tracing quick. Right-click the failing element, choose Inspect, and look at the classes on it and its parents:

• wp-block- classes, such as wp-block-image or wp-block-cover, mean the markup came from a core block. The fix is in the editor for that post, or in the theme's styles if it is a colour or focus problem.
• elementor-, et_pb_ (Divi) or fl- (Beaver Builder) classes point to a page builder widget. Find the widget on the page and check its settings before writing any code.
• wpcf7, gform_, wpforms- or nf- belong to Contact Form 7, Gravity Forms, WPForms and Ninja Forms respectively.
• A class you do not recognise near the end of the page is usually a plugin. Searching the class name with the plugin's name, or deactivating plugins one at a time on staging, will identify it.
• Nothing obvious on a header, footer or sidebar element usually means the theme. For a block theme, open Appearance, Editor, then the template part; for a classic theme, the fault is in files such as header.php or sidebar.php.

Themes: what accessibility-ready does and does not mean

The WordPress.org theme directory has an accessibility-ready tag. Themes carrying it have been reviewed against the WordPress accessibility team's theme requirements, which cover things like a working skip link, visible keyboard focus, sufficient contrast in the default colours, correctly structured headings, labelled form controls and menus that work with a keyboard. The recent default themes have carried the tag, and several popular free themes do as well; check the tag on the theme's directory page rather than relying on a sales page.

The tag is a good starting point, but it describes the theme as shipped. It does not cover:

• colours you change in the Customiser or in Global Styles after installing;
• demo content, starter templates and patterns imported from the theme author;
• anything a page builder draws inside the content area;
• plugins, and the content your editors write.

Premium themes sold on marketplaces have no equivalent review, so test them yourself. If a theme hides focus outlines, has no skip link and codes the logo as a heading, it is often less work to move to a well-built theme than to patch it through a child theme for years.

Block themes and the automatic skip link

For block themes, WordPress adds a "Skip to content" link automatically, pointing at the main element of the template. If your block theme has no skip link, the usual reason is that the template uses a plain Group block instead of one set to the main HTML element. Select the Group that wraps the content in the Site Editor, open Advanced in the block settings and set the HTML element to <main>. Classic themes must provide their own skip link in header.php.

Code for common theme fixes

Make theme changes in a child theme or in the Additional CSS panel, never in the parent theme's files, or the next theme update will wipe them. These examples cover the three theme faults that come up most often.

Restore a visible focus outline

/* Appearance, Customise, Additional CSS (classic themes)
   or Styles, Additional CSS in the Site Editor (block themes) */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible,
.wp-block-button__link:focus-visible {
  outline: 3px solid #1a4fd0;
  outline-offset: 2px;
}

Pick an outline colour with at least 3:1 contrast against both the element and the background around it. If the site has a dark header, you may need a second rule with a light outline for links inside it.

Add a skip link to a classic theme

<!-- child theme header.php, straight after wp_body_open() -->
<a class="skip-link screen-reader-text" href="#primary">Skip to content</a>

<!-- and make sure the content wrapper has that id -->
<main id="primary" class="site-main">

WordPress core already provides a screen-reader-text class in most themes that hides text visually and shows it again on focus. If yours does not, add a rule that brings the link into view when it receives focus, otherwise sighted keyboard users will tab onto an invisible link.

Stop the site title being an h1 on inner pages

<?php if ( is_front_page() ) : ?>
  <h1 class="site-title"><?php bloginfo( 'name' ); ?></h1>
<?php else : ?>
  <p class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a></p>
<?php endif; ?>

Many older themes print the site name in an h1 on every URL, so each post starts with the same heading and the real post title becomes a second h1. Keeping the site name as a paragraph on inner pages lets the post or page title be the one main heading.

Block editor habits that cause most content findings

• Alt text lives in the block, not only the media library. When you insert an image, the block copies the alt text from the media library at that moment. Editing the alt text in the library later does not change posts where the image is already used, so fix old images inside each post, in the Image block's settings sidebar.
• Empty alt text is correct for decoration. If an Image block's alt text is left empty, WordPress outputs alt="", which tells screen readers to skip it. That is right for dividers and mood photos, and wrong for a chart, a product or an image that is also a link.
• Use the Outline view for headings. In the editor, open the Document Overview (the list icon in the top toolbar) and choose Outline. It lists every heading with its level and flags levels that are skipped, which is quicker than checking each Heading block.
• Choose heading levels for structure. If a heading looks too large, change its font size in the block's Typography settings rather than dropping it to a lower level.
• Watch Cover blocks. Text laid over a photo often fails contrast in some parts of the image. Raise the Overlay opacity, pick a darker overlay colour or move the text out of the image.
• Give Buttons distinct text. Three Buttons blocks that all say "Learn more" sound identical when a screen reader lists links. Write "See our pricing" or "Read the case study" instead.
• Respect contrast warnings. When you pick text and background colours in the block settings, the editor shows a warning if the pair may be hard to read. Do not ignore it.

Page builders: settings to check before writing code

Page builders can produce accessible output, but their defaults and demo templates often do not. Most of the fixes are settings rather than code:

Builders change their widget markup between releases, so test after major updates. If a widget cannot be made accessible through its settings, replace it with a core block or a simple HTML widget rather than fighting it with CSS.

The fix, step by step

Accessibility plugins and overlays

Two quite different kinds of product are sold as WordPress accessibility plugins, and it matters which one you install.

• Helper plugins that change your markup. These add things the theme is missing, such as a skip link or a language attribute, or add prompts in the admin so editors fill in alt text. They make real changes to the HTML every visitor receives. They are useful as a stopgap, but check each setting and understand what it does; a better theme often makes several of them unnecessary.
• Checker plugins that report in the admin. These scan posts as you save them and warn about missing alt text or skipped headings. They help editors catch mistakes, but like any automated test they cannot judge whether alt text is accurate.
• Overlay toolbars. These add a floating button offering larger text, contrast modes or "screen reader" features on top of the site. They do not repair unlabelled fields, keyboard traps or wrong headings in the underlying code, and they can clash with the assistive technology disabled visitors already use. Fix the site instead.

Keeping it fixed

• Test on staging after updates. Theme and page builder updates regularly change markup. Re-run the checker on your template URLs before pushing an update live.
• Limit who can change global colours. Global Styles and Customiser colour changes affect every page at once. Keep that permission with the people who understand contrast.
• Review new plugins before activating. Pop-ups, sliders, chat and cookie plugins are the most common source of new keyboard traps. Test one on staging with a keyboard before adding it to the live site.
• Train editors on four things. Alt text, heading levels, link text and not using colour alone. That covers most of the content findings a WordPress site produces.
• Keep the accessibility statement current. Update it when you fix known issues or add new features.