Testing

WordPress accessibility audit: where each issue comes from, and who fixes it

7 min read
Mikhail ShaymardanovWeb Quality and Accessibility Expert

The site's content team fixes some of the issues in a WordPress accessibility audit on its own, in the block editor and the Media Library. An image without alt text or a faint paragraph stays where the team published it, while a flaw in a theme template repeats on every page built from it. The page's code usually shows where each issue comes from, and so who fixes it.

From the audited pages to fixes that last


#Which pages of a WordPress site go into an accessibility audit?

An accessibility audit covers a sample of pages. On each one, the auditor checks WCAG success criteria, such as text that stays readable at double size. WCAG are the international guidelines behind the European standard EN 301 549.

For public sector sites, the method EU countries use to check them in depth lists the sample's pages. Where they exist, these are the home, login, sitemap, contact, help and legal information pages, the accessibility statement and the page for reporting a problem. It adds at least one page for each type of service or other main use, search included, and a downloadable document per type of service where applicable. Every step of a process, like a booking, goes in too. Then come pages that look different or hold another type of content, and finally random pages, at least 10% of the sample.

In WordPress, each type of page comes from a template, a layout the theme provides, so a template's flaw repeats on all its pages. Templates a plugin adds also appear in the Site Editor, and their pages join the sample.

Our demo, the Port Wenlow Tourist Office, is run by the town council, so EU law requires its website to be accessible. Its thirteen sample pages come from five templates.

Screenshot: the list of Shoreline theme templates in the WordPress Site Editor, from “All Archives” to “Single Posts”, each with its description.Marker 1. The Shoreline theme's “Pages” template, used by seven of the thirteen sample pages.
In Appearance > Editor > Templates, the Shoreline theme provides the sample's templates, and seven of the thirteen pages come from the “Pages” template alonemarker 1.
The Port Wenlow sample: thirteen pages, five templates
TemplateSample pages
Front PageHome
PagesContact
Legal notice
Accessibility statement
Site map
Choose a tour
Your details
The salt marshes
Single PostsSardine Festival
Salt Market (random)
Stargazing Night (random)
All ArchivesWhat’s On
Search ResultsSearch for “marsh”
Website accessibility audit: cost, quotes and how to choose an auditor

#How to tell where an accessibility issue comes from in WordPress?

The page's code usually points to the source of an issue. A test on a staging copy, a clone of the live site, confirms it.

#The same issue on every page: a theme template

On the Port Wenlow home page, it takes seven presses of Tab to reach “Choose a tour”, the first link in the content. With no skip link (a “Skip to content” link that jumps past the menu), keyboard users make that trip on every page. The report files this under success criterion 2.4.1, Bypass Blocks, and all thirteen of our pages fail it.

Click the demo, then press the key shown, or move on with “Next step”. Escape leaves the demo.
7 steps

On the Port Wenlow home page, focus goes through the title, the four menu links and “Book”: the content only starts at the seventh Tab, on “Choose a tour”.

WordPress can insert this link on its own: in a block theme, it does so whenever the template contains a <main> element, the main-content tag the home page lacks. Our copy running Twenty Twenty-Five, the default theme tagged “accessibility-ready”, shows “Skip to content” from the first Tab. The issue therefore comes from the templates of Shoreline, the theme bought for Port Wenlow, and the site's web agency fixes it.

How to add a skip link: the HTML code and the keyboard test

#A class named after the plugin

On “Choose a tour”, the three booking fields have only placeholder text, a hint like “Email” inside the field, and no label. A label is the name tied to the field in the code, the one a screen reader announces. Placeholder text doesn't replace it, and it vanishes once typing starts. The report files this under success criterion 3.3.2, Labels or Instructions.

The block's class gives the clue: after wp-block-, WordPress writes the name of the plugin, or theme, that registered the block. A block that ships with WordPress has no such name. Here the class names Portcall, whose script loads from /wp-content/plugins/portcall/. A developer can rename that class, so we checked with Twenty Twenty-Five and Portcall active. The fields still have no label: the code comes from the plugin.

Screenshot: the DevTools Elements panel open on the “Choose a tour” page, with the first field of the booking form selected.Marker 1. The block's tag, whose class wp-block-portcall-booking names the Portcall plugin. Marker 2. The form's first field, with only its placeholder “Tour date (dd/mm/yyyy)”.
In the DevTools Elements panel, the block's class names the Portcall pluginmarker 1, and the date field has only its placeholder, with no label in front of itmarker 2.

#An issue on a single page: the content

On “Sardine Festival”, the poster, a WordPress Image block, has empty alt text (success criterion 1.1.1). Alt text is read in place of the image when someone can't see it, and only the poster gives the festival's date and place.

On “The salt marshes”, a paragraph's has-pearl-gray-color class gives away a color picked in the block's settings. That gray has a contrast ratio of 2.11:1 on white, too faint for someone with low vision (contrast thresholds, success criterion 1.4.3). Such a class can also come from a template, but neither this gray nor this empty alt text shows up on other pages from the same templates. Both are the content team's to fix.


#Who fixes each issue in the accessibility audit report, and where?

The web agency fixes the template once, in a child theme. A plugin gets fixed through its settings, a filter or by its vendor. The content team fixes its own pages.

#The theme template: once, in the child theme

The fix is a single attribute: the Group block that holds the content becomes <main>, through “HTML element” (in the “Advanced” section) or "tagName":"main" in the template file. On the demo, all thirteen pages got the skip link once the six Shoreline templates were fixed.

These files go in a child theme, which inherits from Shoreline: a file named after a Shoreline template replaces it, and Shoreline keeps getting its updates. In a classic theme, without block templates, the link comes from the theme, and it too gets fixed in a child theme.

Avoid

Screenshot: the Port Wenlow header, with the navy focus outline around the title “Port Wenlow”.Marker 1. The title “Port Wenlow”, which gets focus on the first press of Tab.
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</div>
<!-- /wp:group -->

Correct

Screenshot: the “Skip to content” link, light gray, at the top left of the Port Wenlow header, inside the focus outline.Marker 1. The “Skip to content” link that WordPress adds, shown on the first press of Tab.
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->
On the first Tab, the Shoreline template sends focus to the title “Port Wenlow”marker 1; with the main element in the child theme's template, WordPress shows “Skip to content” firstmarker 1.

Before writing these files, open Appearance > Editor > Templates. A template edited there is a database copy, which WordPress picks over the child theme's file. Only those templates offer “Reset”, which deletes the copy. Either way, the fixed template no longer follows Shoreline's changes: check it after every theme update.

#The plugin: through its settings, or its vendor

A fix typed into a plugin's files disappears with the next update. The simplest route is a setting in the plugin. Next comes a filter in the child theme or, if the plugin provides one, a template override. The render_block_portcall/booking filter rewrites the block's HTML on the live site. Last comes writing to the vendor, or switching plugins. Portcall has no setting for its labels, and the agency chose to write to its vendor: the criterion on labels keeps failing until the form gets fixed.

#The page: the content team, in the editor and the Media Library

A public body's accessibility statement, which reports its site's compliance status, may only say “fully compliant” when every requirement is met without exceptions, and it lists each requirement that isn't. A criterion failed on a single page of the sample is already such an exception. On the statement, an issue the content team created on a single page therefore costs as much as a theme issue present everywhere.

On “The salt marshes”, the gray paragraph gets the theme's color back with “Clear”, under Typography > Color. Its contrast on white rises to 15.97:1. For the “Sardine Festival” poster, filling in alt text in the Media Library doesn't update an image already inserted. On our demo, the Media Library has that text, yet the post keeps alt="". The library's text goes to images the theme inserts itself, like the featured image. The post's own text goes in the Image block (what to write there).

Screenshot: the WordPress editor on the “Sardine Festival” post, with the poster selected and, in the Image block settings sidebar, the “Alternative text” field filled in.Marker 1. The Image block's “Alternative text” field, filled in with the festival's name, date and place.
In the “Sardine Festival” post, the Image block's “Alternative text” fieldmarker 1 gets what the poster says: the festival's name, date and place.

At Port Wenlow, the agency fixed the Shoreline templates once, and the form is waiting on Portcall's vendor. The content team got two criteria to pass by fixing its own issues, right where it had published them. WordPress had even warned it about the gray: in the paragraph's settings, it shows “This color has poor contrast against the background.” The page went live anyway.

Website accessibility statement: from the audit report to a published page

After every update of WordPress, the theme or a plugin, the agency runs an Includdy scan on one page per template and on the booking form. It then compares the issues with the previous list. Every new page from the content team gets the same scan. For each issue, Includdy also produces a test plan the content team can run again.


Share this article

Frequently asked questions

Not on its own. The European Commission says accessibility overlays, the toolbars and widgets added on top of a site, are “not an appropriate solution” when they don't make the site itself meet the standard. It advises fixing issues at their source.

The audit judges the pages in the sample as the theme, the plugins and the content produce them.

No. The theme review handbook states that the “accessibility-ready” tag doesn't mean the theme meets WCAG at level AA. It means the theme reaches the minimum standards WordPress's theme review team has set, such as a skip link, labeled form fields or sufficient contrast. The handbook adds that WCAG measures content and can't be applied to a theme alone.

The theme's templates, the plugins and the pages the content team publishes still need an audit, as on any site. The Shopify Theme Store shows no accessibility label at all: see what Shopify checks on a theme, and what's left to test.

Public sector sites, and businesses that sell certain services to consumers. The Web Accessibility Directive covers public sector bodies: the state, regional and local authorities, bodies governed by public law, and certain associations of these. It leaves out public service broadcasters, and NGOs that provide neither essential services nor services for people with disabilities. A public body publishes the result of its audit, done in-house or by a third party, in its accessibility statement.

Since June 28, 2025, the European Accessibility Act has also covered a list of services sold to consumers, among them online stores, consumer banking and e-books. Microenterprises that provide services are exempt: fewer than 10 people, and annual turnover or a balance sheet total of €2 million or less. Each country writes both directives into its own law, and for public sector sites it may go further.