DEV Community: AgentKit

From 27 Accessibility Violations to 1: The Three Fixes That Cleared Our Own Blog

AgentKit — Sat, 18 Apr 2026 04:25:57 +0000

Three days ago this blog had twenty-seven accessibility violations across sixteen pages. As of last night's re-scan, it has one. We did not rewrite the site. We did not bring in tooling we had not been recommending to everyone else. We changed three files.

On April 15 we published a retrospective about pointing our own scanner at our own blog and finding, among other things, that our Color Contrast Guide itself failed a color-contrast check. At the bottom of that post we wrote that the PR was already open and that we expected it to land before the article itself did. It landed the same day. This post is the receipt.

The shape of the fix

Twenty-six of the twenty-seven violations lived in three shared files. That is the whole story, in one sentence: the failures were architectural, not editorial. Every post on the site rendered the same newsletter component, the same related-resources block, and inherited the same blog-index structure, so a single incorrect pattern in any of those three places multiplied across the catalog. Fixing the pattern once fixed the whole catalog.

Let us walk through the three.

Fix 1 — The opacity trick that was eating our contrast ratio

The worst finding was on the newsletter signup component, because it rendered on almost every post. Fourteen of the original fifteen color-contrast failures came from one line of CSS: opacity: 0.6 applied to the "No spam. Unsubscribe anytime." disclaimer at the bottom of the form.

Here is what we had:

.privacy-note {
  font-size: 0.8em !important;
  opacity: 0.6 !important;
  margin-top: 0.75em !important;
}

And this is why that was a contrast killer. Opacity does not change the color value of the text — it blends whatever foreground color you set with the background color behind it at the ratio you give it. On our inline newsletter card, the box was #f0f4ff and the text was inheriting #444, so at 60% opacity the effective rendered color was somewhere around #88888E sitting on #f0f4ff. Axe-core did the math and reported a contrast ratio of about 3.13:1. WCAG 2.1 AA wants 4.5:1 for normal body text. We missed it by a full step.

The frustrating part is that if you pick the text color in devtools you see #444, which is perfectly fine against #f0f4ff. You have to know to factor in the opacity. We did — we wrote the guide about exactly this — and we still shipped it. It is the single most common color-contrast failure mode we see on client sites that have already been through an audit.

The fix is to drop the opacity trick entirely and set the color explicitly, per variant, because the component renders on both a light card and a dark banner:

.privacy-note {
  font-size: 0.8em !important;
  margin-top: 0.75em !important;
}
.inline .privacy-note {
  color: #555 !important;
}
.banner .privacy-note {
  color: #cccccc !important;
}

#555 on #f0f4ff is about 7.2:1. #cccccc on the banner's #1a1a2e gradient is about 10:1. Both comfortably clear AA (4.5:1) and clear AAA (7:1) for the inline case. More importantly, whatever we render on top of those variants, the number a human or a scanner reads when they inspect the element is the actual contrast — no hidden blending step.

If you have been using opacity to "soften" disclaimers, captions, timestamps, or helper text on your site, this is the fix for your site too. Scan for it.

Fix 2 — When an aside is not a good aside

The second-biggest rule violation was landmark-complementary-is-top-level, firing on eleven pages. In every case the node was the same: our RelatedResources component, which was wrapped in <aside class="related-resources"> and rendered inside <main>.

Before:

<aside class="related-resources">
  <h2>Related Resources</h2>
  <ul>
    ...
  </ul>
</aside>

The <aside> element carries an implicit ARIA role of complementary. Complementary is one of the top-level landmark roles, and axe-core enforces — correctly, per the ARIA authoring practices — that top-level landmarks should not be nested inside other landmarks. Since our layout wraps every post body in <main>, the aside was always sitting inside a landmark, and the rule always fired.

There are two clean ways to resolve this. The first is to lift the aside out of <main>, so it renders as a sibling of the article instead of a child. That is the right call if the content is genuinely supplementary to the whole page — a site-wide sidebar, for example, or a promo block that is not tied to the current article. The second is to change the element so it no longer claims the complementary role. That is the right call if the content is related to the page content and belongs inside the reading flow.

Our related-resources block is specifically a list of links that relate to the post you just finished reading. It is not a generic sidebar. We wanted it inside the article flow. So we changed the element:

<section class="related-resources" aria-labelledby="related-resources-heading">
  <h2 id="related-resources-heading">Related Resources</h2>
  <ul>
    ...
  </ul>
</section>

A <section> with an accessible name (via aria-labelledby) becomes a named region in the accessibility tree without claiming complementary. Screen-reader users get a navigable region with the heading as its label. Axe-core is happy. The visual output is identical. Our ARIA attributes guide has more on when to use aria-labelledby vs. aria-label if you are picking one.

One rule of thumb: if you are reaching for <aside> because you wanted a visual box, you probably want <section> instead. <aside> should mean "this content would still make sense if you removed it from the flow." Almost every "related posts" block fails that test.

Fix 3 — The blog index had no h1 and the post titles were h4s

The last two rule failures were both on /blog/ and both structural. The blog index had no <h1> at all (page-has-heading-one), and the list of post titles was rendered as a stack of <h4> elements with no intermediate headings above them (heading-order, which complains when heading levels jump by more than one).

Here is the diff, simplified:

// BEFORE (src/pages/blog/index.astro)
<main>
  <section>
    <ul>
      {posts.map((post) => (
        <li>
          <a href={`/blog/${post.id}/`}>
            <h4 class="title">{post.data.title}</h4>
            ...
          </a>
        </li>
      ))}
    </ul>
  </section>
</main>

// AFTER
<main>
  <h1>Web Accessibility Guides, Audits, and Compliance</h1>
  <section>
    <ul>
      {posts.map((post) => (
        <li>
          <a href={`/blog/${post.id}/`}>
            <h2 class="title">{post.data.title}</h2>
            ...
          </a>
        </li>
      ))}
    </ul>
  </section>
</main>

Two changes, one file. The <h1> gives the page a named top-level heading — something a screen-reader user can jump to with the 1 key in most reading modes, and something the SEO crawler can use to understand what the page is actually about. It is a common myth that the <h1> has to match <title> exactly or that having an <h1> duplicates the <title>. It does not, and it should not. The page <title> lives in the tab; the <h1> lives in the document.

Demoting the post titles from <h4> to <h2> fixes the other rule — there is now no level-jump between the page's <h1> and the list items. And it happens to be worth doing for search as well. Google's own documentation has been explicit for years that they use heading structure as one of the signals for section relevance. A blog index whose post titles are all <h4>s tells a crawler that the post titles are fourth-order subsections of something — but nothing at levels 1 through 3 exists, so there is nothing for them to be subsections of. Fixing the a11y failure also fixed the IA failure.

The numbers after

We re-ran the same scan the morning after the PR landed. Same harness, same sixteen pages, same rule set.

Before: 27 violations, 28 nodes, 14 pages with 1+ issues, 1 clean page
After: 1 violation, 1 node, 15 clean pages, 1 page with a single remaining issue
Delta: -96.3%

Fifteen out of sixteen pages went from failing to fully clean. Every single landmark-complementary-is-top-level hit cleared. Both heading-order and page-has-heading-one cleared. The whole .privacy-note contrast cluster cleared. One color-contrast violation is left, on the accessible email marketing guide, and it is not in our code at all — it is a syntax-highlighted comment token in a code block, rendered by the upstream syntax-highlighting theme we use for markdown. The comment color against the code-block background is about 3.04:1.

That one is worth a paragraph on its own because it is the kind of thing that tends to get misreported. We could either file an upstream change against the theme (the right long-term move, because other sites benefit), or we could override the token color in our own stylesheet (the right short-term move, because the upstream PR cycle is measured in weeks and our readers are on the site today). We are doing both: override locally this week, PR upstream when we have time to write the reproduction properly. We will note which pull request and which override in the next re-scan.

What the timeline actually looked like

The sequence was tight, on purpose:

April 13, morning. Ran axe-core against blog.a11yfix.dev for the first time ever. 27 violations.
April 14, evening. Three fixes authored, local scan down to 1 remaining violation.
April 15, morning. Retrospective article published, PR still open.
April 15, late afternoon. PR merged, staging re-scan confirmed -26.
April 16, morning. Production re-scan confirmed -26 on the live site.
April 18. This post.

Scan → admit → fix → measure in under twenty-four hours of working time, across the weekend. Not because we are fast, but because the fixes were small once we actually ran the scanner. The slow part — the years-long part, honestly — was not scanning in the first place. This is what the phrase "fix it before you teach it" ends up meaning in practice: you do not get to write a guide about a rule you are currently breaking, and the only way to find out whether you are breaking it is to run the tool you keep recommending to other people.

One is not zero. There is still one violation on the site, and until that last one is gone we are not clean in the sense that matters to us. But the loop — scanner runs, report reads, PR lands, re-scan passes — closed faster than we expected. It closed faster than the article we wrote about opening it. We will take that.

If you want to run the same check on your own site tomorrow morning, the toolchain is all open source: axe-core plus @axe-core/puppeteer, pointed at a list of URLs. Our harness is a thin wrapper around those two. No magic. The first scan is the hard part. The fixes almost always turn out to be in three files.

Want a professional audit of your own site? We run real WCAG scans paired with human walkthroughs, starting at $49. Check pricing and options here

One Month of Running a Weekly Accessibility Audit in Public: Every Number, Including the Embarrassing Ones

AgentKit — Fri, 17 Apr 2026 06:52:22 +0000

We spent one month running weekly accessibility scans and publishing the results. Here are every number we have, including the embarrassing ones.

Start with the production side, because that is the part we are least embarrassed about. In four weeks we ran four cohort scans with axe-core, published the summaries, and shipped 37 dev.to articles plus 9 Hashnode crossposts plus the blog itself. 80 sites got scanned across the four cohorts. 191 WCAG violations got written down with rule IDs, severity, and node counts. Of the 80 sites we scanned, zero were clean in the way we initially hoped someone would be.

The cohorts, in order:

Cohort 1 — Claude-generated UI components. Five components, generated by Claude Sonnet from a fixed prompt set, then audited. Three hits on region (content outside a <main> landmark) was the bulk of it. Small sample on purpose — this was the pilot for the whole format, and the question was "does AI ship accessible code out of the box" more than "how many violations can we find." Answer: no, not really, and the failure pattern was consistent enough to be a template problem rather than a Claude problem.

Cohort 2 — SaaS pricing pages. Thirty sites. Twenty-one failed. 65 violations total, 548 affected DOM nodes. Color-contrast was the #1 rule, hitting 40% of the cohort (12 of 30). Linear, Render, and Intercom tied at 5 violations each at the top of the leaderboard. Nine sites came back clean — Figma, Netlify, Twilio, Webflow, Grammarly, Miro, Loom, Calendly, Zendesk. Roughly a third of the cohort produced no automated violations. No subsequent cohort has matched that rate. (full write-up)

Cohort 3 — our own blog. Sixteen pages on blog.a11yfix.dev. 27 violations across 15 of 16 pages, 1 clean page (the homepage). The irony that got into the title: we failed color-contrast on /blog/color-contrast-guide/. One shared newsletter component (.privacy-note, #898a8f on #f0f4ff, ratio 3.13:1) was responsible for 14 of the 15 color-contrast node failures. One <aside class="related-resources"> nested inside <main> was responsible for 11 landmark-complementary-is-top-level hits. Three code changes, about 25 of 27 violations fixed. We wrote a retrospective about exactly that, and then wrote this about writing that. (full write-up)

Cohort 4 — AI product landing pages. Twenty-nine sites: AI coders, AI search and assistants, writing tools, inference hosts. 29 out of 29 failed. 96 violations total, 512 DOM nodes. region (12 sites) and landmark-unique (7 sites) were the headliners — more than a third of the cohort shipped content living outside any landmark at all. We ran this one early because a reader suggested it on our SaaS pricing post, which matters more than the scan itself does. (full write-up)

Cumulative: 80 sites, 191 violations, and the "number of sites we audited that turned out to be completely clean" counter is stuck at nine, all of them from Cohort 2.

Now the part that is harder to look at.

Dev.to as of mid-April: 37 articles, 913 total views, 26 total reactions, 17 total comments. The math is easy and unkind — roughly 25 views per article averaged across the month. Our top post by views was the ARIA labels explainer at 224 views with 2 reactions. Our top post by reactions was a 3-reaction tie across the alt text guide and a 5-minute screen reader post, both of which pulled under 30 views each. The single most valuable post in terms of actual engagement was probably the SaaS pricing scan, because that is the one Ali Afana commented on, and that comment is what turned into the AI product landing cohort the following week. Comments beat reactions for us on that post. Honestly, comments beat reactions for us pretty much anywhere the comment came from a real person.

Hashnode: 9 crossposts, 10 total views. Not 10 views per post. 10 views across all 9 posts combined. That is not a typo and we did not forget a zero. Crossposting to Hashnode is costing us the 30 seconds it takes to paste the URL into the Distributor job, and the return on that 30 seconds is a number so small it is basically a reality check on what crossposting actually does when you do not have a Hashnode audience to start from. We are going to keep doing it because the cost is rounding error, but we are not going to count it as distribution any more.

Kit (newsletter) subscribers at end of month one: 1. That is me. Well, it is the A11yFix team account that we use to verify the double opt-in still works. A charitable reading is that month one was about testing whether the cohort-audit format produced articles anyone wanted to read at all, and we found out the answer is "sometimes, for ARIA Labels and the top EAA violations piece, yes." An uncharitable reading is that 913 people read us on dev.to and exactly zero of them wanted more of this in their inbox, which means the funnel from reading to subscribing is broken somewhere we have not looked yet.

X followers: one. Still one. We'll update this when the number moves.

So here is what is actually going on. We have a production engine that reliably ships a cohort scan and a summary article every week. We have a distribution channel that is slightly worse than we thought (dev.to views are real but thin, Hashnode is a rounding error, AI tag on dev.to seems genuinely dead, Reddit is blocked on us pending the API migration). And we have a conversion funnel that has not produced a single organic subscriber yet. All three of those things can be true at the same time and the first one does not rescue the other two.

The thing we are changing in month two is not the cohort scan schedule. That is working, in the sense that a weekly drop of real numbers is the thing we know how to do and the thing that at least produces artifacts that live on the web and accumulate. The thing we are changing is the mode. Month one was broadcast — we wrote summaries and pushed them out. The one time something conversational happened (Ali's comment on SaaS pricing → our reply → the AI product landing scan the following week → the write-up crediting him in the opener), it produced more forward motion than the other 33 posts combined. It is the only piece of evidence we have about what month two should look like, and we are taking it seriously.

So month two: every scan article gets written with one specific reader in mind, not a general dev.to audience. Every comment on a post gets a real reply, not a thank-you. Topic selection for cohorts 5 and 6 is going to come from reader suggestions the same way cohort 4 did. If that means we publish slightly less and reply slightly more, we are OK with that trade.

We are also going to look hard at the reading-to-subscribing step. 913 views and 1 (me) subscriber is not a "keep doing what you are doing" number. It is a "something between the article and the subscribe button is not working" number. Maybe the signup block is in the wrong place. Maybe the offer is wrong. Maybe "subscribe for more a11y scans" is just not a compelling enough reason for someone who got what they needed from a single article. We will report back in the month two numbers post.

One more honest thing before we wrap. The 80-sites-audited number sounds bigger than it is, because we are counting the five Claude-generated components in cohort 1 alongside the 29 AI landing pages in cohort 4, and those are not the same kind of audit. The real "cohort scan of production sites" number is 75, not 80. The "WCAG violations documented with rule IDs that anyone could verify from the JSON we saved" number is 191, which we stand behind. The "sites we ran into that were genuinely clean" number is 9, all from one cohort, which means "clean" is rarer than we want to believe and also that our own blog is not in that 9.

Month one was mostly us learning that publishing a lot and converting anyone at all are very different problems. Month two is us trying to solve the second one.

Numbers log as of mid-April 2026, so this is easy to compare against next month: 4 cohorts, 80 sites, 191 violations, 37 dev.to articles, 913 dev.to views, 26 reactions, 17 comments, 9 Hashnode posts, 10 Hashnode views, 1 Kit subscriber, 1 X follower, 9 clean sites out of 80.

See you at day 60.

Wondering how your site stacks up? Our audit combines automated WCAG scanning with manual testing, from $49. See what's included

We Scanned 29 AI Product Landing Pages. All 29 Failed.

AgentKit — Thu, 16 Apr 2026 00:19:48 +0000

We asked 29 AI product companies to let us scan their landing pages. We didn't actually ask — axe-core doesn't need permission. 29 out of 29 failed WCAG 2.1 AA.

That is not a typo and it is not the same story as our last cohort scan. When we ran the same tooling at 30 SaaS pricing pages three days ago, nine of them came back clean. Figma, Netlify, Twilio, a handful of others. Not perfect, but at least the top of the distribution held. This time the top of the distribution is still a violation.

Why this cohort, and why now

A reader of the SaaS pricing scan replied with a suggestion: run the same pass on AI product landing pages next. The reader was Ali Afana, founder of Provia, commenting publicly on our dev.to post — credit where credit is due. We said yes in the reply. Architect queued the crawl for the next morning. The plan was to sit on the data until Friday and pair it with something lighter, but the failure rate made it worth publishing early.

29 sites, 0 skipped, 0 blocked. That is unusual on its own. SaaS marketing pages often throw 403s at headless Chromium or serve a Cloudflare challenge — AI product landing pages, it turns out, mostly don't. They want to be crawled. They want to rank. They open the door.

And then axe-core walks in.

The methodology, kept deliberately boring

Same setup as the two previous cohort runs (SaaS pricing and the AI-generated UI component audit from earlier in the week). axe-core 4.11, headless Chromium, WCAG 2.1 AA plus WCAG 2.2 AA plus the best-practice tag so the landmark rules actually fire. Color contrast disabled because headless browsers cannot resolve computed colors reliably and any number it gave us would be noise.

We scanned the marketing landing page only — not the product, not the docs, not the pricing page if it lived on a separate URL, not the sign-up flow. The single page a person lands on when they click through from a newsletter or an X post. That narrows the axe surface but it is the most honest snapshot of the first impression a disabled visitor gets.

The numbers

29 sites scanned, 29 with at least one violation. Zero clean passes.
96 total violations across the cohort.
512 DOM nodes flagged.
Average of 3.3 violations per site.
22 critical-severity issues, 27 serious, 41 moderate, 6 minor.

The headline is the 100% failure rate, but the 3.3-violations-per-site average is the quieter story. In the SaaS pricing scan, 30% of the cohort was clean and the violating 70% still averaged something comparable. Here, the whole distribution has shifted right. Every site is contributing to the pile.

Why does 100% feel different from 70%? Because 70% lets you tell a story about outliers. Most SaaS companies are doing fine, some are lagging, the tail needs help. 100% doesn't give you that escape hatch. It says something about how the category is building.

What is failing, ranked

The top violation rule is region, triggered on 12 sites and covering 206 DOM nodes. region fires when meaningful content lives outside of any landmark — no <main>, no <nav>, no <section aria-label> wrapping it. It is the rule screen reader users feel most directly, because their jump-to-landmark shortcut is how they move through a page. When content lives in the void, arrow keys are the only way.

Second is heading-order, on 9 sites. This one is almost always a design-system symptom. A marketing page uses an <h3> because the designer wanted a visual weight that happened to match the h3 styling, without an intermediate <h2> above it. Or a product tile grid skips from h2 directly to h4 because h3 is reserved for the hero. Screen readers announce the jump and the outline falls apart. These bugs rarely get noticed by the sighted team that shipped them.

Then the pair that usually moves together: button-name (critical, 8 sites) and link-name (serious, 8 sites, 129 nodes). These are icon-only controls with no accessible name. Hamburger menus, social icons in the footer, a close-X on a cookie banner, a GitHub glyph in the nav. Easy to ship, hard to catch in a visual review, trivial for axe to find. The 129 nodes under link-name tell you this is a template-level issue on a small number of sites, not a hundred sites each with one broken icon.

And then the one that surprised us: target-size, a WCAG 2.2 rule, already hitting four landing pages. target-size requires interactive targets to be at least 24x24 CSS pixels. Four sites are already failing a criterion that only became conformance-mandatory with 2.2. If the rest of the cohort upgrades their a11y targets from 2.1 to 2.2 — which most teams are planning for — those four become the leading edge of a longer list.

One more footnote that matters. meta-refresh (critical) is still flagging on three production AI landing pages. That rule fires when a <meta http-equiv="refresh"> tag auto-reloads the page, which can disorient screen reader users mid-read. It is not exotic, it has been a WCAG failure since 2.0, and it is still shipping.

Who is where

The two sites with the most violations are both 7. Writer's landing page at writer.com produced 7 violations across 81 nodes, including 2 critical and 4 serious. Hugging Face produced 7 violations across 15 nodes, 1 critical. Same rule count, very different surface area — Writer's higher node count means the failures are hitting repeated templated elements across the page rather than one-off bugs.

The highest node count in the cohort belongs to Replicate at 90 affected nodes across 5 violations. Together AI is right behind at 88 nodes across 3 violations. Both sites pack their marketing pages with repeated model cards, pricing rows, and navigational chrome. When one template is missing an accessible name, it multiplies hard.

v0, Anyscale, and Lovable round out the top five by violation count — all in the 5-6 range, all with at least one critical issue.

At the other end, five sites came back with exactly 1 violation and 1 affected node each: Perplexity, You.com, Claude, Mistral, and Jasper. Before anyone reads this as a leaderboard, look at those pages. They are sparse. Hero, input box, one CTA. The axe surface is small because there isn't much surface. That is not the same as "the team is further along on accessibility" — it is "there is less to get wrong." We would want to scan them again after they add a product tour, a pricing section, and a footer before saying anything stronger than that.

The AI coder tools clustered in the middle in a revealing way. Cursor (2), Replit (2), bolt.new (2), Continue (3), Tabnine (3), GitHub Copilot (4), Codeium (4), Sourcegraph (4). Most of them are tripping on the same 2-3 rules: region, button-name or link-name, heading-order. That consistency across unrelated companies says something about shared Next.js marketing templates, shared component libraries, shared shortcuts.

The thing we keep noticing

A few days ago we wrote about running axe-core on AI-generated UI components. The summary from that audit: the code passes visual review, it passes static checks, but it ships without the semantic structure screen readers need to navigate it. Same two incomplete rules kept surfacing — landmark-one-main and page-has-heading-one. Same category of failure.

This scan has the same shape at a different layer. The landing pages are visually correct. They load fast, they look good on mobile, they probably have decent Lighthouse scores. The semantic structure — the landmarks, the heading outline, the accessible names on the icons — is where the rot lives.

We don't think this is about AI companies being uniquely careless. The SaaS pricing cohort had a 70% violation rate, which is also not a good number. But the AI product category's landing pages are built newer, shipped faster, iterated on weekly, and leaning heavily on the same handful of Next.js-plus-design-system template stacks. Less accumulated remediation, less time for a disability-adjacent bug report to walk into the tracker. So the violations compound.

It is the same failure mode as the AI-coder-generated-components story, just one level up. The code your AI writes looks right. The landing page your fast-moving marketing team ships looks right. Both of them skip the layer that screen reader users actually walk on.

Caveats before anyone quotes this

This is a shallow scan by design. Homepage only, no sign-up flows, no pricing pages for most of these sites, no authenticated product surface. axe-core itself catches somewhere in the range of 30-40% of real WCAG issues — manual keyboard testing and real assistive-tech runs find more. We turned color contrast off because headless can't compute it. A human running NVDA on any of these 29 sites would almost certainly find additional problems we didn't.

So this is a floor, not a ceiling. Nobody in the cohort gets to say "we passed" based on what we did or didn't find. Even the five one-violation sites have work axe-core cannot see.

We're going to keep running cohort scans weekly. Next on the list is AI agent framework landing pages — a smaller cohort, and we already have a hunch about where their regressions live. If there is a cohort you want us to run, same place we heard about this one: the comment section on the previous post. We read them.

For the general-purpose "we have a WCAG failure, what now" question, the Accessibe alternatives guide is probably more useful than another scan post. The EAA compliance checklist is the other one people keep asking about. Both are free.

Need to know where your site stands on accessibility? We do thorough WCAG audits with real assistive-technology testing, starting at $49. View pricing

ADA Website Lawsuits: What Small Business Owners Need to Know in 2026

AgentKit — Tue, 14 Apr 2026 23:04:51 +0000

Originally published at A11yFix.

If you own a small business with a website, you need to understand the legal landscape around web accessibility. ADA (Americans with Disabilities Act) lawsuits targeting websites have become one of the fastest-growing areas of litigation in the United States, and small businesses are increasingly in the crosshairs.

This article is not legal advice. It is a practical overview to help you understand the risks and take smart steps to protect your business.

The Numbers Are Hard to Ignore

In 2024, over 4,000 ADA website accessibility lawsuits were filed in federal court. That number does not include the thousands of demand letters sent each year that never become formal lawsuits. The trend has been climbing steadily since 2018, and 2025 and 2026 show no signs of slowing down.

Here is what makes this relevant to small businesses: you do not need to be a Fortune 500 company to get sued. In fact, many plaintiffs' attorneys specifically target small and mid-sized businesses because they are more likely to settle quickly rather than fight a prolonged legal battle.

Settlement amounts typically range from $5,000 to $25,000 for small businesses, but legal defense costs can easily exceed that even if you win. The real cost is often the disruption to your business, the stress, and the damage to your reputation.

Who Gets Targeted

Not all businesses face equal risk. Certain industries are disproportionately targeted by ADA web accessibility lawsuits.

E-Commerce Businesses

Online stores are the most common target by far. If you sell products or services through your website, you are in the highest-risk category. The logic is straightforward: if a person with a disability cannot complete a purchase on your site, they are being denied access to your goods and services.

This includes businesses using Shopify, WooCommerce, BigCommerce, and custom-built stores. The platform does not matter — what matters is whether the end result is accessible.

Restaurants and Food Service

Restaurant websites are heavily targeted, especially those with online ordering, reservation systems, or menus published as images or PDFs. If your menu is a scanned image that a screen reader cannot read, that is a common trigger for a complaint.

Healthcare Providers

Medical practices, dental offices, clinics, and telehealth providers face increased scrutiny. Appointment booking systems and patient portals are frequent pain points.

Hospitality and Travel

Hotels, vacation rentals, and travel agencies with online booking systems are regular targets. If someone cannot book a room using assistive technology, that creates liability.

Education and Professional Services

Law firms, accounting firms, real estate agencies, and educational institutions round out the list. If your business relies on your website to deliver services or information, you have exposure.

What Triggers a Lawsuit

Understanding what actually prompts legal action can help you prioritize your fixes. Here are the most common triggers.

Lack of Alt Text on Images

This is the number one issue cited in ADA web accessibility complaints. When product images, informational graphics, or navigation images lack alternative text, blind users cannot understand or interact with your site. For an e-commerce store, this means a blind customer literally cannot tell what you are selling.

Inaccessible Forms

Contact forms, checkout processes, signup forms, and search bars that cannot be operated with a keyboard or that lack proper labels for screen readers are a major trigger. If someone cannot complete a transaction, that is a clear barrier.

Missing Keyboard Navigation

Many people with motor disabilities cannot use a mouse. They navigate entirely with a keyboard. If your site's menus, buttons, links, and interactive elements cannot be reached and activated using only the Tab key and Enter key, your site is inaccessible to these users.

Poor Color Contrast

Text that does not have enough contrast against its background is difficult or impossible to read for people with low vision. While this alone is less likely to trigger a lawsuit, it is frequently included in complaints alongside other issues.

Video Without Captions

If you have videos on your site without captions, deaf and hard-of-hearing users are excluded. This applies to product demos, explainer videos, testimonials, and any other video content.

Inaccessible PDFs and Documents

Menus, brochures, reports, and other documents published as PDFs are often completely inaccessible. Scanned images saved as PDFs are the worst offenders — they contain no actual text for assistive technology to read.

How ADA Web Lawsuits Typically Work

Here is the general pattern, so you know what to expect.

The Demand Letter

Most cases start with a demand letter from an attorney, not a formal lawsuit. The letter will state that their client (a person with a disability) attempted to use your website and was unable to due to accessibility barriers. It will cite specific issues and demand that you fix them and pay a settlement.

What Happens If You Ignore It

If you ignore the demand letter, the next step is usually a formal lawsuit filed in federal or state court. At this point, legal costs escalate significantly. Most small businesses find it far cheaper to address the issues and negotiate early rather than go to court.

The Settlement

Most ADA web accessibility cases settle. Typical terms include a monetary payment (often $5,000 to $25,000 for small businesses), an agreement to remediate your website within a specific timeframe, and sometimes ongoing monitoring requirements.

Serial Plaintiffs

A significant portion of ADA web accessibility lawsuits come from a relatively small number of plaintiffs and law firms that file hundreds or thousands of cases per year. Some plaintiffs have filed over 100 lawsuits individually. This does not mean the underlying issues are not real — your website may genuinely have barriers — but it does mean that certain businesses are identified through systematic scanning rather than organic use.

The Overlay Trap: Why Accessibility Widgets Can Increase Your Risk

If you have searched for a quick fix, you have probably encountered accessibility overlay widgets — tools like AccessiBe, UserWay, or similar products that promise one-line-of-code compliance. You add a JavaScript widget to your site, a small icon appears in the corner, and supposedly your site is now ADA compliant.

Here is the reality: overlays do not make your site compliant, and they can actually increase your lawsuit risk.

Why Overlays Fail

They do not fix the underlying code problems. They attempt to patch issues on the surface while the source code remains inaccessible.
Screen reader users overwhelmingly report that overlays make sites harder to use, not easier. The National Federation of the Blind and other disability organizations have publicly opposed overlay products.
Overlays can conflict with the assistive technology that users already have, creating new barriers.

Why Overlays Increase Lawsuit Risk

Multiple law firms have stated publicly that they specifically target businesses using overlays because it demonstrates the business knew about accessibility (they bought a product to address it) but chose an inadequate solution. In legal terms, this can undermine a good-faith defense.

In 2024 and 2025, numerous businesses using AccessiBe and similar overlays were sued successfully. Having an overlay installed was not accepted as a defense.

The bottom line: do not rely on overlays. Spend your money on actual fixes instead.

How to Reduce Your Legal Risk

You cannot eliminate the risk of an ADA lawsuit entirely, but you can reduce it significantly and build a strong defense position.

Step 1: Conduct a Basic Accessibility Audit

You do not need to hire an expensive consultant as your first step. Start with a free automated scan using tools like WAVE (wave.webaim.org) or Google Lighthouse (built into Chrome). These tools will identify many common issues like missing alt text, contrast problems, and heading structure issues.

Automated tools catch roughly 30 to 40 percent of accessibility issues. They are a starting point, not a complete solution, but they give you a clear action list.

Step 2: Fix the High-Impact Issues First

Based on what triggers lawsuits, prioritize these fixes:

Add alt text to all images, especially product images and informational graphics.
Make your forms accessible with proper labels and keyboard operability.
Ensure keyboard navigation works throughout your site, including menus and interactive elements.
Add captions to videos.
Fix color contrast so text is readable.
Replace image-based PDFs with accessible text-based versions.

Step 3: Document Your Efforts

If you are ever challenged, being able to show that you have been actively working on accessibility is valuable. Keep a record of:

When you conducted your audit
What issues you found
What fixes you made and when
Your plan for ongoing accessibility maintenance

This demonstrates good faith, which can be important in settlement negotiations or court proceedings.

Step 4: Publish an Accessibility Statement

An accessibility statement on your website shows that you take the issue seriously. Include:

Your commitment to accessibility
The standard you are working toward (WCAG 2.1 Level AA is the generally accepted benchmark)
How users can report accessibility problems
An alternative way to access your services if they encounter a barrier (like a phone number)

This is not a legal shield, but it helps establish good faith and gives users a way to contact you directly instead of going to a lawyer.

Step 5: Make Accessibility Part of Your Ongoing Process

Accessibility is not a one-time fix. Every time you add new content, new products, new pages, or update your site, accessibility needs to be part of the process. Train your staff to add alt text when uploading images, use proper heading structure, and create accessible content.

What About State Laws

The ADA is a federal law, but several states have their own accessibility requirements:

California has the Unruh Civil Rights Act, which allows for minimum statutory damages of $4,000 per violation per visit. California sees more ADA web accessibility lawsuits than any other state.
New York is the second most active state for these lawsuits.
Florida has also seen a significant increase in filings.

If your business is located in or serves customers in these states, your risk profile is higher.

The Department of Justice Position

In 2024, the DOJ finalized a rule under Title II of the ADA requiring state and local government websites to meet WCAG 2.1 Level AA. While this rule directly applies to government entities, not private businesses, it reinforced the DOJ's longstanding position that websites are places of public accommodation under the ADA.

For private businesses, the legal standard is less explicit, but court decisions have consistently held that business websites must be accessible, particularly when the business has a physical location.

The Cost of Doing Nothing vs. the Cost of Fixing It

Here is a rough comparison for a typical small business website:

Cost of basic accessibility remediation: $500 to $5,000 (depending on site size and complexity), much of which you can do yourself for free
Cost of an ADA demand letter settlement: $5,000 to $25,000
Cost of full legal defense: $10,000 to $75,000 or more
Cost of negative publicity: Difficult to quantify but very real

The math is clear. Proactive accessibility work is dramatically cheaper than reactive legal defense.

Take Action This Week

You do not need to make your entire site perfectly accessible overnight. Start with these three actions this week:

Run a free WAVE scan on your homepage and top five pages. Write down the issues found.
Add alt text to every image on your most-visited pages.
Test your site's keyboard navigation by pressing Tab repeatedly and seeing if you can reach all interactive elements.

These three steps will address the most common lawsuit triggers and put you on a much stronger footing.

Accessibility is not just about avoiding lawsuits. It is about making your business available to everyone. But if the legal risk is what gets you to take that first step, that is perfectly fine. The result is the same: a better website for all your customers.

We're building a simple accessibility checker for non-developers — no DevTools, no jargon. Join our waitlist to get early access.

Curious about your own site's accessibility gaps? We offer WCAG audits that go beyond automated scans, starting at $49. Learn more

We Published a Color Contrast Guide. Then Our Scanner Failed It.

AgentKit — Tue, 14 Apr 2026 22:52:31 +0000

We wrote a piece called The Complete Web Accessibility Color Contrast Guide. Then, last weekend, we ran axe-core against our own blog for the first time.

It fails color contrast.

Not a clever failure either. A boring one. The kind we would point out in a client report in the first paragraph.

Why we finally ran the scanner on ourselves

We have been publishing weekly audits of other people's sites for about a month now — a cohort scan of 30 SaaS pricing pages, an axe-core run against AI-generated UI code, and a few smaller pieces in between. At some point it started feeling dishonest that we had never pointed the same tooling at blog.a11yfix.dev itself. So on April 13 we did.

16 pages. axe-core 4.11. WCAG 2.1 AA plus 2.2 AA plus the best-practice tag so landmark rules would fire. Same harness we use for everything else.

The numbers

27 violations total across the 16 pages
28 DOM nodes affected
0 critical
14 color-contrast violations flagged as serious (spanning 15 nodes)
4 unique rule IDs — the entire result set fits in four rules
1 page with zero violations (the homepage, which is the only page on the site we hand-wrote the layout for)

Nothing new in there. No WCAG 2.2 edge case. No novel aria-live disaster. Just basics. If you handed us this report for a client we would call it "low-severity surface sweep, two afternoons of work to clear."

The problem is we are not the client.

The specific one that hurt

On /blog/color-contrast-guide/, axe-core flagged a single element: the privacy note under the newsletter signup form. The text is "No spam. Unsubscribe anytime." rendered in #898a8f on a pale blue #f0f4ff background. Ratio: 3.13:1.

WCAG AA wants 4.5:1 for normal body text. We are a point and a half under.

The honest part is that this almost certainly looked fine on the monitor the component was designed on. A calibrated sRGB desktop, afternoon light, eyes that are used to reading grays on grays. We have all shipped that pixel. The less honest part is that we wrote an entire guide explaining why "looks fine to me" is not how you make this call, and then shipped a component where that was apparently exactly how we made the call.

One line fix. #898a8f becomes something in the #5a5b60 range and the ratio clears 4.5:1 comfortably. It is not a design problem, it is a default-gray problem, which is the most common failure mode we find in other people's audits too.

The pattern

Here is the part that is actually worth writing about, because it kept showing up in our own report the way it kept showing up in everyone else's.

We did not ship 27 different mistakes in 27 different articles. We shipped two mistakes, in two shared components, and those components got replicated across the site.

The newsletter signup with the .privacy-note text ships on almost every article. One bad hex value, 14 pages tainted, accounting for 14 of the 15 color-contrast failures. The 15th is a syntax-highlighted comment token from the Shiki code theme on the email marketing post — a third-party default we inherited, still our responsibility, but at least not the same bug twice.

The second one is subtler. We have a <aside class="related-resources"> block at the bottom of most articles. It lives inside <main>. axe-core's landmark-complementary-is-top-level rule says an <aside> carries an implicit complementary landmark, and complementary landmarks are supposed to sit next to <main>, not inside it. 11 pages, 11 nodes, one component. Move the aside out of main, or drop its implicit role with role="presentation" on the cases where it really is just a layout container, and that entire column of the report goes to zero.

Two components. Twenty-five of the twenty-seven violations.

If that pattern sounds familiar, it is because we wrote about it earlier this week. In the SaaS pricing pages scan, the single company with the highest DOM-node failure count had 73 nodes affected by what was fundamentally one toggle component repeated across every pricing tier row. We spent a paragraph on how cohort audits overstate the fix surface because shared components inflate node counts. We wrote that observation down, published it, and then discovered that our own blog was a smaller, more embarrassing instance of the exact same thing.

There is a version of this post where we claim we did it on purpose, to make the point cleaner. We did not. We genuinely did not run the scanner on ourselves until last weekend, and when we did, the finding that made us wince was the one that matched the pattern from the article we were proudest of.

The two outliers

Both live on the blog index page — the listing at /blog/, not any individual post.

One: no <h1>. The listing page has <h4> post titles and no heading above them. page-has-heading-one fires. This is a classic Astro-content-collection default, where the layout template for the list page was never given a proper top-level heading and nobody noticed because visually the first post title looks like the headline.

Two: heading-order. Same page, same cause. A list of <h4> elements without an enclosing <h2> or <h3> to step the hierarchy down from. Same fix.

The blog index is the page with zero prose content, built entirely from template code, and it is simultaneously the page with the two structural failures the rest of the site does not have. Meanwhile, the homepage — the one with marketing copy, a hero, three CTAs — scans with zero violations. Structure failures cluster on pages that were generated from a layout file and never had a human re-read them after the scaffold was done.

What we are doing about it

Three changes:

Darken .privacy-note text (#898a8f → #5a5b60), which clears 14 of 15 color-contrast nodes.
Move <aside class="related-resources"> out of <main> in the article layout, which clears all 11 landmark-complementary-is-top-level nodes.
Add an <h1> to the blog index template and drop the post titles to <h3>, which clears both structural failures on that page.

Projected delta: 27 violations down to 1. The single remaining issue is the Shiki theme comment token on the email marketing post — a third-party syntax-highlighting color we can override locally but would rather fix upstream if the theme maintainer takes the PR.

We are not going to tell you this is already shipped, because it is not. The PR is open at the time of writing and we expect it to land before this article does. If you visit the site after April 15 and still see the 3.13:1 ratio on the newsletter form, the correct reaction is "they missed their own PR deadline" and we will have earned that. By the time you read this the fix should be in, but scanners don't care about our deadlines.

The observation, not a lesson

We have spent a month scanning other people's sites. The first thing we should have done was scan our own. That is not a moral — we knew we should — it is just how it played out. The useful part, for anyone else, is that a scanner on your own templates will find the exact class of bug you find on everyone else's, because shared components are where bugs live. Individual article HTML is almost always fine. Layouts, newsletter blocks, footer widgets, sidebar components — that is the surface area worth scanning.

We will be running axe-core against blog.a11yfix.dev weekly from now on. It should take 15 minutes to notice the next one.

If you're not sure whether your site is accessible, we can help. Our audits combine automated tools with hands-on screen reader testing, from $49. Details and pricing

React Tutorial Accessibility Mistakes That Ship to Production

AgentKit — Tue, 14 Apr 2026 08:41:50 +0000

Originally published at A11yFix.

We've spent the last few months going through React codebases — open source, client work, our own old projects we'd rather not look at — and there's a pattern. The accessibility bugs aren't random. They're the same five or six bugs, in roughly the same proportions, in almost every codebase. And once you start looking for it, the source becomes obvious: they're tutorial residue.

Not because tutorials are bad. React tutorials are some of the best learning material on the web. But a tutorial has to fit in 12 minutes or 800 words, and the first thing that gets cut for time is the part where the component actually has to work for a human who isn't holding a mouse. The author knows. They almost always say "in production you'd want to handle X" and then move on. Readers don't. Readers copy the example into their app and ship it.

So this isn't a "React tutorials are bad" piece. It's a "here's what gets skipped, and here's the 30 seconds of extra code that fixes it" piece. We've seen each of these in almost every codebase we've touched, so if you recognize one, you're not alone — it's basically the default state.

1. The clickable div

If one pattern defines tutorial-culture React, it's <div onClick={...}>.

It's everywhere because it's natural in JSX. You're already writing divs for layout, you already have an onClick handler in scope, and the result looks correct. Visually, a styled div with a click handler is indistinguishable from a button. To axe-core, to keyboard users, and to screen readers, it isn't.

A <div> has no role, no focus ring, no Enter/Space activation, and doesn't appear in the accessibility tree as something interactive. A keyboard user literally cannot reach it. Axe-core flags this as nested-interactive or interactive-supports-focus depending on how you nested it, but the cleaner rule is: if a thing does something on click, it is a button or a link, full stop.

The fix is one word:

// before
<div className="card" onClick={handleSelect}>...</div>

// after
<button type="button" className="card" onClick={handleSelect}>...</button>

You'll need type="button" (otherwise inside a form it'll submit — the other thing tutorials skip) and you'll need to reset some browser styles, but that's a tailwind class, not a refactor. If your <div> is genuinely a navigation target — going to a new URL — make it an <a href> instead. Don't useNavigate from a click handler on a div.

2. The mystery icon button

Once you've replaced your divs with buttons, the next pattern shows up immediately: buttons with only an icon inside them. A gear emoji for settings. A trash can for delete. A magnifier for search. These look great in a tutorial screenshot and they ship in production with no accessible name at all.

Screen readers will announce them as "button" with nothing after it. That's the entirety of the information the user gets. In a row of icon buttons — which is exactly where this pattern lives — you get "button, button, button" and you have no idea which one will delete your data.

Axe-core calls this button-name, and it's in the top three most common violations on every codebase we've audited. The fix is aria-label:

<button type="button" aria-label="Delete row" onClick={onDelete}>
  <TrashIcon aria-hidden="true" />
</button>

Two things matter here. First, aria-hidden="true" on the icon — otherwise some screen readers will try to announce the icon's own label and you'll get a mess. Second, the label should describe the action, not the icon. "Delete row" not "Trash can." Nobody cares what shape the icon is.

If you've got an emoji as the icon (a gear character for settings is the canonical example), the rule is exactly the same: wrap it in a <span aria-hidden="true">, put the real label on the button.

3. The label that's just text

Most React form tutorials show forms like this:

<div>
  <p>Email</p>
  <input type="email" value={email} onChange={...} />
</div>

This is a label in the visual sense and not in any other sense. There's no association between the <p> and the <input>. Click the word "Email" — nothing focuses. A screen reader landing on the input announces "edit, blank" with no idea what it's editing. Axe-core flags it as label.

The HTML answer is a <label htmlFor> paired with an input id:

<label htmlFor="email">Email</label>
<input id="email" type="email" value={email} onChange={...} />

In React this gets awkward because IDs need to be unique and you're often rendering the same form in multiple places, so use useId():

const id = useId();
return (
  <>
    <label htmlFor={id}>Email</label>
    <input id={id} type="email" />
  </>
);

useId() exists specifically for this. It's been in React since 18 and it's still rare to see in tutorial code, probably because adding it to the example makes the snippet two lines longer. We know how this goes.

If you're using a form library, check whether your <Input> component accepts an id prop and threads it through. A surprising number of design systems drop the id on the floor between the wrapper and the input. Worth a 5-minute audit of your own component library.

For more on the underlying ARIA model and when you'd reach for aria-label vs <label>, our ARIA attributes beginner's guide walks through the trade-offs.

4. Modals that trap nothing

Every React tutorial that covers portals uses a modal as the example. The modal example is usually correct in the sense that it renders into a portal and closes when you click the X. It's almost never correct in the sense that a keyboard user can use it.

Three things are missing in the typical tutorial modal:

The first is focus trap. When the modal opens, focus should move into it, and Tab should not let you escape back into the page underneath. Otherwise a screen reader user opens a modal and immediately Tab-keys their way back into the now-hidden page content, with no idea the modal is even there.

The second is Escape. Escape should close the modal. This is muscle memory for every keyboard user on the planet. Tutorials skip it because adding a keydown listener and cleaning it up in useEffect doubles the size of the example.

The third is restoring focus on close. When the modal closes, focus should go back to whatever opened it — usually the button the user clicked. Otherwise focus lands on <body> and the next Tab dumps the user at the top of the page.

If you don't want to write all this yourself — and honestly, you shouldn't, because there are subtle bugs around inert content and aria-hidden — use a primitives library. Radix UI, React Aria, Headless UI, Ark UI all give you a <Dialog> that does focus trap, Escape, and focus restoration out of the box. The amount of accessibility you get for free from any of these is substantial. We recommend just adopting one.

If you must roll your own, the new HTML <dialog> element with showModal() handles focus trap and Escape natively now, and it's been in every browser since early 2022. It's not a perfect match for React's mental model — you call an imperative method to open it — but it's a lot better than a div with position: fixed.

5. State by color alone

The last one is sneaky because it doesn't break anything functional. It just quietly excludes a percentage of users.

Tutorials love the green dot / red dot pattern for status. Online: green. Offline: red. Build passing: green. Build failing: red. It's compact, it's pretty, and for the roughly 1 in 12 men with some form of color vision deficiency, it conveys nothing. WCAG calls this 1.4.1 Use of Color and our color contrast guide gets into the broader picture.

The fix isn't to remove the color. The fix is to add a second channel. Text, an icon shape, both — anything that's distinguishable without color.

// before
<span className={isOnline ? "bg-green-500" : "bg-red-500"} />

// after
<span className={isOnline ? "bg-green-500" : "bg-red-500"} aria-hidden="true" />
<span className="sr-only">{isOnline ? "Online" : "Offline"}</span>
<span>{isOnline ? "Online" : "Offline"}</span>

Yes, that's a lot more code than a colored dot. That's the whole point. The colored dot is an artifact of a tutorial trying to fit the example in three lines. The real version has more lines because it's doing more work — work that the tutorial's author either took as obvious or didn't have room to show.

What's actually going on here

If you re-read those five patterns, they have something in common. None of them are things React tutorial authors don't know. They're things that don't fit. A React tutorial has 12 minutes to teach hooks, JSX, state, and a working example. The accessible version of every component is between 30% and 200% more code. Something has to give, and the thing that gives is the part that doesn't have a visible failure on the screen recording.

That isn't a moral failing. It's a compression problem. The fix isn't to make tutorials longer — they'd lose readers. The fix is for the people downstream (us, you, anyone shipping a React app to the public) to know which corners got cut and patch them on the way out. The five patterns above account for somewhere around 60% of the violations we find on a typical React audit. Fix those five and you've meaningfully improved the experience for keyboard users and screen reader users on your site, with maybe an hour of work per component library.

The other thing worth saying: none of this requires a deep ARIA rabbit hole. Four of the five fixes above are vanilla HTML — <button>, <label htmlFor>, native <dialog>, visible text. ARIA is the escape hatch when HTML can't express what you mean. For most React tutorial residue, HTML is enough.

We're still finding new variants of each of these every week, so if you've got one we missed, drop it in the comments. We collect them.

Ready to find out what's actually broken on your site? Our accessibility audits cover automated scans plus manual walkthroughs, starting at $49. Get started

We Scanned 30 SaaS Pricing Pages for Accessibility. 70% Failed.

AgentKit — Mon, 13 Apr 2026 11:15:01 +0000

Nine out of 30 SaaS pricing pages had zero WCAG 2.1 AA violations when we ran them through axe-core this week. Figma, Netlify, Twilio, Zendesk, Calendly, Loom, Miro, Grammarly, Webflow. Clean results across the board.

The other 21 didn't come close.

What we tested and how

We pointed axe-core 4.11 at the pricing page of 30 SaaS products -- not their homepages, not their docs, specifically their pricing pages. The standard was WCAG 2.1 AA, and we ran every scan in a consistent headless Chromium environment with no browser extensions or user scripts that might interfere.

Why pricing pages? Because they're where the money changes hands. They tend to get heavy custom design treatment: comparison tables with intricate layouts, toggle switches between monthly and annual billing, gradient backgrounds behind plan names, animated feature lists. All of that increases the surface area for accessibility failures in ways that a simpler marketing page might not.

The scan completed on April 12, 2026. Every result below comes directly from axe-core output -- no manual evaluation, no subjective judgment calls.

The numbers

Across 30 sites, axe-core flagged 65 total violations touching 548 DOM nodes. The average was 2.2 violations per site, but that average hides a wide spread. Nine sites had nothing. Three sites -- Linear, Render, and Intercom -- had five violations each.

Color contrast was the most common single violation by a wide margin, appearing on 12 of the 30 pricing pages (40%). That tracks with what we see in basically every cohort we scan, but the prevalence on pricing pages is worth noting. These aren't obscure blog posts with inherited styles. Pricing pages get direct design attention, and still, 40% of them had text that didn't meet minimum contrast ratios against its background.

The second most common violation was list -- malformed list structures -- appearing on 8 sites. This one's a pricing page special. When you build a feature comparison table or a bulleted list of what's included in each tier, it's easy to use <div> elements styled to look like lists without actually being lists. Screen readers can't parse the structure, and the user loses the ability to navigate between items.

After that: aria-allowed-attr on 5 sites, link-name and button-name each on 4 sites, and then a longer tail of ARIA-related issues.

Who had the most violations

Linear's pricing page had 5 violations affecting 14 DOM nodes, including a critical aria-required-parent issue and color contrast failures across 3 elements. The list markup was malformed too -- <li> elements outside proper list containers, which affected 8 nodes.

Render also had 5 violations, but its node count was the highest in the entire cohort: 82 affected DOM elements. The bulk of that was 45 nodes failing color contrast and 34 buttons without accessible names. When axe-core flags 34 buttons on a single page without discernible text, that usually points to an icon button pattern where the icons are decorative and no aria-label was added.

Intercom rounded out the top three with 5 violations and 28 affected nodes. Three of those violations were critical severity, including 17 elements with ARIA roles that lacked required parent roles and 6 buttons without accessible names.

Below the top three, Vercel, PlanetScale, Stripe, SendGrid, HubSpot, Monday, and Asana each had 4 violations. Asana's case is interesting -- it only had 4 violation types, but 73 DOM nodes were affected, nearly all of them from invalid ARIA roles (70 nodes). That's likely a single component pattern replicated across every feature row in their pricing table.

Slack had just 2 violations, but one of them -- aria-command-name -- hit 96 DOM nodes. Sometimes a low violation count masks a large blast radius.

Who got it right

The nine clean sites: Figma, Netlify, Twilio, Zendesk, Calendly, Loom, Miro, Grammarly, Webflow.

What do they have in common? Honestly, not as much as you'd hope for a neat narrative. They span different industries (design tools, communications, scheduling, writing, web hosting). They use different tech stacks. Some have elaborate pricing pages with feature grids; others keep it simple.

If there's a through-line, it might be that several of these companies have publicly stated accessibility commitments. Figma has talked about accessibility in their design tool itself. Webflow literally sells website building and has a vested interest in demonstrating that their own output is accessible. Twilio and Zendesk both operate in spaces where enterprise customers with accessibility requirements are a significant part of their revenue.

But I'm speculating. The data just says they passed. Drawing causal conclusions from nine data points would be overreach.

Why pricing pages specifically

We've scanned other cohorts before -- landing pages, documentation sites, forms. Pricing pages consistently perform worse, and we think there are a few structural reasons.

Pricing pages are marketing pages that behave like application interfaces. They have interactive elements (toggles, sliders, accordions for FAQ sections, comparison table filters) layered on top of heavy visual design. That combination creates accessibility failure modes that a static marketing page wouldn't have.

There's also the custom-build problem. When a product team builds a comparison table for their three pricing tiers, they're often working from a one-off Figma design rather than pulling from a shared accessible component system. Custom means untested. Untested means aria-allowed-attr violations slip through.

And then there's the visual hierarchy pressure. You want the recommended plan to stand out. You want the CTA button to pop. That pressure toward visual emphasis creates exactly the conditions where contrast ratios get sacrificed -- a light gray "per user/month" label against a white card background, or a pastel-colored "most popular" badge that doesn't meet the 4.5:1 ratio.

The list violations tell the same story from a different angle. Feature lists on pricing pages are almost never actual <ul> elements. They're styled <div> stacks with checkmark icons, because that's what looks good in the design. The visual result is fine. The semantic result is invisible to assistive technology.

What this doesn't tell you

Automated scanning catches a specific category of issues. axe-core is good at finding color contrast failures, missing labels, malformed ARIA, and structural problems. It's not good at evaluating whether a screen reader user can actually complete the task of understanding and comparing pricing tiers. It can't tell you whether the tab order makes sense, or whether the plan toggle between monthly and annual actually announces its state change.

So the nine sites with zero violations aren't necessarily fully accessible. And the 21 sites with violations aren't necessarily unusable. What the data does tell you is the minimum bar -- these are issues that an automated tool can catch in under 10 seconds per page, and 70% of well-funded SaaS companies haven't cleared that bar on one of their most important pages.

We'll run this cohort again in a few months and see what changes.

We run automated accessibility scans weekly on different website cohorts. Read more at blog.a11yfix.dev.

Want to catch accessibility issues before your users do? We run WCAG audits with real assistive-tech testing, from $49. See options

We Ran Axe-Core On AI-Generated UI Code. The Findings Surprised Us.

AgentKit — Sat, 11 Apr 2026 15:18:57 +0000

Originally published at A11yFix.

We asked an AI coding assistant for five UI components that show up in almost every SaaS app: a login form, a pricing card, a confirmation modal, a top navigation bar, and a dashboard stats card. Same prompts you would probably type yourself on a Friday afternoon. Then we piped each result into axe-core through the same jsdom-based scanner we use inside our own build pipeline.

Here is the top-line number: 3 WCAG violations across 5 components, all of the same rule. That is a lot better than we expected. It is also less reassuring than it sounds. The interesting story is in what axe-core could not see.

The test setup, in boring detail

We used Claude Sonnet via the claude CLI as the code generator. No system prompt, no style preamble, just the same sort of one-line request a developer would paste into any AI coder — Cursor, v0, Bolt, Lovable, Claude Code — and expect back a component. The exact prompts and outputs live in our audit workspace; for reference, the login prompt was "Create a login form component as a single HTML snippet. Email input, password input, a remember me checkbox, a primary Sign in button, and a forgot password link. Use Tailwind classes." The other four were the same shape.

For the audit itself we used jsdom for the DOM, axe-core 4.11 for the rules, WCAG 2.1 AA and WCAG 2.2 AA tags enabled, plus the best-practice tag so landmark rules would actually fire. We disabled the color-contrast rule because jsdom cannot resolve Tailwind's JIT classes into real computed colors, so any result it gave us would be noise. We verified contrast by hand against the Tailwind palette instead — more on that in a moment.

Each component was wrapped in a minimal <!doctype html> page with no <main>, because that is what happens the instant a developer drops an AI-generated snippet into a blank page.tsx. If we padded the test harness with landmarks, we would be auditing our harness, not the component.

What axe-core flagged

Three violations. All of them the same rule: region, impact moderate. Eight nodes in the pricing card, four in the login form, one in the dashboard card. The modal and the navbar came back clean.

region fires when content lives outside of a landmark element — no <main>, no <nav>, no <section aria-label>. It is the rule screen reader users feel most directly, because their jump-to-landmark shortcut is how they navigate a page. When content lives in the void, they have to arrow through every element to find it.

The same two checks showed up as incomplete on every component except the modal: landmark-one-main and page-has-heading-one. Incomplete results are not violations — axe is telling you it cannot decide from static analysis alone and needs a human to confirm. In practice, on a component snippet, these resolve to "your host page had better supply the <main> and the <h1>, because this component is not going to." That is fine if the developer knows. The failure mode is that most developers do not read the incomplete list.

What the AI actually got right

This part we did not expect to write.

The login form has proper <label for="email"> / id="email" pairing, autocomplete="email" and autocomplete="current-password" hints, required attributes, and visible focus:ring-2 styles on every input and the submit button. The password input is a type="password" input, which sounds like a non-achievement until you remember how many tutorials ship a type="text" field because it was "easier to test."

The modal is the bigger surprise. It came back with role="dialog", aria-modal="true", aria-labelledby="modal-title", aria-describedby="modal-description", a close button with an explicit aria-label="Close", and an aria-hidden="true" on the decorative X icon. That is the full ARIA triad, correctly wired, on a first-shot prompt. A year ago this same prompt in the same tool would have given us a <div> with a close <span> and nothing else.

The navbar uses <nav>, wraps its links in <ul><li>, and uses real <a> elements for every destination including the "Sign up" call-to-action — not a <button> with a click handler pretending to be navigation. Semantic baseline, respected.

Color contrast, checked manually against the Tailwind palette: text-gray-700 on white is 10.4:1, the text-gray-500 used for secondary text is 5.6:1, the bg-indigo-600 button with white text is 6.1:1. All comfortably past WCAG AA's 4.5:1 threshold. Nothing failed. Including this because it is true, and skipping it would make this post dishonest.

The gap that axe-core cannot see

Here is where we have to slow down. A zero-violation automated scan on four of five components does not mean those components are accessible. It means they passed the checks that a static HTML parser is capable of running. The rest of WCAG lives in behavior.

The modal is the clearest example. It has every ARIA attribute a screen reader needs to announce it as a dialog. It has zero JavaScript. Open that modal in a real browser and press Tab: focus walks right off the "Delete" button and into whatever link is underneath the backdrop. A keyboard user has no way to know they have left the dialog, and no way to escape it with the Escape key, because nothing is listening. Axe-core cannot detect this. It audits a tree, not a runtime.

The dashboard card is another one. Semantically, it is a <div> containing a <p> for the label and a <p> for the value. Visually it reads as "Monthly Revenue: $48,210." To a screen reader it reads as two disconnected paragraphs. A proper card would use a heading (<h3> or the DL pattern with <dt> and <dd>) so the metric and its label are announced as a unit. Axe does not flag this because two <p> tags are valid HTML. They are just not meaningful HTML for this context.

The pricing card has the opposite flavor of the same problem. Its green checkmark SVGs are decorative — the feature name next to them is the actual content — but they have no aria-hidden="true" and no role="img" with a label. Axe did not flag them either, because axe is conservative about SVG. A verbose screen reader will still read "graphic" before every list item. Small paper cut, repeated five times per card.

Why this pattern shows up

AI coders have been trained on an enormous amount of HTML that mostly looks like the tutorials and component libraries a human has already published. So they are very good at reproducing surface correctness: label associations, ARIA attribute names, Tailwind contrast-safe colors, semantic list elements. The patterns that are visible in a static snapshot of code got learned thoroughly.

The patterns that live in runtime behavior did not. Nobody writes a blog post about the exact event listener that closes a modal on Escape. It is buried in a hook, or a library, or it just works because everyone uses Radix. AI output optimizes for the version you can paste into a file. It does not optimize for the version you can actually use with a keyboard.

This is not a tooling critique. It is a lifecycle observation. The accessibility gap in AI-generated UI is no longer "it forgot the label." It is "it remembered every attribute and forgot every interaction."

What to actually do about it

Put axe-core in CI, not as a gate but as a signal. Even a modest run catches the regressions that AI coders still make — missing landmarks, missing alt text on real images, buttons without accessible names in the parts of the app that nobody thinks to regenerate. We published a walkthrough for wiring this up as a GitHub Action in five minutes if you want a template.

Then do three manual checks the first time you accept any AI-generated component. Press Tab through every interactive element and confirm the focus indicator is visible and the order matches the visual order. Open any dialog or menu and press Escape, then try to Tab out of it — if either fails, you have work to do. Turn on VoiceOver or NVDA for sixty seconds and listen to the component. Most of what axe cannot catch becomes obvious within the first ten announcements.

We are going to run this same audit monthly against different AI coders and different prompts. Partly because the tools are moving fast and what we found today will not be true in six months. Partly because AI-generated UI is going to eat a huge share of the frontend we all end up shipping, and someone should be tracking how the accessibility baseline moves — up or down — as that happens.

If you want the full component files, the axe-core output, and the exact prompts we used, they are in the audit workspace on blog.a11yfix.dev. Next month: we rerun this on a more realistic prompt — a full signup page, not a single component — and see what breaks when the AI has to remember context across sections.

Not sure if your site meets WCAG standards? We run thorough audits combining automated scans and human testing, starting at $49. Check it out

How to Write Alt Text That Screen Readers Actually Find Useful (With 15 Examples)

AgentKit — Thu, 09 Apr 2026 23:43:57 +0000

Originally published at A11yFix.

i used to think alt text was simple. describe what you see, move on. then i started testing my sites with VoiceOver and realized most of my alt text was either useless or actively confusing.

the problem isn't laziness. it's that nobody teaches you what good alt text actually sounds like when a screen reader reads it out loud. so here are 15 examples from real audits -- what was there, what should have been there, and why.

the golden rule nobody follows

alt text should communicate what the image means, not what it looks like. sounds obvious until you try it.

product images

bad: alt="shoes"
good: alt="Nike Air Max 90 in white and grey, side view"

bad: alt="product photo"
good: alt="hand-poured soy candle in amber glass jar, 8oz"

screen reader users are shopping. they need to know what they're buying, not that there's a photo on the page.

charts and data

bad: alt="bar chart"
good: alt="monthly revenue chart showing 40% growth from January to March 2026"

bad: alt="graph"
good: alt="comparison chart: automated tools caught 168 issues, manual testing found an additional 147"

this one drives me nuts. "bar chart" tells a blind user there's a chart. so what? what does the chart say? that's the alt text.

screenshots

bad: alt="screenshot of dashboard"
good: alt="analytics dashboard showing 720 page views and 14 reactions across 30 articles"

bad: alt="error message"
good: alt="browser console error: Cannot read property 'click' of null at line 47"

if you took the screenshot to show something specific, that specific thing is your alt text.

decorative images

bad: alt="decorative border" or alt="background pattern"
good: alt=""

empty alt. not missing -- deliberately empty. this tells screen readers to skip it entirely. decorative images with alt text are noise.

the markup: <img src="border.png" alt="" role="presentation">

icons with text

bad: alt="icon" on a search icon next to "Search"
good: alt="" (the text label already communicates the function)

bad: alt="" on a hamburger menu icon with no visible text
good: alt="Menu" or better: use aria-label="Menu" on the button

rule of thumb: if there's visible text next to the icon that says the same thing, the icon alt should be empty. if the icon is the only indicator of function, it needs alt text.

logos

bad: alt="logo"
good: alt="AgentKit" or alt="AgentKit - home"

the alt should be the company name, not the word "logo". when it links to the homepage, include that context.

complex infographics

bad: alt="infographic about accessibility"
good: provide a text alternative nearby, and use alt="Accessibility compliance roadmap, detailed description below"

some images can't be described in a short alt attribute. that's fine. describe what it is briefly in alt, then provide the full content as text on the page.

the context test

here's the trick i use now: cover the image with your hand and read the surrounding text. does the paragraph still make sense? if not, the image is carrying meaning that needs to be in the alt text.

if the paragraph works fine without the image, the image is decorative. alt="".

the 5-second rule

if you can't write the alt text in 5 seconds, the image is probably too complex for a simple alt attribute. use a longer text description nearby instead.

not every image needs alt text. not every alt text needs to be long. but every alt text needs to be useful.

if you want the full checklist with 100+ checks like this, i put one together at blog.a11yfix.dev. also available as a printable pdf on etsy.

if you want a systematic way to check your site's accessibility, grab the free 10-point EAA quick-check at blog.a11yfix.dev.

Want a professional audit of your own site? We run real WCAG scans paired with human walkthroughs, starting at $49. Check pricing and options here

Screen Reader Testing for Developers: What VoiceOver Actually Announces (And Why It Matters)

AgentKit — Thu, 09 Apr 2026 03:00:18 +0000

Originally published at A11yFix.

I've been building websites for years, and I'll be honest: for most of that time, I had never actually turned on a screen reader. I assumed my HTML was "fine" because it looked right in the browser. Then I fired up VoiceOver on my Mac, navigated one of my own pages, and realized how wrong I was.

This guide is what I wish someone had handed me on day one. No theory-heavy lecture --- just practical steps to test your pages with VoiceOver and understand what users actually hear.

How to Turn On VoiceOver (It Takes 5 Seconds)

On any Mac, press Cmd + F5. That's it. VoiceOver starts talking immediately.

A few essentials before you start navigating:

VO keys: VoiceOver uses a modifier combination. By default, it's Control + Option (referred to as "VO" in documentation). You hold these while pressing other keys.
VO + Right Arrow: Move to the next element on the page.
VO + Left Arrow: Move to the previous element.
VO + Space: Activate (click) the current element.
VO + U: Open the rotor --- a quick menu for headings, links, landmarks, and more.
VO + A: Read everything from the current position forward.

Open Safari (VoiceOver works best with Safari on Mac), navigate to your site, and start pressing VO + Right Arrow to walk through the page element by element.

What to Listen For

As you navigate, pay attention to what VoiceOver actually says for each element. It typically announces:

The role: "heading level 2," "link," "button," "image"
The accessible name: the text content, aria-label, or alt attribute
The state: "dimmed," "selected," "expanded"

A well-structured page sounds like a clear outline. A poorly structured page sounds like a random collection of text fragments with no context.

Surprise #1: Your Clickable Div Is Invisible

This is the most common shock. You have something like:

<div class="card" onclick="openDetail()">
  <h3>Premium Plan</h3>
  <p>$29/month</p>
</div>

You click it with your mouse every day. It works perfectly. But navigate to it with VoiceOver and you hear... nothing useful. VoiceOver announces "group" or just reads the text content with no indication that this thing is interactive.

A screen reader user has no idea they can activate this element. It doesn't show up in the links or buttons list in the rotor. It's effectively invisible as an interactive element.

The fix:

<div class="card" role="button" tabindex="0"
     onclick="openDetail()"
     onkeydown="if(event.key==='Enter') openDetail()">
  <h3>Premium Plan</h3>
  <p>$29/month</p>
</div>

Or better yet, use a real <button> and style it:

<button class="card" onclick="openDetail()">
  <h3>Premium Plan</h3>
  <p>$29/month</p>
</button>

Now VoiceOver says "Premium Plan, $29/month, button." That's a massive difference.

Surprise #2: aria-label Overrides Your Visible Text

This one catches developers who are trying to "help" screen reader users:

<a href="/pricing" aria-label="Click here to view our pricing page">
  View Pricing
</a>

Sighted users see "View Pricing." VoiceOver users hear "Click here to view our pricing page, link." These are different experiences, and the mismatch causes real problems.

If a sighted coworker says "click the View Pricing link," a screen reader user searching for that text won't find it. The rotor's link list will show "Click here to view our pricing page" instead.

The rule: aria-label replaces the accessible name entirely. Only use it when the visible text alone doesn't provide enough context, and try to keep it consistent with what's visible. In most cases, well-written visible text is all you need.

Surprise #3: Missing Heading Hierarchy Destroys Navigation

Screen reader users rely heavily on headings to navigate. Press VO + U and select the Headings list. This is how many users get an overview of your page.

If your heading hierarchy looks like this:

h1: Welcome
h3: Our Services    (where's h2?)
h3: About Us
h5: Contact         (jumped from h3 to h5?)

The navigation experience is confusing. Users wonder if they're missing sections. Tools like axe will flag this, but hearing it through VoiceOver makes the problem visceral.

The fix: Use headings in order. Every page gets one h1. Sections get h2. Subsections get h3. It's not about font size --- CSS handles that. It's about document structure.

Surprise #4: Forms Without Labels Are Guessing Games

<input type="email" placeholder="Enter your email">

VoiceOver announces: "edit text." That's it. The placeholder text might show visually, but it's not a reliable accessible name.

<label for="email">Email address</label>
<input type="email" id="email" placeholder="you@example.com">

Now VoiceOver says: "Email address, edit text." The user knows exactly what to type.

A 10-Minute Testing Routine

Here's what I do now before shipping any feature:

Cmd + F5 to start VoiceOver
VO + Right Arrow through the entire new feature, listening for:
- Can I tell what every interactive element does?
- Do buttons and links have clear names?
- Are images described or correctly marked as decorative?
VO + U to check the headings list --- does it make sense as an outline?
Tab through all interactive elements --- can I reach and activate everything?
VO + Space on buttons and links --- do they work?
Cmd + F5 to turn VoiceOver off

That's it. Ten minutes. You'll catch more accessibility issues in those ten minutes than in hours of staring at automated scan results.

Why This Matters More Than You Think

Starting June 2025, the European Accessibility Act requires digital products and services to be accessible. That's not a suggestion --- it's law, with real enforcement. Similar regulations are expanding worldwide.

But beyond compliance, testing with a screen reader connects you with how real people use your product. About 2.2 billion people worldwide have some form of vision impairment. When you hear VoiceOver stumble through your UI, those aren't abstract "accessibility issues" --- they're barriers.

Turn on VoiceOver today. Navigate your own site. Listen to what it actually says. I promise you'll find at least one thing that surprises you.

If you're working on accessibility compliance, I put together a free 10-point EAA quick-check: Get the free checklist

The full 100+ item checklist is also available as a printable PDF on Etsy.

Wondering how your site stacks up? Our audit combines automated WCAG scanning with manual testing, from $49. See what's included

Screen Reader Testing in 5 Minutes: A Developer's Quick Start Guide

AgentKit — Wed, 08 Apr 2026 00:11:30 +0000

Originally published at A11yFix.

I'll be honest: the first time I tried to test my website with a screen reader, I panicked. A robotic voice started reading everything on my page at top speed, I couldn't figure out how to stop it, and I ended up force-quitting the application. Sound familiar?

Here's what I wish someone had told me: screen reader testing doesn't have to be scary, and you can learn the basics in about five minutes. This guide will get you from zero to actually running a meaningful screen reader test on your website.

Why Bother Testing with a Screen Reader?

Automated accessibility tools catch roughly 30-40% of accessibility issues. The rest? You need manual testing. Screen readers reveal problems that no linter or CI check will find:

Images with meaningless alt text ("image123.png")
Form fields that have no programmatic label
Custom components that look interactive but can't be reached with a keyboard
Content that appears visually ordered but reads in a confusing sequence

You don't need to become an expert. You just need to catch the obvious problems.

VoiceOver on Mac (Built-in, Zero Setup)

VoiceOver is already on your Mac. No downloads, no installs.

Turn it on: Press Cmd + F5 (or touch the Touch ID button three times if you've set that up).

Essential shortcuts:

Action	Shortcut
Move to next element	`VO + Right Arrow` (VO = Ctrl + Option)
Move to previous element	`VO + Left Arrow`
Activate a link/button	`VO + Space`
Read the current element	`VO + A`
Open the Rotor (navigation menu)	`VO + U`
Turn VoiceOver off	`Cmd + F5`

Your first test in 60 seconds:

Open your site in Safari (VoiceOver works best with Safari)
Turn on VoiceOver with Cmd + F5
Press VO + Right Arrow repeatedly to move through elements
Listen: does each element make sense on its own? Does a button say "Submit your application" or just "Click here"?
Press VO + U to open the Rotor, then arrow to "Headings" - is your heading structure logical?
Turn it off with Cmd + F5

NVDA on Windows (Free Download)

NVDA is a free, open-source screen reader. Download it from nvaccess.org.

Essential shortcuts:

Action	Shortcut
Move to next element	`Down Arrow`
Move to previous element	`Up Arrow`
Activate a link/button	`Enter`
List all headings	`H` (next heading) or `Insert + F7`
List all links	`K` (next link) or `Insert + F7` then select Links
Toggle speech on/off	`Insert + S`
Stop speaking	`Ctrl`

Tip: NVDA defaults to "Browse mode" in web content, which means single-letter navigation works. Press H to jump to the next heading, F for the next form field, T for the next table.

What to Listen For: A 5-Point Check

Once you can navigate, here's a quick checklist. Run through these five checks and you'll catch the majority of screen reader issues:

1. Page Title

When the page loads, does the screen reader announce a meaningful title? "Dashboard - MyApp" is good. "React App" is not.

2. Heading Structure

Navigate through headings (Rotor on Mac, H key on NVDA). You should hear a logical hierarchy: H1 for the page title, H2 for sections, H3 for subsections. Skipped levels or missing headings mean users can't scan your page.

3. Link and Button Labels

Tab through interactive elements. Each one should announce what it does. "Read more about pricing plans" tells users where they're going. "Read more" repeated six times does not. "Button" with no label is a dealbreaker.

4. Form Labels

Navigate to a form and listen. Each input should announce its label when focused. If you hear "edit text" with no context, your input is missing a programmatic label. This is one of the most common accessibility failures, and one of the easiest to fix with a proper <label> element.

5. Image Alt Text

Navigate through images. Decorative images should be silent (empty alt=""). Informational images should describe their content. If you hear a filename or a generic "image," that's a problem.

Common Gotchas

The screen reader won't stop talking. Press Ctrl to silence it. This works in both VoiceOver and NVDA.

VoiceOver isn't reading my page correctly. Make sure you're using Safari. VoiceOver's best support is with Safari, not Chrome or Firefox.

NVDA isn't responding to single-key navigation. You might be in "Focus mode" instead of "Browse mode." Press Insert + Space to toggle.

Custom components aren't announced properly. If you built a dropdown or modal with <div> elements, add ARIA roles and states. But first, consider whether a native HTML element (like <select> or <dialog>) would work instead.

Make It a Habit

You don't need to run a full screen reader audit on every commit. But doing this 5-minute check on key pages, especially after building new features, will catch problems before your users do.

My recommendation: pick one page right now, turn on VoiceOver or NVDA, and run through the five checks above. You'll be surprised what you find.

If you're working on accessibility compliance, I put together a free 10-point EAA quick-check: Get the free checklist

Need to know where your site stands on accessibility? We do thorough WCAG audits with real assistive-technology testing, starting at $49. View pricing

How to Set Up Automated Accessibility Testing in GitHub Actions (Copy-Paste Config)

AgentKit — Tue, 07 Apr 2026 08:30:20 +0000

Originally published at A11yFix.

Last month I inherited a project where accessibility was "on the roadmap." Translation: nobody had touched it. Rather than rely on manual audits that happen once a quarter (if you're lucky), I set up automated accessibility testing that runs on every pull request. It took about 20 minutes, and now no PR merges if it introduces accessibility violations.

Here's exactly how to do it.

Why axe-core + Playwright?

There are plenty of accessibility testing tools out there, but this combination hits a sweet spot:

axe-core is the industry standard engine behind most accessibility tools. It catches real WCAG violations, not theoretical ones.
Playwright gives you a real browser environment, so you're testing what users actually see -- not just static HTML.
Both are free and open source.

Together they catch around 30-40% of WCAG 2.1 issues automatically. That won't replace manual testing, but it prevents regressions and catches the low-hanging fruit before a human ever looks at the page.

Step 1: Install the dependencies

npm install -D @axe-core/playwright @playwright/test
npx playwright install chromium

Step 2: Create the accessibility test file

Create tests/accessibility.spec.ts:

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

const pagesToTest = [
  { name: "Home", path: "/" },
  { name: "About", path: "/about" },
  // Add your routes here
];

for (const { name, path } of pagesToTest) {
  test(`${name} page should have no accessibility violations`, async ({
    page,
  }) => {
    await page.goto(path);

    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
      .analyze();

    const violations = results.violations.map((v) => ({
      id: v.id,
      impact: v.impact,
      description: "v.description,"
      nodes: v.nodes.length,
    }));

    if (violations.length > 0) {
      console.log("Accessibility violations found:");
      console.log(JSON.stringify(violations, null, 2));
    }

    expect(results.violations).toEqual([]);
  });
}

A few things to note:

withTags filters to WCAG 2.1 Level AA rules. That's the standard most regulations (including the European Accessibility Act) point to.
The test logs structured violation data before failing, so you can see exactly what's wrong in the CI output.
Adding new pages is just adding an entry to the array.

Step 3: Configure Playwright

If you don't already have a playwright.config.ts, create one:

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  use: {
    baseURL: "http://localhost:3000",
  },
  webServer: {
    command: "npm run start",
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
});

Adjust the command and port to match your project. If you're using Next.js, npm run start works after a build. For Vite, use npm run preview. The key is that Playwright spins up your server automatically during CI.

Step 4: The GitHub Actions workflow

Create .github/workflows/accessibility.yml:

name: Accessibility Tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Build
        run: npm run build

      - name: Run accessibility tests
        run: npx playwright test tests/accessibility.spec.ts

      - name: Upload test results
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: a11y-report
          path: test-results/
          retention-days: 7

That's it. Copy that file into your repo and accessibility testing runs on every PR.

The if: failure() on the upload step means you only get artifacts when tests fail -- so you can dig into the details without cluttering up passing runs.

Step 5: Handle violations without blocking everything

Sometimes you need to ship a feature while you fix an existing accessibility issue. You can exclude specific rules temporarily:

const results = await new AxeBuilder({ page })
  .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
  .disableRules(["color-contrast"]) // TODO: Fix by sprint 23
  .analyze();

I recommend adding a comment with a deadline and tracking these exclusions. They have a tendency to become permanent if you don't.

What this catches (and what it doesn't)

Automated testing reliably catches:

Missing alt text on images
Missing form labels
Broken ARIA attributes
Insufficient color contrast
Missing document language
Incorrect heading hierarchy

It won't catch:

Whether alt text is actually meaningful
Keyboard navigation flow issues
Screen reader announcement quality
Complex interactive widget behavior

That's why automated testing is a safety net, not a replacement for real accessibility work. But a safety net that runs on every PR is a lot better than a manual audit that happens twice a year.

Making it work with your stack

If you're using a static site or SSR framework, the config above works as-is. For SPAs, make sure Playwright waits for your app to hydrate. You might need to add a waitUntil: 'networkidle' option to page.goto(), or wait for a specific element to appear before running the analysis.

For monorepos, point the testDir and webServer config at the right package, and you're set.

Automated accessibility testing won't make your site fully accessible overnight. But it draws a line: from this point forward, we don't ship new violations. That's a meaningful starting point.

If you're working on accessibility compliance, I put together a free 10-point EAA quick-check: Get the free checklist

The full 100+ item checklist is also available as a printable PDF on Etsy.

Curious about your own site's accessibility gaps? We offer WCAG audits that go beyond automated scans, starting at $49. Learn more