WordPress Accessibility: Theme/Plugin Pitfalls + Fixes

Choose the Right Foundation (Themes)

Common Pitfalls

• “Pixel-perfect” themes utilizing divs for everything with no headings or landmarks.

• Typography and buttons with low contrast.

• Fancy menus or sliders with broken keyboard focus.

Solutions

• Begin with a theme that is accessibility-ready or a lean, semantic base.

• Ensure there is one H1 per template, proper H2/H3, and defined landmarks (header, nav, main, footer).

• Incorporate styles for visible focus and AA contrast tokens from the start.

Include Skip Link (insert into header.php)

<a class="skip-link screen-reader-text" href="#main">Skip to content</a>

Blocks & Content (Gutenberg)

Common Pitfalls

• Heading blocks used for layout styling (e.g., H3 as a large label), resulting in no logical order.

• Images lacking or having vague alt text.

• Link text such as “click here”.

Solutions

• Educate editors: use one H1 followed by logical H2/H3 structures.

• Complete the Alt Text field; aim for 5–15 words that serve a purpose.

• Develop meaningful link text like “View pricing” or “Download brochure”.

• Utilize the List and Table blocks for actual lists and tables—avoid faking with line breaks.

Adjustable tools can enhance readability with Text Options, Reading Ruler, Dictionary, and Light/Dark/Colour Modes, but remember: correct content structure comes first.

Navigation & Menus

Common Pitfalls

• Mega menus created using divs, lacking keyboard support.

• Hover-only functionality for open/close, with Esc not functioning to close.

Solutions

• Implement WordPress menus as proper links and toggle submenus using buttons.

• Ensure: Tab initiates the menu, Esc closes it, and focus returns to the origin trigger.

• Replicate hover styles with :focus-visible.

Forms (Contact, Checkout, Search)

Common Pitfalls

• Labels only as placeholders; error messaging not accessible.

• Validation per keystroke that disrupts typing.

Solutions

• Use visible <label for> for each field; employ <fieldset><legend> for groups.

• Conduct validation on blur + submit; direct focus to the first error; connect messages via aria-describedby.

• Include autocomplete attributes (email, address-line1, postal-code, etc.).

Media (Images, Video, PDFs)

Common Pitfalls

• Decorative images with non-empty alt attribute result in noise for screen readers.

• Lacking captions or transcripts.

• PDFs uploaded without tags or reading order.

Solutions

• For decorative images, use an empty alt attribute (alt="").

• Offer captions for video and transcripts available on the web page.

• For PDFs, export with tags and include type and size information (“PDF, 1.2 MB”).

• Opt for HTML pages for dynamic content; use PDFs for downloads.

Plugins (The Silent Breaker)

Common Pitfalls

• Visual builders and marketing plugins that add unlabelled controls or disrupt focus.

• Carousels or sliders that auto-advance without pause.

Solutions

• Test plugins on a staging site with keyboard and screen-reader assessments.

• Replace div-based controls with buttons/links; employ ARIA elements only as needed.

• Facilitate pause/stop options for any moving content and respect reduced motion settings.

Adjustable’s Page Options allow users to hide images/animations, highlight links, or scale pages, easing challenges from third-party UI when in use.

Performance & Stability (Core Web Vitals)

Common Pitfalls

• Layout shifts caused by late-loading fonts or ads.

• Oversized images and bulky script bundles.

Solutions

• Pre-size images; deliver them in modern formats; lazy-load media that are not essential.

• Reserve space for embeds or ads; utilize font-display: swap.

• Maintain lean plugins; eliminate those that are unnecessary.

Focus Management & Traps (Modals, Drawers)

Common Pitfalls

• Modals that don’t trap focus or fail to return focus to the trigger.

• Off-canvas menus that remain tabbable even while hidden.

Solutions

• Upon opening: move focus inside, trap it, and upon closing return to the trigger.

• Conceal off-canvas content using inert or aria-hidden, and remove from the Tab order.

Minimal CSS for visible focus (enqueue once)

:root { --focus-ring: 2px solid #111318; }
:where(a,button,input,select,textarea,[role="button"]):focus-visible {
  outline: var(--focus-ring); outline-offset: 3px;
}

International & Reading Support

• If serving multiple languages, confirm lang attributes are accurate and switch content accordingly.

• Adjustable includes Language Translation and Text to Speech, assisting global and low-vision users in interacting with your content without duplicating pages.

Governance: Prevent Regressions

• Incorporate a Definition of Done: headings, labels, focus, contrast, keyboard, motion.

• Conduct a quick scan + keyboard pass on staging before launching.

• Record editor guidelines in a one-page style guide accessible within WordPress.

• Arrange for quarterly reviews of templates and high-traffic posts.

Quick Testing Routine (10–12 Minutes)

1. Keyboard Pass (5 min): Navigate through nav → content → forms → dialogs. Avoid traps; ensure focus is always visible.

2. Screen Reader Skim (3–4 min): Check title, headings, links list, form labels, and error notifications.

3. Mobile Spot Check (2–3 min): Ensure target sizes, reflow at 320 px, zoom functionality; sticky bars should not impede focus.

Copy-Paste Checklist (Markdown)

How Adjustable Contributes (Post-Structural Fixes)

• Accessibility Profiles provide quick and user-friendly presets.

• Text Options and Page Options (scaling, hide images/animations, highlight links) reduce friction on dense pages.

• Reading Ruler, Cursor Adjustment, and Screen Mask to enhance focus on lengthy posts or forms.

• Text to Speech and Language Translation help expand reach and understanding.

• Dictionary for immediate definitions in complex content.

• Light/Dark/Color Modes to satisfy user preferences.

• Customizable placement for toolbar or widget to match your theme design.

Try Adjustable

FAQs

Are “Accessibility-Ready” Themes Enough?
They are a great starting point but not a complete solution. You must still verify headings, focus, contrast, and component functionality.

Which WordPress Plugins Cause the Most Issues?
Any plugins that inject interactive UI (menus, sliders, popups, form builders). Test installations and updates with keyboard and a brief screen-reader review.

Do Toolbars Ensure Site Compliance?
Toolbars like Adjustable don’t replace structural fixes. They enhance comfort, control, and reach—increasing engagement while maintaining accessible templates and content.

How Can I Prevent Editors from Compromising Accessibility?
Supply a one-page editor guide (headings, links, alt text), include a pre-publish checklist, and conduct monthly reviews of popular posts.

Next Steps

• Evaluate your active theme with the checklist and correct tokens, headings, and focus.

• Assess your top 10 plugins on staging; replace or modify any failing keyboard checks.

• Implement Adjustable to enhance readability, language accessibility, and task completion as you continue to iterate.

• Recommended Reads: Accessible Forms, Keyboard Accessibility, Color Contrast Accessibility.