How to find and fix accessibility issues with Claude Code, and where automated checks stop

Claude Code can find and fix many accessibility issues on a website: it sets up an automated scanner, runs it across your page templates, groups the failures by cause, and fixes them in code, such as missing form labels, unnamed buttons, low-contrast colors, skipped heading levels and focus outlines someone removed. It then re-runs the scan to prove the fixes. What it can't do is tell you the site is accessible. The W3C is blunt about this: "Web accessibility evaluation tools can not determine accessibility, they can only assist in doing so." A person still has to test with a keyboard and a screen reader.

This guide gives the steps, example prompts, the check for each step and what a person reviews. It also covers the US legal dates as of October 2026. Accessibility law is a legal question. Nothing here is legal advice; talk to counsel about your obligations.

The standard and the law, briefly

The W3C's WCAG overview says WCAG 2.2 "has 13 guidelines," organized under four principles: perceivable, operable, understandable and robust. It adds nine success criteria to 2.1, including 2.4.11 Focus Not Obscured (Minimum) and 2.5.8 Target Size (Minimum), which asks that pointer targets be "at least 24 by 24 CSS pixels," with exceptions. Two long-standing criteria apply to almost every page: 1.1.1, text alternatives for non-text content, and 1.4.3, text contrast "of at least 4.5:1," or 3:1 for large text.

For US public bodies, the DOJ's Title II web rule page says the April 2026 interim final rule extended compliance to April 26, 2027 for entities with a population of 50,000 or more, and April 26, 2028 for smaller entities and special districts. The rule cites WCAG 2.1 AA, not 2.2, and it covers content a contractor builds: a county page "must meet WCAG 2.1, Level AA even if a local web design company made the web page." For private businesses, the ADA also applies to businesses open to the public under Title III, but the DOJ's web guidance says it "does not have a regulation setting out detailed standards." WCAG 2.2 adds criteria to 2.1 without changing the existing ones, apart from 4.1.1 Parsing, which it marks obsolete. Confirm the right target with counsel.

Step 1: Pick the templates and the target

Work on a staging or local copy, on a branch in git. Don't scan every URL first. Pick one example of each template: home, a service page, a blog post, a product page, the contact form, search results, any page with a menu or modal. Most failures repeat across pages built from the same template.

Write the target into your project instructions: for example, "WCAG 2.2 Level AA; don't remove visible focus styles; color changes need design approval." That keeps every session working to the same standard.

Step 2: Have Claude set up and run an automated scan

Two free, open-source tools are axe-core and Lighthouse. Deque's axe-core has rules "for WCAG 2.0, 2.1, 2.2 on level A, AA and AAA," and returns some results as "incomplete" where "manual review is needed." Google's Lighthouse gives an accessibility score that its documentation calls "a weighted average of all accessibility audits," where manual audits "don't affect your score." A score is a summary, not a verdict.

Example prompt: Install axe-core as a dev dependency and write a script that loads each URL in templates.txt from the local build in a headless browser, runs axe with WCAG 2.2 A and AA rules, and writes every violation and every "incomplete" result to a11y-report.csv with the page, rule, impact, element selector and WCAG criterion. Don't change any site files yet.

The check: the report lists every template, and a page you know has a problem, such as a form with placeholder-only fields, shows it. If nothing shows, the scan isn't reaching the rendered page.

Step 3: Group failures by cause

Ask Claude to turn the raw report into a fix list grouped by source file and rule.

Image descriptions are their own job, with their own review step; see writing and applying image alt text.

Step 4: Fix in code, one group at a time

Start in plan mode with /plan so Claude shows the files it will touch, then fix one group per session or branch. Smaller diffs are easier to review and easier to undo.

Example prompt: Fix the "form fields without labels" group in a11y-report.csv. Add visible labels tied to each field, keep the current layout, and keep placeholder text only as a hint. Don't change field names or form submission code. Show me the plan first.

Some fixes are decisions, not code. Contrast fixes change brand colors. Focus styles change how the site looks. Larger touch targets change spacing. Claude can propose options, such as the closest passing shade of your brand color, but a person picks.

Be careful with forms. A fix that renames fields or changes markup can break spam filtering or analytics events. Test a real submission on staging after each change; our guide to building and fixing contact forms covers the form side.

Step 5: Re-run the scan and check in a real browser

After each group, re-run the step 2 script and compare.

The check: violations for that rule fall to zero on every template scanned, and no new violations appear elsewhere. Then look at the pages. Claude Code can drive a real Chrome window with its Chrome integration to load each template, read console errors and inspect what actually renders; see Claude Code and Chrome. Looking at the rendered page catches visual side effects a scanner can't, like a label that now overlaps a field.

Step 6: The manual checks automated tools can't replace

The W3C's guidance on selecting evaluation tools says "Some accessibility checks just cannot be automated and require manual intervention." These are the checks a person does on each template:

The W3C goes further: "Knowledgeable human evaluation is required to determine if a site is accessible." For public sector sites or high-risk projects, that means an accessibility specialist, and ideally testing with people who use assistive technology.

Step 7: Keep it from slipping back

Accessibility regresses as new pages and components ship. Add the scan to your pre-deploy routine and run it on every pull request for the templates it covers. A hook can run it automatically when Claude finishes a reply. Keep a short written record of what was tested, when and by whom; that record is more useful than a score if anyone asks. Our pre-deploy checklist shows where the check fits.

Don't treat an overlay widget as a fix. The DOJ's guidance says automated checkers and overlays "can be helpful tools, but ... they need to be used carefully." Fixing the code is the durable route.

What a person must review

• The target standard and the legal question, with counsel where it applies.
• Every color, spacing and focus-style change, for brand and usability.
• Form changes, with a real test submission on staging.
• The manual checks in step 6, on every template.
• The diff for each fix group before it merges, and the deploy itself.

Before running any of this on a live site, read whether Claude Code is safe for production websites and the habits in common Claude Code mistakes on websites. For WordPress specifics, see our guide to making a WordPress site WCAG accessible.

Conclusion

Claude Code is a practical way to clear the automated half of an accessibility backlog: set up a scanner, group failures by template and cause, fix them in code one group at a time, and re-run the scan to prove it. The other half needs people: keyboard and screen reader testing, design decisions on color and spacing, and a legal view on which standard applies. If you'd like a team to do both halves, see our ADA-compliant website design and development service. More guides are in our Claude Code Guide.

Frequently asked questions