Bring any page in for a check-up. a11ymedic examines it with 61 WCAG 2.2 rules, tells you in plain language what is wrong and who it hurts, and hands you the patched HTML. It works as a page overlay, on the command line, in CI and inside your tests.
Who it is for
A finding is not a lint warning. Each one says which people hit the barrier, so you know why the fix matters before you write it.
Live demo
Pick a patient or paste your own HTML and run the medic. Numbered pins land on the page, the chart explains each problem with the exact fix, and Treat applies it to the live page so you can watch the patient recover.
Contrast eye exam
Pick a text color and a background and read the chart. a11ymedic keeps the hue and moves only the OKLCH lightness until the pair passes, so your brand still looks like your brand. The same math writes the color-contrast fix in every report.
Large text, 24px
Normal body text at 16px. The quick brown otter jumps over the lazy bug.
4.5:1 contrast
Type a CSS color: #0f8b8d, rgb(), hsl(), oklch() or a name.
Prescription lenses
on , :1
on , :1
on , :1
Perfect vision: this pair already passes the target.
Read the guide: How to fix color contrast without losing your brand.
How it works
An engine written from scratch runs 61 rules on a real DOM. In the browser it reads computed styles and real boxes. On Node it parses HTML with jsdom, cascades your CSS itself (specificity, variables, inheritance) and keeps line numbers.
Every finding says what is wrong with this exact element, why it matters, who is affected and which WCAG 2.2 criterion it breaks, in English and Portuguese, with the selector and the HTML snippet.
Each finding comes with patched code: the missing alt, aria-label or label for, a contrast safe color picked in OKLCH. Safe fixes apply in one command with a diff preview, and running them twice changes nothing.
Quick start
Same rules, same explanations and the same fixes wherever you run it.
House call
Add one script tag in development. Numbered pins mark each problem and a keyboard accessible side panel explains it. Alt + Shift + A toggles it.
<script src="https://cdn.jsdelivr.net/npm/a11ymedic@0.1.0/dist/a11ymedic.js" data-overlay></script>
<!-- Portuguese: data-overlay="pt" -->Or drag this bookmarklet to your bookmarks bar and press it on any site: a11ymedic check-up
Walk-in clinic
Check built HTML, a folder or a live URL. With Playwright or Puppeteer installed, URLs are checked in a headless browser; without them the HTML is fetched and checked statically.
npx a11ymedic "dist/**/*.html"
npx a11ymedic https://example.com --format html -o report.html
npx a11ymedic fix "src/**/*.html" # preview safe fixes as a diff
npx a11ymedic fix "src/**/*.html" --write # apply themDaily rounds
On GitHub Actions a11ymedic prints annotations on the changed lines and writes a job summary on its own.
name: Accessibility
on: [push, pull_request]
jobs:
a11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci && npm run build
- run: npx a11ymedic "dist/**/*.html" --fail-on seriousLab tests
Audit rendered components and get a readable failure with the fix for each problem.
import { audit } from "a11ymedic";
import "a11ymedic/vitest"; // Jest: setupFilesAfterEnv: ["a11ymedic/jest"]
test("the toolbar is accessible", async () => {
document.body.innerHTML = renderToolbar();
expect(await audit(document.body)).toHaveNoViolations();
});npm install --save-dev a11ymedicimport { render } from "@testing-library/react";
import { audit } from "a11ymedic";
import "a11ymedic/vitest";
test("Toolbar", async () => {
const { container } = render(<Toolbar />);
expect(await audit(container)).toHaveNoViolations({ severity: "serious" });
});import { mount } from "@vue/test-utils";
import { audit } from "a11ymedic";
import "a11ymedic/vitest";
it("Card", async () => {
const wrapper = mount(Card, { props: { title: "Plans" }, attachTo: document.body });
expect(await audit(wrapper.element)).toHaveNoViolations();
});import { audit } from "a11ymedic";
it("is accessible", async () => {
const fixture = TestBed.createComponent(CardComponent);
fixture.detectChanges();
const result = await audit(fixture.nativeElement);
expect(result.findings).toEqual([]);
});import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
{process.env.NODE_ENV === "development" && (
<Script src="https://cdn.jsdelivr.net/npm/a11ymedic@0.1.0/dist/a11ymedic.js" data-overlay />
)}
</body>
</html>
);
}Rule catalog
The medicine cabinet, sorted into twelve drawers. Every rule has a passing and a failing test fixture. The ones with a bandage are applied by a11ymedic fix --write; the others come with a suggested patch to review.
61 of 61 rules
image-altcritical
Image without alt text
image-alt-qualitymoderate
Alt text that does not help
input-image-altcritical
Image button without text
area-altcritical
Image map area without text
role-img-altserious
Graphic without a name
object-altserious
Embedded object without a text alternative
button-namecritical
Button without a name
link-nameserious
Link without a name
link-text-genericmoderate
Link text like "click here"
label-in-nameserious
Visible label missing from the accessible name
aria-dialog-nameserious
Dialog without a name
aria-widget-nameserious
Custom control without a name
frame-titleserious
Frame without a title
frame-title-uniqueminor
Frames with the same title
labelcritical
Form field without a label
autocomplete-validserious
Invalid autocomplete value
input-purposeminor
Personal data field without autocomplete
paste-blockedserious
Pasting into a field is blocked
radio-groupmoderate
Radio buttons without a group label
color-contrastserious
Text with low color contrast
color-contrast-enhancedminor
Text contrast below the enhanced level (AAA)
tabindexserious
Positive tabindex changes the focus order
focus-visibleserious
Focus indicator removed
nested-interactiveserious
Interactive element inside another one
keyboard-click-handlerserious
Clickable element that keyboards cannot use
link-as-buttonmoderate
Link used as a button
bypassserious
No way to skip repeated content
skip-linkmoderate
In-page link points nowhere
meta-viewportcritical
Zoom is disabled
target-sizeserious
Click or tap target smaller than 24 by 24 pixels
document-titleserious
Page has no title
heading-ordermoderate
Heading level skipped
page-has-heading-onemoderate
Page has no main heading (h1)
empty-headingmoderate
Empty heading
landmark-one-mainmoderate
Page needs exactly one main landmark
landmark-uniquemoderate
Landmarks that cannot be told apart
regionmoderate
Content outside of landmarks
listserious
List with invalid children
listitemserious
List item outside of a list
definition-listserious
Definition list with invalid structure
duplicate-idminor
Duplicate id
html-has-langserious
Page language is not set
html-lang-validserious
Page language code is invalid
valid-langmoderate
Invalid language on part of the page
video-captioncritical
Video without captions
autoplay-mediaserious
Media that plays sound on its own
blink-marqueeserious
Blinking or scrolling text
motion-reducedmoderate
Large animation ignores reduced motion
meta-refreshcritical
Page refreshes or redirects on a timer
table-headersserious
Data table without header cells
th-scope-validmoderate
Invalid scope on a header cell
empty-table-headerminor
Empty table header cell
aria-valid-roleserious
Invalid ARIA role
aria-valid-attrserious
Misspelled or unknown ARIA attribute
aria-valid-attr-valueserious
Invalid ARIA attribute value
aria-required-attrcritical
ARIA role missing a required state
aria-hidden-focusserious
Hidden content that can still receive focus
aria-hidden-bodycritical
Whole page hidden from screen readers
aria-prohibited-labelmoderate
aria-label on an element that cannot be named
aria-required-parentcritical
ARIA role outside of its required container
presentation-role-conflictminor
role="presentation" that browsers ignore
API
import { audit, fixHtml, suggestColors, formatText } from "a11ymedic";
const result = await audit('<img src="team.jpg">', { level: "AA", lang: "en" });
const [finding] = result.findings;
finding.rule; // "image-alt"
finding.severity; // "critical"
finding.message.pt; // plain language, English and Portuguese
finding.wcag[0].url; // https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html
finding.fix.after; // '<img src="team.jpg" alt="Team">'
console.log(formatText(result));
const { output, applied } = await fixHtml(html); // safe fixes only
suggestColors("#999999", "#ffffff").foreground; // "#767676"| Function | What it does |
|---|---|
audit(html | document | element, options?) | Runs the rules. Returns findings (most severe first), human checks and counts. |
auditDocument(root, options?) | The same, synchronous, for a live DOM. |
fixHtml(html, options?) | Applies safe fixes to source text and keeps formatting. Idempotent. |
applyFix(finding) | Applies one fix to the live DOM. |
contrastRatio(fg, bg), suggestColors(fg, bg, { ratio }) | WCAG contrast and the closest passing pair in OKLCH. |
accessibleName(el), getRole(el) | Accessible name and role, as assistive technology sees them. |
formatText, toJSON, toMarkdown, toHtml, githubAnnotations, githubSummary | Reports. |
overlay(options?), drawPins(doc, findings) | Browser build only: the pins and panel. |
Full reference with every option: README on GitHub.
The reading room
Short guides with the code to copy. Pick a pamphlet from the rack.
FAQ
Use one that finds problems and tells you how to fix them. a11ymedic is free and open source: it checks 61 WCAG 2.2 rules in the browser, on the command line and in CI, explains each problem in plain English or Portuguese and gives the patched HTML for every finding.
Run npx a11ymedic https://your-site.com for a full report, or add the a11ymedic script tag (or the bookmarklet) to see numbered pins on the page itself. For your own code, run npx a11ymedic "src/**/*.html" and add --fail-on serious in CI.
It fixes the safe ones: a11ymedic fix "src/**/*.html" shows a diff and --write applies it. Safe fixes are things like an empty alt on a spacer image, tabindex 0 instead of 5, re-enabling zoom or a misspelled ARIA attribute. Everything that needs a human decision (alt text that describes a photo, a label text) comes as a ready to paste suggestion instead.
No. Automated checks catch a large share of common problems, but not all of them: whether alt text is accurate, whether a flow makes sense with a screen reader or whether captions are correct still need people. a11ymedic marks what it cannot decide as a human check.
Yes. Test rendered components with expect(await audit(container)).toHaveNoViolations() in Vitest or Jest, check built HTML with the CLI, or load the overlay script in development.
No. Its overlay is a diagnosis tool for the people who build the site: it highlights problems and shows the fix. It never changes the page for visitors. Real fixes belong in your source code.