WordPress Accessibility: Common Pitfalls & Fixes

WordPress gives developers a head start with accessibility—but it’s just that: a start. While the platform includes solid foundations like semantic markup and keyboard-friendly admin features, building an experience that works for everyone still requires thoughtful decisions on our part. As developers, we’re in a unique position to go beyond the basics, spotting the small oversights that can create big barriers for users.

In this guide, we’ll walk through some of the most common accessibility missteps we see in WordPress projects—along with practical fixes you can implement right away. Whether you’re refactoring an old theme or launching something new, these insights are meant to help you create experiences that are not just compliant, but genuinely inclusive.

Misuse of Heading Structures for Visual Styling

It’s easy to reach for <h2> or <h3> tags to style text because they’re built into most WordPress themes with bold and larger font sizes. But when headings are used purely for visual emphasis—not structure—you end up distorting the page’s semantic outline.

Why It Matters

Screen reader users often rely on heading navigation to scan and jump between sections. If headings are skipped, out of order, or misused, the page becomes harder to understand, and key content may get missed entirely.

How to Fix It

Use CSS for Styling: Apply styles using classes or inline styles, not heading tags. In Gutenberg, you can use blocks with custom styles or reusable blocks instead of jumping heading levels.
Follow a Logical Heading Hierarchy: Begin with one <h1> per page (usually the title), then use <h2> for top-level sections, <h3> for subsections, and so on.
Audit Your Work: Use tools like WAVE or the Google Lighthouse Accessibility Report to evaluate your heading structure and flag potential misuses before they go live.

Overreliance on Theme Defaults for Color Contrast

Many developers trust their WordPress theme’s default color scheme to do the heavy lifting—but while a palette may look good visually, it doesn’t mean it’s accessible. Default colors often fail to meetWCAG 2.1 AA standards, especially for body text and buttons.

Accessibility Risk

Poor color contrast is a major barrier for users with low vision or color blindness. If your text blends into the background, you’re excluding readers—sometimes without realizing it.

Practical Fixes

Test Contrast Ratios: Use WebAIM’s Contrast Checker or the Color Contrast Analyzer to validate text against its background.
Override Theme Defaults: Most modern themes offer customization options via the Customizer or Full Site Editing. Make small adjustments—lighten text, darken backgrounds—to meet or exceed the 4.5:1 minimum contrast ratio.
Offer User Controls: Consider giving users the ability to switch to high-contrast mode with plugins like “WP Accessibility.” This gives more control to your users while improving inclusivity.

Improper List Markup Practices

It’s not unusual to see developers create the appearance of a list using <div> tags, line breaks, or other non-semantic methods—especially in custom blocks or page builders commonly used in WordPress.

Why It’s a Problem

Screen readers rely on semantic tags like <ul>, <ol>, and <li> to announce that a list exists, how many items are in it, and how items relate to each other. Without this structure, users lose context.

Best Practices

Use Native List Markup: If it’s a list—code it as a list. Use <ul> for unordered lists and <ol> for ordered ones. Wrap each list item in <li>.
Handle Nesting Thoughtfully: For sub-lists, nest another <ul> or <ol> inside an <li>. Screen readers will announce the nested structure properly.
Test Your Output: Run accessibility audits or inspect the DOM to ensure list structures are coded semantically, especially when using custom Gutenberg blocks or page builders.

Neglecting Contextual Relevance in Alt Text

WordPress auto-generates alt text from image file names if authors don’t supply one. That’s how you end up with images labeled “IMG_4829.jpg”—which isn’t helpful to anyone.

Why It Matters

Alt text should describe why the image is there, not just what it looks like. If the image provides important context, instructions, or emotion, a generic label fails users who rely on screen readers.

What Developers Can Do

Write Purpose-Driven Alt Text: If the image is showing a concept, outcome, or step in a process, describe that context directly. For example, “Screenshot of the plugin settings menu with Accessibility Mode enabled.”
Avoid Phrases Like “Image of…” Screen readers already announce the presence of an image. Jump straight into the relevant description.
Use Empty Alt for Decorative Images: For visuals that are purely aesthetic and add no informational value, use alt="" so assistive tech knows to skip it entirely.

Overuse and Misapplication of ARIA Attributes

ARIA is a powerful toolset—but like any tool, misuse can cause more harm than good. Adding roles and attributes without understanding their implications can break screen reader behavior or clutter the accessibility tree.

The Real Cost

Improper ARIA use can confuse assistive technologies, interfere with default behaviors, and even make components harder—not easier—to use. Overengineering is just as dangerous as under-engineering.

Smarter ARIA Use

Favor Native HTML First: If you’re building a checkbox, <input type="checkbox"> with an associated <label> is far more reliable than using a <div> with ARIA roles and states.
Use ARIA Only When Required: If you’re building a custom interactive widget (like a tabbed interface or menu), consult the ARIA Authoring Practices Guide. Choose correct roles and manage keyboard interactions accordingly.
Test Your Implementation: Use screen readers like NVDA or VoiceOver to verify that ARIA is behaving as expected. Pay attention to focus, announcements, and interaction patterns.

Overlooking Keyboard Navigation and Focus Management

Many developers unintentionally design for mouse users first. But for users relying on keyboards—whether due to preference, disability, or temporary injury—keyboard accessibility is critical.

Key Accessibility Concerns

No Visible Focus Indicators: Removing browser outlines with outline: none; without providing alternatives leaves users lost.
Custom Components Not Keyboard-Aware: Modals, sliders, dropdowns, and carousels built from scratch often lack proper keyboard event handling and focus management.

Developer-Friendly Fixes

Ensure Focus Visibility: Style focused elements clearly using CSS, like :focus { outline: 2px solid #000; }. Customize this to match your theme, but don’t remove it entirely.
Handle Keyboard Events: For custom components, add keydown or keyup listeners to handle Enter, Escape, and Arrow keys appropriately. Don’t rely on click events alone.
Do Keyboard-Only Testing: Regularly test your site using only the keyboard. Tab through each interactive element and verify focus moves logically, without skipping important controls.

What True Accessibility Looks Like in WordPress

Accessibility isn’t a checklist—it’s a mindset. When we write clean, semantic code, ensure visual clarity, and support every way a user might interact with our sites, we’re not just doing right by WCAG—we’re doing right by our users. The real goal is to build experiences that work for everyone, without assumptions about how people navigate the web.

As WordPress developers, we have powerful tools and a vibrant ecosystem at our disposal. Let’s use them with care and intention. Keep testing, stay curious, and don’t hesitate to dig deeper. And if you’re looking to strengthen your accessibility efforts, 216digital offers ADA compliance briefings tailored to development teams. We’re here to support your work—because inclusive development is better development.