---
title: "Accessibility for AI Coding Agents Is a Defaults Problem"
description: "Accessibility for AI coding agents is a defaults problem: 95.9% of home pages fail automated WCAG checks, so an agent trained on the web ships those barriers faster."
author: "MDflow"
date: 2026-11-21
reading_time: "15 min"
canonical_url: https://mdflow.cz/blog/accessibility-for-ai-coding-agents
md_url: https://mdflow.cz/blog/accessibility-for-ai-coding-agents.md
---

# Accessibility for AI Coding Agents Is a Defaults Problem

*Published November 21, 2026 · 15 min read*


Close your eyes. Now unlock your phone, open the notes app, and type "hello world."

Jemima Abu opened her AI Engineer talk by making a room full of engineers try exactly that. Some managed on muscle memory. Nobody enjoyed it. Her point landed before a single slide did: for a lot of people that is not an exercise, it is the permanent condition under which they use your product — and **accessibility for AI coding agents** is now the question of whether the code being generated at speed is usable by them at all.

> **TL;DR** — Accessibility is a defaults problem, not an effort problem. An agent reproduces the web it learned from, and 95.9% of the top million home pages have detected WCAG failures, so the default output is inaccessible. Fixing it means changing what "default" means: accessible primitives in the design system, deterministic checks in CI, and one versioned requirements document every agent can retrieve — the kind of document a markdown workspace like [MDflow](https://mdflow.cz) is for. [Start free](/login).

## What accessibility for AI coding agents means

**It means deciding, before the agent writes anything, that the accessible pattern is the one it reaches for by default.** Accessibility itself is unchanged: the practice of building products people can use regardless of disability. The [WHO](https://www.who.int/news-room/fact-sheets/detail/disability-and-health) puts that population at an estimated 1.3 billion people — 16% of the world, or one in six.

What changed is who types. When a person writes a component, the accessible choice is one decision they can be trained to make. When an agent writes forty components in an afternoon, the choice has already been made forty times by whatever the model considered normal. You are no longer correcting a developer; you are setting a prior.

The framing here comes from [*Teach Your AI Agent to Build Products Everyone Can Use*](https://www.youtube.com/watch?v=YV1x6gCdgQA), Abu's talk at AI Engineer, published on 9 November 2026. Abu is a product engineer at CAIS, a Google Developer Expert, and certified in accessibility core competencies.

## Why agents default to inaccessible patterns

**Because the corpus is the web, and the web fails.** This is the part that is not a matter of opinion.

WebAIM's [annual scan](https://webaim.org/projects/million/) of the top one million home pages, run in February 2026, found **detected WCAG 2 failures on 95.9%** of them — up from 94.8% a year earlier, which WebAIM describes as reversing a trend of gradual improvement. The average page carried **56.1 distinct errors**, a 10.1% increase on the previous year's 51. Because automated testing only sees part of the picture, WebAIM notes that actual full conformance is "certainly lower than 4.1%."

The failures are also boringly consistent. Six categories — low contrast text (83.9% of pages), missing alternative text (53.1%), missing form input labels (51%), empty links (46.3%), empty buttons (30.6%) and missing document language (13.5%) — account for 96% of all errors detected, and have been the same six for seven years. That is the distribution a model learned from.

Three mechanisms turn that corpus into your pull request:

**1. Popular beats correct.** An agent optimises for the pattern it saw most, and the most common implementation of a UI widget is rarely the simplest correct one. Abu's example is the accordion: most public code implements it with custom JavaScript, while HTML has `<details>` and `<summary>`, which [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details) describes as a disclosure widget that opens on click or on space when focused, carries an implicit `group` role, and — with a shared `name` attribute across several of them — gives you an exclusive accordion "without scripting." Less code, browser-maintained behaviour, nothing to get wrong.

> One pairing worth a footnote: the talk also suggests `popover` where you would build a modal. MDN is explicit that [popovers are always non-modal](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) and that `<dialog>` is the right way to build a modal — `showModal()` is what makes the rest of the page inert and gives you Esc-to-close and a styleable `::backdrop`. Native-first is the correct instinct; which native element is the detail your skill has to get right, because the agent will not check.

**2. Volume multiplies the default.** Agents write more code than people do, and generated code tends toward the verbose implementation rather than the four-line platform one. Every extra bespoke widget is extra surface where keyboard operation, focus order and naming can be wrong.

**3. Your repository is the strongest prompt in the room.** Abu's analogy: a roommate who moves into a flat with dishes already in the sink will never do dishes. An agent dropped into a codebase full of `div` buttons reads them as the convention and produces more. This is the same argument the lint-rules research makes about [prose versus enforcement](/blog/lint-rules-for-ai-coding-agents) — what is already in the repo outweighs what you wrote in a rules file.

There is a fourth signal in the WebAIM data worth sitting with. Home pages using ARIA averaged **59.1 errors against 42** on pages with none. Read that carefully: it is a correlation, and pages that reach for ARIA are usually the more complex ones to begin with. But it is a hard argument against the reflex of bolting ARIA onto finished markup. ARIA is not a layer you add at the end; it is a tool for the cases where no native element exists.

## What inaccessible output actually costs

**Users, money, and rework — in that order.**

**Users leave without telling you.** Abu's sharpest line is about the business that says none of its users rely on assistive technology. They don't, because they couldn't get in: it is a shop complaining nobody comes through a door it never built. The customer who could not operate your onboarding flow is simply at a competitor, and never appears in your analytics as a loss.

**Legal exposure is rising, not plateauing.** Seyfarth Shaw [counted 3,117 federal website-accessibility lawsuits in the US in 2025](https://www.adatitleiii.com/2026/03/federal-court-website-accessibility-lawsuit-filings-bounce-back-in-2025/), a 27% increase on 2024's 2,452, making up 36% of all federal ADA Title III filings — and they note that state-court filings and demand letters are not in that count. In the EU, the [European Accessibility Act](https://eur-lex.europa.eu/eli/dir/2019/882/oj) has been applicable since 28 June 2025 to in-scope consumer services, including e-commerce, with websites and mobile apps explicitly covered.

**Retrofits cost more than defaults.** Abu's image for a site made accessible at the end is a plain muffin with blueberries pressed into the top. The structural fixes — a heading order, a focus sequence, a form that announces its errors — are not attributes you can sprinkle on finished components; they are the components. Nor is there a product that does it for you: the [Overlay Fact Sheet](https://overlayfactsheet.com/en/), signed by hundreds of accessibility practitioners, states that "no overlay product on the market can cause a website to become fully compliant" with any existing standard "and therefore cannot eliminate legal risk."

And the cheerful possibility, offered with the honesty it deserves: Abu ran one Figma implementation prompt twice, with and without an accessibility skill, and reported 15 minutes falling to 5 with a 58% cost reduction. She disclaimed it on stage — one run, unconstrained, not empirical data. Take it as a plausible direction, not a benchmark. The mechanism is at least sensible: an agent that knows to reach for `<details>` stops generating two hundred lines of accordion.

## Which teams benefit most

1. **Consumer web products in the US or EU** — the ones directly inside ADA Title III and EAA scope, where the cost of a bad default has a dollar figure attached.
2. **Design-system and component-library owners** — the highest-leverage place to work, because one fixed primitive fixes every page that consumes it.
3. **Public-sector and regulated suppliers** — accessibility conformance is a procurement gate, and claims about it are audited.
4. **Teams where agents write most of the UI** — the volume argument; a bad default compounds at the rate you ship.
5. **Non-specialists shipping interfaces** — backend engineers, PMs and designers now merging front-end code with agent help, who never had the accessibility training the default assumes.
6. **Native mobile teams** — the requirements differ from the web, so a web-flavoured checklist copied off the internet is the wrong document.

## How to teach an agent accessibility

Abu's four steps are the right spine: **define your requirements**, **audit the existing codebase**, **implement a design system**, and **make the guidelines mandatory** for every run. Layer them by how strongly each one binds.

**Defaults in code, first.** Native elements and audited design-system components. A primitive an agent can only use correctly beats any instruction about using it correctly. This is also where the codebase audit pays off: deleting the `div` buttons removes the bad example, not just the bad advice.

**Deterministic checks, second.** `eslint-plugin-jsx-a11y` in the editor and the pre-commit hook, `axe-core` in CI against rendered pages. These fail the build identically for every agent and every human, and the error message is itself a prompt — a failing rule teaches the next run in a way a rules file does not. Between them they cover the WebAIM six: the lint rules catch missing labels, missing `alt` and empty interactive elements in source, while contrast and document language need the rendered page, which is axe-core's job.

**The skill, third.** Prose carries what no check can: which standard you are holding to, which components are blessed, what to do when neither is obvious. Something like this — an illustration, not Abu's file, which the talk only paraphrased:

```markdown
# Accessibility requirements

Target: WCAG 2.2 AA. Applies to every component in `src/ui`.

## Always
- Semantic HTML first. Reach for ARIA only when no native element fits.
- Every interactive element must be operable by keyboard alone, with a
  visible focus indicator.
- Every form input has a programmatically associated label.
- Images carry meaningful `alt`; decorative images carry `alt=""`.
- Text meets 4.5:1 contrast (3:1 for large text and UI boundaries).

## Prefer the platform
- Disclosure / accordion: `<details>` + `<summary>` (shared `name` for
  exclusive accordions), not a custom JS widget.
- Modal: `<dialog>` + `showModal()`. Not `popover`, which is non-modal.
- Use a design-system component where one exists; do not re-implement it.

## Never
- `div` or `span` as a button or link.
- Removing focus outlines without replacing them.
- Positive `tabindex` values.
```

**Published guidance, alongside it.** Chrome's [Modern Web Guidance](https://developer.chrome.com/docs/modern-web-guidance) — a set of agent skills plus a CLI, released 1.0 with input from Mozilla and Microsoft — exists precisely to stop agents defaulting to the dated popular pattern, and ships an accessibility guide covering semantic HTML, focus management, forms and media. It installs with `npx modern-web-guidance@latest install`, assumes Baseline "Widely available" features unless you state a different target in `AGENTS.md` or `CLAUDE.md`, and Chrome reports a 37-percentage-point improvement in adherence to modern best practices in its own early evaluations, with the caveat that your results may vary.

**Human testing, last and unskippable.** Keyboard-only walkthroughs, a screen reader, and disabled users. WebAIM's own caveat is the honest ceiling on everything above it: absence of detected errors does not mean a page is accessible.

## How MDflow fits

Notice what step one actually requires: **a single accessibility requirements document that every agent and every tool reads the same way.** Not a paragraph in one repo's `CLAUDE.md`, a second copy in another repo, and a third in a Notion page the agents cannot open. Requirements differ per product and per platform, they get revised, and they are useless the moment two copies disagree.

What [MDflow](https://mdflow.cz) does today:

- **Markdown, not a proprietary document format.** The requirements document is the same text a human reviews and an agent retrieves — no export step, no fidelity loss.
- **Folder descriptions as the retrieval signal.** MDflow ranks folder descriptions above folder names and document titles in [`mdflow_get_context`](/docs/mcp), so a description like *"accessibility requirements — WCAG 2.2 AA, web only; mobile standards live in /mobile-standards"* routes an agent to the right document without a vector index.
- **One copy, many clients.** The hosted MCP server at `/api/mcp` and the versioned [HTTP API](/docs/api) under `/api/v1` serve the same workspace to Claude Code, Claude Desktop, Cursor, Codex and ChatGPT, plus any CI script holding a token. Claude connects in one click through the [MDflow connector](https://claude.ai/directory/mdflow).
- **Writes are attributable.** In a personal workspace, the Document Log at `/log` records created, edited, shared and deleted events with the actor on every row — `you` for browser actions, `automated · <token name>` for anything arriving over the API or MCP — so a change to the standard is never anonymous. Team accounts keep their own audit feed of lifecycle changes instead, retained 365 days.
- **Version history across every write path.** Capture covers the editor, the HTTP API and the MCP server, with a line-by-line diff and a non-destructive restore (Pro; 30 days or 300 versions).
- **Shared with a team or published.** Team workspaces carry per-workspace read-only or full access, and any shared document has a raw `.md` twin with YAML frontmatter that an agent can fetch and cite in one request.

Three limits worth stating plainly, because the previous section is an argument for enforcement:

- **MDflow stores the standard; it cannot enforce it.** Nothing in a workspace fails a build. Enforcement belongs in `eslint-plugin-jsx-a11y`, `axe-core` and CI, and this post is not arguing otherwise.
- **Personal access tokens are account-wide and read-write.** There is no read-only or workspace-scoped personal token, so a token handed to a CI job can write as well as read. Only Team tokens are scoped.
- **Version history is not exposed over the API or MCP.** An agent can read the current standard but cannot ask what changed in it last month; that diff is in the editor only.

Where this is headed — direction, not a dated commitment: narrower, read-only credentials for agents that should only consume context, and making document history reachable by the tools that write the documents, so an agent can see a requirement's history rather than just its latest text.

## The bottom line

The uncomfortable version of Abu's argument is that agents are not making accessibility worse — they are making our existing defaults visible at scale. A team whose real standard was "whatever the developer remembered" now has that standard executed hundreds of times a week, perfectly consistently, by something that never gets tired of being wrong.

So fix the defaults rather than the output. Put accessible primitives in the design system, deterministic checks in CI, your actual requirements in one document every agent can retrieve, and human testing at the end where no automation reaches. The skill is the cheapest part of that, which is why it is worth writing today.

[Start free](/login) · [Connect an AI agent](/docs/mcp) · [Read the API docs](/docs/api)

## Frequently asked questions

### Why does AI-generated code tend to be inaccessible?

Because the pattern an agent reaches for is the pattern it saw most, and the web it learned from mostly fails. WebAIM's February 2026 scan of the top million home pages found detected WCAG 2 failures on 95.9% of them, averaging 56.1 errors per page. An agent does not weigh correctness against popularity; a custom JavaScript widget appears far more often in public code than the native element that does the same job accessibly, so that is what gets generated. Your own codebase compounds it: an agent reads existing workarounds as house style.

### Does giving an agent an accessibility skill make it cheaper and faster?

There is one public anecdote and no good evidence. In her AI Engineer talk, Jemima Abu ran the same Figma implementation prompt twice, once with an accessibility skill and once without, and reported 15 minutes down to 5 and a 58% cost reduction. She disclaimed the result herself as a one-off in an unconstrained environment, not empirical data. Treat the direction as plausible — fewer tokens spent reinventing a native element — and the numbers as a single run.

### Can automated accessibility testing prove a site is accessible?

No. Automated tools catch a subset of failures, and WebAIM states plainly that absence of detected errors does not indicate a page is accessible or conformant. Automated checks are the right thing to run on every pull request because they are cheap and deterministic, but keyboard-only walkthroughs, screen-reader testing and testing with disabled users cover what no linter can see. The point of automation is to stop the regressions that are mechanically detectable, not to issue a pass.

### Do accessibility overlays fix AI-generated accessibility problems?

No. The Overlay Fact Sheet, signed by hundreds of accessibility practitioners, states that no overlay product on the market can cause a website to become fully compliant with any existing accessibility standard and therefore cannot eliminate legal risk. An overlay is a script bolted on after the fact; it does not change the markup an agent generated. The same applies to a cleanup pass that sprays ARIA attributes over finished components.

### Where should a team's accessibility requirements live so every agent reads them?

In one versioned markdown document that each agent can retrieve on its own credentials, rather than pasted into several rules files that drift apart. Accessibility requirements differ by product — a web app and a native mobile app answer to different standards — so the document is yours, not a generic checklist. A markdown workspace such as MDflow holds it over MCP and an HTTP API, so Claude, Cursor, Codex and a CI job all read the same copy.

## Further reading

- [*Teach Your AI Agent to Build Products Everyone Can Use*](https://www.youtube.com/watch?v=YV1x6gCdgQA) — Jemima Abu, AI Engineer, 9 November 2026
- [The WebAIM Million](https://webaim.org/projects/million/) — the February 2026 accessibility analysis of the top 1,000,000 home pages
- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) — W3C Web Content Accessibility Guidelines
- [Modern Web Guidance](https://developer.chrome.com/docs/modern-web-guidance) — Chrome's agent skills for modern web platform features
- [Overlay Fact Sheet](https://overlayfactsheet.com/en/) — what accessibility overlays can and cannot do
- [Federal website accessibility lawsuit filings in 2025](https://www.adatitleiii.com/2026/03/federal-court-website-accessibility-lawsuit-filings-bounce-back-in-2025/) — Seyfarth Shaw, March 2026
- [Disability and health](https://www.who.int/news-room/fact-sheets/detail/disability-and-health) — World Health Organization fact sheet
- [Lint Rules Beat Rules Files for AI Coding Agents](/blog/lint-rules-for-ai-coding-agents) — why a correction belongs in a check, not a paragraph
- [On-Device AI Agents Run on a 16-Millisecond Budget](/blog/on-device-ai-agents-compute-budget) — accessibility as a continuously tuned dial, not a toggle
- [Connect an AI agent to MDflow over MCP](/docs/mcp) · [MDflow HTTP API](/docs/api) · [FAQ](/faq)

