Your WordPress Theme Is the Problem — 5 Fixes That Prevent 80% of ADA Demand Letters

Why WordPress Sites Are High-Value Targets

The ADA lawsuit machine is algorithmic. Plaintiff firms run automated scanners — the same axe-core engine that ADAflags uses — against millions of URLs. WordPress is an attractive target for three reasons:

1. Volume. 43% of the web means hundreds of millions of sites, the majority of them small businesses without legal counsel.
2. Theme monoculture. A small number of themes — Astra, OceanWP, GeneratePress, Divi, Elementor + Hello — power enormous chunks of WordPress. A violation in a popular theme's default configuration creates a predictable pattern that scanners find at scale.
3. Page builder output. Elementor and Divi generate HTML that fails accessibility standards by default. A site built with either builder has a known fingerprint of violations before the developer writes a single line of custom code.

The 5 Violations in Your WordPress Theme — With Exact Fixes

Fix 1: Featured images and media library missing alt text

WordPress stores alt text in the media library (post_meta key _wp_attachment_image_alt). When merchants add images without filling in alt text, the alt attribute outputs as empty — a WCAG 1.1.1 failure on every post and page.

Two-part fix: enforce alt text at the template level, and add a media upload reminder for your team.

// Fallback: if featured image has no alt text, use the post title.
// Add to functions.php or a site-specific plugin.
function adaflags_featured_image_alt( $attr, $attachment, $size, $icon ) {
  if ( empty( $attr['alt'] ) ) {
    $post_id = get_post_thumbnail_id();
    $alt     = trim( strip_tags( get_post_field( 'post_title', $post_id ) ) );
    if ( empty( $alt ) ) {
      // Last resort: use parent post title
      $alt = trim( strip_tags( get_the_title() ) );
    }
    $attr['alt'] = esc_attr( $alt );
  }
  return $attr;
}
add_filter( 'wp_get_attachment_image_attributes', 'adaflags_featured_image_alt', 10, 4 );

// Show an admin notice when an attachment has no alt text set.
function adaflags_check_media_alt() {
  $screen = get_current_screen();
  if ( ! $screen || $screen->base !== 'upload' ) return;
  $images = get_posts([
    'post_type'      => 'attachment',
    'post_mime_type' => 'image',
    'posts_per_page' => -1,
    'meta_query'     => [[
      'key'     => '_wp_attachment_image_alt',
      'compare' => 'NOT EXISTS',
    ]],
  ]);
  if ( ! empty( $images ) ) {
    echo '<div class="notice notice-warning"><p><strong>ADA Risk:</strong> '
       . count( $images )
       . ' image(s) in your media library are missing alt text. <a href="/wp-admin/upload.php">Fix them</a>.</p></div>';
  }
}
add_action( 'admin_notices', 'adaflags_check_media_alt' );

Fix 2: Low-contrast theme defaults (Astra, OceanWP, GeneratePress)

The three most popular WordPress themes all ship with default color palettes that fail WCAG 1.4.3. The violations aren't a bug — they're design choices that look fine on a monitor but fail the 4.5:1 minimum contrast ratio required for body text.

Common failures by theme:

• Astra: Default link color #0274be on white = 4.05:1 (fails). Body text meta in #999 = 2.85:1 (fails). Recommended fix: change global link color to #0060a0 (5.1:1).
• OceanWP: Default subheading and widget title color #888 = 3.54:1 (fails). Footer text #777 on dark footer background frequently fails. Recommended fix: set body text to #333, meta text to #555.
• GeneratePress: Navigation link hover color in some presets falls below 3:1 for large text. Check your theme's "Colors" settings and verify every color token against a contrast tool.

/* Astra: fix default link and meta text contrast */
:root {
  --ast-global-color-0: #0060a0; /* links: 5.1:1 on white */
}
.entry-meta, .posted-on, .byline, .cat-links {
  color: #555555; /* 7.46:1 — was #999 (2.85:1) */
}

/* OceanWP / GeneratePress: general safe meta color */
.entry-meta, .post-meta, .widget-title { color: #595959; } /* 7.0:1 */
footer, .footer-widgets { color: #d4d4d4; } /* on dark bg: ensure passes */

Fix 3: Elementor and Divi popups creating focus traps

Elementor Pro's popup widget and Divi's Modal module both have the same structural problem: when a popup opens, keyboard focus is not moved into the popup, and the modal is not given role="dialog" or aria-modal="true". This means screen reader users are still navigating the background page — and the popup appears invisible to assistive technology.

For Elementor popups, the fix requires a small JavaScript snippet added to your theme's functions.php or a custom JS file:

// Enqueue custom JS that fixes Elementor popup accessibility
function adaflags_elementor_popup_a11y() {
  if ( ! class_exists( '\\Elementor\\Plugin' ) ) return;
  wp_add_inline_script( 'elementor-frontend', '
    document.addEventListener("DOMContentLoaded", function () {
      jQuery(document).on("elementor/popup/show", function (e, id, instance) {
        var popup = document.getElementById("elementor-popup-modal-" + id);
        if (!popup) return;
        popup.setAttribute("role", "dialog");
        popup.setAttribute("aria-modal", "true");
        popup.setAttribute("aria-label", "Dialog");
        // Move focus into the popup
        var firstFocusable = popup.querySelector(
          "a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex=\'-1\'])"
        );
        if (firstFocusable) firstFocusable.focus();
      });
      jQuery(document).on("elementor/popup/hide", function () {
        // Return focus to trigger element if tracked
        if (window._adaLastFocused) window._adaLastFocused.focus();
      });
      document.addEventListener("click", function (e) {
        if (e.target.closest("[data-elementor-open-lightbox]")) {
          window._adaLastFocused = e.target;
        }
      });
    });
  ' );
}
add_action( 'wp_enqueue_scripts', 'adaflags_elementor_popup_a11y' );

For Divi modals, enable Divi's built-in accessibility mode under Theme Options → Accessibility → "Improve Module Accessibility" and "Keyboard Navigation". This is a setting, not code — but it's off by default.

Fix 4: Missing skip-to-content link

A skip-to-content link lets keyboard and screen reader users jump past your navigation directly to the main content. WCAG 2.4.1 (Bypass Blocks) requires a mechanism to skip repeated navigation. Most WordPress themes either omit this entirely or implement it incorrectly (hidden via display:none, which removes it from focus order).

<!-- Skip to content: visible on focus, hidden otherwise -->
<a href="#main-content"
   class="skip-to-content"
   style="position:absolute;left:-9999px;top:0;z-index:999;background:#00e68a;color:#000;padding:.5rem 1rem;font-weight:700;"
   onfocus="this.style.left='0'"
   onblur="this.style.left='-9999px'">
  Skip to main content
</a>

<!-- Then add id="main-content" to your <main> element -->
<main id="main-content">...

If you're using a theme that doesn't give you direct access to header.php (like Divi or some Elementor setups), add the skip link and the id="main-content" via the functions.php snippet below:

function adaflags_skip_link() {
  echo '<a href="#main-content" class="skip-to-content" style="position:absolute;left:-9999px;top:0;z-index:9999;background:#00e68a;color:#000;padding:.5rem 1rem;font-weight:700" onfocus="this.style.left=\'0\'" onblur="this.style.left=\'-9999px\'">Skip to main content</a>';
}
add_action( 'wp_body_open', 'adaflags_skip_link', 1 );

Fix 5: Broken heading hierarchy in blog templates

WCAG 1.3.1 (Info and Relationships) requires that heading levels convey structure — H1 → H2 → H3, without skipping. The most common WordPress failure: the site name is H1 in the header on archive pages, but the blog post titles on an archive page are rendered as H2, and post meta links inside a post are H4 — skipping H3 entirely. On single post pages, many themes render the post title as H2 or H3 because the "H1" position is occupied by the site name in the header.

// Run in browser console to audit heading order
[...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].forEach(h => {
  console.log(`${h.tagName}: ${h.textContent.trim().slice(0,60)}`);
});

Fix in your theme's single.php template: ensure the post title is wrapped in <h1>. Your site name in the header should be a <p> or <div> with a logo class — not a heading — so there's only one H1 per page.

<!-- Wrong: post title as H2 while site name is H1 in header -->
<h2 class="entry-title"><?php the_title(); ?></h2>

<!-- Correct: post title is H1; site name in header uses a non-heading element -->
<h1 class="entry-title"><?php the_title(); ?></h1>
<!-- And in header.php, wrap site name in <p> or <div>, not <h1> -->
<p class="site-title"><a href="<?php echo home_url(); ?>"><?php bloginfo('name'); ?></a></p>

WordPress Accessibility Plugins: What Actually Works vs. Overlays

The plugin ecosystem for WordPress accessibility is a mix of legitimate tools and overlay widgets disguised as compliance solutions. Here's the breakdown:

Plugin	What it does	Verdict
WP Accessibility (free) by Joe Dolson	Adds skip links, fixes language attributes, removes tabindex from non-interactive elements, enables long description support. Changes actual HTML output.	Legitimate
Accessibility Checker (free tier) by Equalize Digital	Scans your content post-by-post and surfaces real WCAG violations in the admin panel. Flags issues you can fix — doesn't try to fix them invisibly.	Legitimate
AccessiBe overlay widget	JavaScript overlay that tries to remap the rendered DOM. FTC fined $1M in 2025 for false compliance claims. NFB has condemned it. WordPress users have been sued with it installed.	Avoid
UserWay overlay widget	Same overlay model. 1,416 overlay lawsuits filed in H1 2025. Featured in the February 2026 Magistrate ruling that confirmed overlays don't constitute compliance.	Avoid
AudioEye overlay + managed	Widget product has same problems. Their managed audit service is different — actual code changes by their team. The widget alone isn't sufficient.	Widget: Avoid

The WordPress ADA Lawsuit Pattern

Several defendants in our 2025 ADA lawsuit tracker operated WordPress sites. The pattern is consistent:

1. Scanner identifies your site. Automated tools flag WCAG violations — typically missing alt text on multiple pages and form label failures. The combination of issues signals a non-compliant site worth pursuing.
2. Demand letter arrives. The letter cites specific violations on specific URLs with WCAG criterion numbers. Often references axe-core violation IDs directly, because that's what the scanner uses.
3. Settlement or litigation. Small business WordPress sites — restaurants, boutiques, service businesses — typically settle for $25,000–$50,000. California Unruh Act cases run higher due to statutory damages.

The consistent thread across cases: all cited violations were present in the theme's default output. None required anything exotic. All were fixable with the changes described above.

Quick Implementation Checklist for WordPress Owners

• 1
  Scan your site first. Run a free ADAFlags scan on your homepage, a blog post, and your contact page. This tells you exactly which violations are present before touching any code.
• 2
  Add the alt text fallback to functions.php. The wp_get_attachment_image_attributes filter above catches all cases where alt text is missing in the media library. Deploy it first — it covers every image on your site instantly.
• 3
  Check your theme's contrast defaults. Open Chrome DevTools on your homepage. Click the color swatches next to your body text, link color, and meta text. Every ratio should show a green checkmark at 4.5:1 or above. Fix any failures in your child theme's CSS.
• 4
  Add a skip-to-content link. Use the wp_body_open hook above — it works with any theme and doesn't require editing theme files directly. Verify by pressing Tab immediately after page load.
• 5
  Fix heading hierarchy. Run the console snippet above on your homepage, a post page, and an archive page. There should be exactly one H1 per page. H2 and H3 should be nested properly under it.
• 6
  Fix Elementor/Divi popups if you use them. Add the Elementor snippet above or enable Divi's accessibility settings. Then test the popup by navigating to the trigger element with Tab and pressing Enter — you should be moved into the popup and able to close it with Escape.
• 7
  Re-scan after changes. Run ADAFlags again to confirm violations are resolved. Save the scan results — this documents your remediation effort and is your best defense evidence.

Frequently Asked Questions

Is my WordPress website required to be ADA compliant?

Yes. Title III of the ADA applies to websites as places of public accommodation. WordPress sites — whether blogs, e-commerce, or service businesses — have been targeted by plaintiff firms under the ADA and state laws (California Unruh Act, New York HRL). Being on WordPress doesn't create any exemption or special status.

Does WordPress make my site ADA compliant automatically?

No. WordPress core is largely accessible, but your theme controls the HTML output — and most themes fail on contrast, missing alt text, unlabeled inputs, and heading structure. Page builders like Elementor and Divi add additional accessibility problems specific to how they generate HTML. Compliance depends on your theme configuration, not the platform.

Will an accessibility plugin like AccessiBe or UserWay protect my WordPress site?

No. Overlay plugins have been condemned by the National Federation of the Blind, fined by the FTC, and consistently ruled insufficient by courts. WordPress sites with overlays installed have been sued anyway. The violations exist in your theme's PHP templates and generated HTML — overlays run after page load and cannot fix source-level issues.

Which WordPress plugins actually help with ADA compliance?

WP Accessibility (free, by Joe Dolson) adds skip links, fixes language attributes, and addresses several theme-level issues. Accessibility Checker (free tier by Equalize Digital) scans your content and surfaces violations in the admin panel. These change actual HTML rather than trying to intercept it after render. The key difference from overlays: they make your site actually accessible, not just appear to be.

What are the most common ADA violations in WordPress themes?

Featured images and media library images without alt text, low-contrast color defaults in Astra/OceanWP/GeneratePress, Elementor and Divi popups that create focus traps, missing skip-to-content links, and broken heading hierarchy in blog templates that skip H2 to H4. These five patterns appear in the vast majority of WordPress ADA demand letters.

Related reading: Comparing overlay tools? Best AccessiBe Alternatives · UserWay Alternatives · AudioEye Alternatives. For the full compliance picture: ADA Compliance Checklist for Small Businesses. For platform-specific guides: Shopify ADA Compliance · Wix ADA Compliance. Full legal context: 2025 ADA Lawsuit Tracker (141 defendants).