Testing & Tools

Fixing and Rechecking Accessibility Issues on a WordPress Client Site

This walkthrough follows one page of a WordPress site from first scan to recheck. The site is a demo we built for this article on 08.11.26, not a client site: WordPress 6.8.3, the default Twenty Twenty-Five theme, and a homepage with the content an agency typically inherits. Every finding and measurement below comes from that site. The checks ran with axe-core 4.13.0, the rules engine AllyProof uses alongside HTML_CodeSniffer, so an AllyProof scan of the same page can report additional findings.

What the first scan found

Three issue groups, all rated serious:

Finding	Where	WCAG
Text contrast 2.52:1 (needs 4.5:1)	Intro paragraph with a custom grey text colour (#a3a3a3 on white)	1.4.3
Link with no accessible name	Linked logo image whose alt text was left empty	2.4.4, 4.1.2
List contains a list	Header navigation: the default Page List fallback rendered a ul directly inside the navigation ul	1.3.1

The third one was not planted. It came from WordPress's default header on a site where nobody had built a menu yet, which describes many freshly handed-over client sites.

What the scan could not see

Two problems on the same page passed every automated rule:

• A meaningful photo marked as decorative. When an editor leaves the Image block's alternative text empty, WordPress outputs alt="". That tells screen readers to skip the image. For a photo of the clinic's reception, that hides content - but only a person can decide whether an image carries meaning, so no rule flags it.
• A placeholder used as the only label. The pasted newsletter embed had an email field with placeholder="Your email" and no label. axe-core accepts the placeholder as the field's accessible name, so the rule passes, yet the hint disappears as soon as someone types. A visible label is the dependable fix.

Recording these as manual-review items alongside the automated findings keeps the handoff honest: the scan result is a starting list, not the full list.

The fixes, in the WordPress editor

1. Contrast. Select the paragraph, open Styles > Color > Text and choose a darker colour. We used #525252, which measures 7.81:1 on white. Prefer a colour from the theme palette so later edits stay consistent.
2. Linked logo. Select the Image block and fill in Alternative text. For an image that is a link, describe where it goes: "About Riverside Dental".
3. Reception photo. Add alternative text that says what the image shows: "Reception desk at Riverside Dental". If an image is genuinely decorative, leaving it empty is correct - make that a deliberate choice, not a default.
4. Navigation. Open the Site Editor, select the header Navigation, then select the Page List inside it and convert it into individual links (the editor offers this as an edit action on the Page List block; wording varies between versions). The menu then renders one list of links.
5. Newsletter embed. In the Custom HTML block, add a visible <label for="newsletter-email">Email address</label>, give the input the matching id, and add autocomplete="email". If the embed comes from a mailing provider, check whether its form builder offers a label setting first, so the fix survives a re-paste.

The recheck

The same axe-core run after the changes returned no automated findings, at 1280 pixels and at 375 pixels wide (where the theme collapses the navigation). The two manual-review items were resolved by the editor changes in steps 3 and 5.

What still needs a person before telling the client the page is done:

• Tab through the page: every link, the menu toggle and the form are reachable, the focus indicator is visible, and the order makes sense.
• Open and close the mobile menu with the keyboard and a screen reader.
• Read the alt text aloud in context: does it say what a sighted visitor gets from the image?
• Submit the newsletter form empty and with an invalid address, and check that the error is announced and explained.

Running the same loop with AllyProof

The free single-page test shows the automated findings for one URL. After deploying a fix, use Run a fresh scan on the result: a repeat test within 24 hours otherwise shows the cached result, and that would not be a recheck. For a client site you maintain, add it as a site: each later scan - manual, or scheduled (monthly on Free, weekly on Business) - marks issues it no longer finds as resolved, so the history shows which fixes landed. Business is EUR 35 per site per month, or EUR 336 per site per year, with a 14-day trial for eligible accounts (payment method required; renews until cancelled).

For the client update, send three things: what was found and fixed with dates, what the automated recheck showed, and which manual checks are complete or still open. That is more useful to a client than a score, and it does not promise conformance a scan cannot establish.

Common questions

Why does WordPress output alt="" when I leave the alt text empty?

An empty alt attribute tells assistive technology the image is decorative and can be skipped. That is correct for decoration but hides a meaningful image. Automated tools cannot tell the difference, so they do not flag it.

Why does the default WordPress navigation fail the axe list rule?

When no menu has been built, the Navigation block in block themes falls back to a Page List. In this example that produced a ul element directly inside another ul. Converting the Page List into individual links removed the nested list.

Does a clean rescan mean the WordPress site is accessible?

No. It means the automated rules that ran found nothing on the pages and states tested. Keyboard operation, focus visibility, screen reader output and the quality of alt text still need a person to check them.