A website accessibility checker that explains every fix

What an accessibility checker can and cannot find

Automated checks are good at anything that can be decided from the code. An <img> with no alt attribute, a <button> that contains only an SVG, a text color of #999999 on white (2.84:1, below the 4.5:1 that WCAG asks for), an <html> element with no lang, a positive tabindex, an aria-expanded with a value of "yes": all of these are facts, and a checker can find every one of them in milliseconds.

Other questions need judgment. A checker can see that an image has alt text, but not whether "Team" is a good description of a photo that shows a fire exit. It can see that a page has headings, but not whether they describe the sections. Studies of real audits usually find that automated tools catch somewhere between a third and a half of the issues on a typical page. That is still a lot of work saved, because the problems they catch are also the most common ones.

a11ymedic is honest about that line. Every result is either a finding (a proven failure with a fix) or an entry in incomplete, which means "needs a human check". Text over a background image and target sizes measured without layout land in the second group, so you know exactly what to review by eye.

Three ways to check a website

You can run the same rules in three places. Pick the one that matches what you are doing right now.

1. In the page you are looking at. Add one script tag. It audits the live page with the real computed styles and element boxes, draws numbered pins on each problem and opens a side panel you can use with the keyboard. Press Alt+Shift+A to show or hide it.
2. From the terminal. Point the CLI at files, globs, folders or a URL. For a URL it uses Playwright or Puppeteer when one of them is installed, and otherwise fetches the HTML and runs a static check.
3. From code. Call audit(html) in Node, inspect the findings, and turn them into a report or a failing test.

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

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

# Local files
npx a11ymedic "src/**/*.html"

# A deployed page, saved as an HTML report
npx a11ymedic https://example.com --format html -o report.html

# Report in Portuguese, including AAA rules
npx a11ymedic index.html --lang pt --level AAA

If you want to try it without installing anything, paste a snippet into the online check-up on the home page.

How to read a finding

Each finding is written for the person who has to fix it, not for an auditor. It has the same fields in every output format:

• Severity: critical, serious, moderate or minor. Critical means some people cannot use the feature at all, for example a button with no name.
• Message: what is wrong with this exact element, in English and Portuguese.
• Explanation and affects: why it matters and who is hurt by it, such as screen reader users, people with low vision, or people with tremors.
• WCAG: the success criteria it fails, with their level and a link to the official Understanding page.
• Location: a unique CSS selector plus the line and column in your source file.
• Fix: a summary, the element before, and the element after. When fix.safe is true the change needs no human decision and the CLI can apply it for you.

import { audit, formatText } from "a11ymedic";

const result = await audit('<img src="team-photo.jpg"><p style="color:#999">Hi</p>');

for (const f of result.findings) {
  console.log(f.rule, f.severity, f.message.en);
  console.log("  WCAG", f.wcag.map((c) => c.id).join(", "), "line", f.line);
  console.log("  before:", f.fix.before);
  console.log("  after: ", f.fix.after);
}

console.log(formatText(result));

For the contrast finding above, the fix says to change the text to #767676 (4.54:1), the closest color with the same hue that passes. The color contrast guide explains how that suggestion is chosen.

Static check or real browser?

When a11ymedic reads an HTML file from disk, there is no layout engine. It cascades the page CSS itself to find colors, display and visibility, which is enough for most rules. What it cannot know is the rendered size of an element or the pixels behind a piece of text. So in a static check, a small icon link without explicit sizes is reported as "needs a human check", and text on a photo is never guessed.

In a real browser, the overlay and the headless mode use getComputedStyle and real element boxes. That is the most accurate option for target size (24 by 24 CSS pixels, or enough spacing) and for contrast on complex pages. A good rule of thumb: use static checks for fast feedback on every commit, and run the browser mode on the key pages of your deployed site.

The 15 minute manual pass

After the automated check is clean, spend a few minutes on what no tool can judge:

• Keyboard only. Unplug the mouse. Tab through the page, open every menu and dialog, submit every form. Focus should always be visible and never get stuck.
• Zoom to 200 and 400 percent. Nothing should be cut off, and at 400 percent the page should not scroll sideways.
• Screen reader smoke test. Open the list of headings and the list of links. They should read like a table of contents and a set of clear destinations.
• Read the alt texts and labels. Are they true and useful in context?

The WCAG cheat sheet has a short manual tip for every criterion, including the ones no tool covers.

A practical plan for your first audit

Large sites often get hundreds of findings on the first run. Do not let the number stop you. Most of them come from a few shared components, so fixing one header or one card template can remove dozens at once.

1. Run the CLI over your templates and sort by severity. Fix every critical finding first.
2. Apply the safe fixes automatically with npx a11ymedic fix "src/**/*.html" --write, then review the diff.
3. Fix contrast at the design token level rather than element by element.
4. Add a check to your pipeline so new problems cannot come back. The CI guide shows how.
5. Do the manual pass on your five most visited pages.

Install instructions for every environment are in the install section, and the full list of checks is in the rules reference.