Accessibility overlay vs real fixes: what actually works

Two kinds of overlay

A runtime repair overlay is a script added to a production site. When a visitor loads the page, it scans the DOM and changes it: it adds attributes, generates alt text, adjusts colors, and often adds a toolbar with options such as bigger text, higher contrast or a reading guide. The promise is that a site becomes accessible without changing its code.

A diagnostic overlay is a tool for the people who build the site. It scans the page and shows the problems, but it does not change anything for visitors. The a11ymedic overlay is this second kind. It draws numbered pins on the elements that fail, and opens a side panel that explains each problem, who it affects, which WCAG criteria it fails, and the exact code to fix it. It never edits the page content, never invents alt text, and never changes colors on the live site.

What runtime repair can and cannot do

Some changes really can be made safely at runtime. Adding lang="en" to a page in English, or removing user-scalable=no from the viewport tag, needs no knowledge of the content. But most accessibility problems are about meaning, and meaning is not in the DOM:

• Alt text. A script can guess that a photo shows "a person smiling". It cannot know that the photo is the new head of nursing, or that the chart shows signups doubling. A wrong description can be worse than none, because the user trusts it.
• Names of controls. An icon button with an SVG could mean close, delete, mute or collapse. Guessing wrong sends a screen reader user into the wrong action.
• Structure. Turning a styled <div> into a heading requires knowing which divs are headings and what level they are. Reading order, focus order and keyboard behavior of custom widgets are design decisions.
• Timing. Changes made after load can arrive late, be undone by a framework re rendering the component, or miss content that appears later in a single page app.
• Conflicts with the user's own tools. Disabled people usually already have assistive technology set up the way they like: a screen reader, magnification, high contrast mode, custom fonts or browser zoom. An extra layer that changes the page or the keyboard behavior can interfere with those settings rather than help.

There is also a simple practical point. WCAG describes the content you deliver. If the HTML your server sends has unlabeled fields, every channel that consumes it (search engines, reader modes, other browsers, scripts that fail to load) still gets unlabeled fields. Many accessibility practitioners and disabled users have raised these concerns, which is why the guidance from standards bodies centers on fixing the content itself.

What about preference toolbars?

Controls for text size, spacing or contrast are not harmful in themselves, and some audiences like them. But they repeat features that browsers and operating systems already provide, and that people already know how to use. More importantly, they do not address the barriers in the code. A form with no labels is still a form with no labels at 150 percent zoom. If you offer such controls, treat them as an extra, never as the way you meet WCAG.

Why fixing the source wins

A fix in the source is made once, by someone who knows what the content means, and then it works for everyone, everywhere, with no extra script for visitors to download. It also teaches the team: a developer who adds a label to a field today writes the next form correctly. Most fixes are small:

<!-- Before -->
<button><svg>...</svg></button>
<input type="email" placeholder="Email">
<img src="divider.png">

<!-- After -->
<button aria-label="Close"><svg aria-hidden="true">...</svg></button>
<label for="email">Email</label>
<input type="email" id="email" autocomplete="email">
<img src="divider.png" alt="">

Fixing at the component and design token level multiplies the effect. One corrected button component, or one darker gray in your color tokens (see the color contrast guide), can clear hundreds of findings across a site.

A workflow: diagnose in the page, fix in the code

The a11ymedic overlay is meant for development, staging and design reviews. Load it on a local or preview build, look at the pins, open the panel with the keyboard, and copy the fix into your component. Alt+Shift+A shows or hides it. Because it runs in a real browser, it uses computed styles and real element sizes, which makes it the most accurate way to check contrast and target size.

<script src="https://cdn.jsdelivr.net/npm/a11ymedic@0.1.0/dist/a11ymedic.js" data-overlay></script>

if (location.hostname === "localhost") {
  const s = document.createElement("script");
  s.src = "https://cdn.jsdelivr.net/npm/a11ymedic@0.1.0/dist/a11ymedic.js";
  s.dataset.overlay = "";
  document.head.append(s);
}

For changes that need no human decision, let the CLI edit the files for you. It applies only safe fixes (empty alt on images that are clearly decorative, a page language it can detect, removed zoom blocking, labels for tab panels) and leaves anything that needs judgment, such as writing a real description, for a person.

# Preview the changes as a diff
npx a11ymedic fix "src/**/*.html"

# Write them to disk, then review with git diff
npx a11ymedic fix "src/**/*.html" --write

Finally, keep the fixes from regressing with a check in your pipeline, as shown in the CI guide.

When you cannot change the code

Sometimes the problem is in a third party embed, a legacy CMS template or a vendor widget. Runtime patching is tempting there, but it is still fragile. Better options, roughly in order: fix the template that generates the markup; ask the vendor for an accessible version and share the a11ymedic report as evidence (the HTML and Markdown reports are easy to attach); replace the component; and as a last resort, patch the markup at build time, where the change is versioned and testable, instead of in every visitor's browser. Use --exclude with a CSS selector to keep known third party areas out of your CI gate while you work on it, so the rest of the site stays protected.

To start, run the online check-up on a snippet or read the website accessibility checker guide.