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


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.
Marker 1. The Shoreline theme's “Pages” template, used by seven of the thirteen sample pages.| Template | Sample pages |
|---|---|
| Front Page | Home |
| Pages | Contact Legal notice Accessibility statement Site map Choose a tour Your details The salt marshes |
| Single Posts | Sardine Festival Salt Market (random) Stargazing Night (random) |
| All Archives | What’s On |
| Search Results | Search 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.
“Port Wenlow”, the site title, with no “Skip to content” link before it.
“Tours”, the first menu link.
“What’s On”.
“The salt marshes”.
“Contact”.
“Book”, the header button.
Focus finally enters the content, 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.
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)”.#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
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
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 -->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).
Marker 1. The Image block's “Alternative text” field, filled in with 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.


