a11y-fix
Skill117 starsChanged 35 days agoMITView on GitHub
Find and fix accessibility problems in a web page or codebase (React, Next.js, React Native, Angular, plain HTML/JS), or in just the files or directories the user names. Use when asked to audit, check or fix accessibility (a11y, WCAG, axe, screen reader, alt text, labels, contrast).
1 other project uses a version of this.
Adopted by
Most recently taken up by
- badass-courses/a11y-agenttheir own version, first seen Mar 18, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- badass-courses/a11y-agent★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Do both for a web app when you can: source first, then the URL.
- Very specific: line 34
Use fixHint as the starting point.
- Very specific: line 35
Prefer native HTML (<button>, <label>, <nav>) over adding ARIA.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
a11y-fix
Scan, fix, rescan, report. Uses the a11y-checker MCP tools (scan_page, explain_rule); if they are not available, use the CLI: npx a11y-checker <target> --json. The CLI prints a bare JSON array of findings and exits 1 when there are any (that is not a crash).
1. Pick the target
Scope first. Scan only what the user named: a file, several files, a directory or a URL. Pass them all in one call (target can be a list; the CLI takes several arguments). If they named nothing, ask which files or directories; scan the whole project only when they ask for the whole codebase. Only edit files inside that scope, and report (do not fix) findings that point outside it.
- Source code: scan the directory or file. A directory scan covers JS/TS/JSX/TSX (React, Next.js, React Native), Vue (
.vue), Astro (.astro, needseslint-plugin-astro; if aWarning:says it was skipped, runnpx a11y-checker init), Angular templates (.htmlfragments and inlinetemplate:strings in*.component.ts), and full HTML pages (rendered and checked with axe). Svelte, template engines and DOM code built in plain JS (document.createElement) are not linted statically; scan the running page's URL instead. Findings carryfileandline. Works without a running app and is the only option for React Native. - Running app or page: scan the URL (start the dev server first if needed). Findings carry a CSS
selectorandhtml. Use this too for Next.js, because it checks the rendered result (e.g.next/imagealt, page title, contrast), which source scanning cannot. - Do both for a web app when you can: source first, then the URL.
An .html file path is rendered directly, no server needed. A directory or any other file is linted as source.
Next.js and multi-page apps have many routes. Scan each important route's URL.
2. Scan
Call scan_page with the target. If the result (or the CLI's stderr) carries a Warning: about skipped files or nothing to scan, those files were not checked. Never report a clean result for them: say so, and scan the running app's URL instead (or ask for it). Add tags: ["wcag2aa", "wcag22aa"] for a specific WCAG level. For client-rendered pages, pass waitFor with a selector that appears once the app has rendered.
3. Fix
Work through findings, most severe first (critical, serious, moderate, minor). Source findings are all serious, so order those by file.
Fix the root cause, then rescan: one change often clears several findings (a clickable <div> turned into a <button>, one missing <main>).
- Source findings: open
fileatlineand fix it there. - Web findings: locate the element in source. Search for distinctive text from
html, the id, class ordata-testidinselector. Fix the component that renders it, not just one instance. - Use
fixHintas the starting point; callexplain_rulefor a webruleIdwhen the hint is not enough. - Prefer native HTML (
<button>,<label>,<nav>) over adding ARIA. Addlangto<html>, analtto images (alt=""only if decorative), a name to every control.
Do not guess content. These need the real content and count as not fixable by you: alt text, link text, button names, page <title> and <h1>. If you cannot tell what something is for, ask; if you cannot ask, leave it and list it in the report.
4. Rescan
Scan the same target again. Repeat steps 3 and 4 until only findings that need real content remain, at most three rounds.
5. Report
Give: what was fixed (rule, file), what remains, and why. Always call out these as needing a human:
- Color contrast (
color-contrast): needs a design decision. - Meaningful alt text, captions and transcripts.
- Anything automated tools cannot judge. Automated scanning finds only part of the problems; say so, and recommend a keyboard and screen reader pass.
Known gaps
- Source scanning does not check Next.js
<Image>alt text. The URL scan does. - Source findings have no WCAG tags and are all reported as
serious. - Source scanning does not cover Svelte, template engines or markup built by plain JS; use the URL scan for those.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

