spencerx / a11y-ai

Experimental tool to automatically detect accessibility issues in web pages and provide suggestions for fixing them

🤖 a11y-ai

Experimental tool to automatically detect accessibility issues in web pages using OpenAI and provide suggestions for fixing them.

Can I help fixing your a11y issues?

Installation

To use this tool you need Node.js 16.4+. We recommended to install Node.js using NVM (Mac OS, Linux or WSL) or nvm-windows (Windows) to avoid issues.

npm install -g a11y-ai

Usage

Usage: a11y <command> <files> [options]

If no files are specified, it will scan the current directory and
subdirectories for HTML files.

Commands:
  s, scan                     Scan files or URLs for accessibility issues
    -o, --format <format>     Report format [text, json] (default: text)
    
  f, fix                      Fix accessibility issues interactively
    -i, --issues <issues>     Comma-separated list of issues to fix (disable scan)
    -s, --chunk-size <tokens> Set input chunk size (default: 1000)
    -c, --char-diff           Use character diff instead of patch-like diff
    -y, --yes                 Apply fixes without prompting
    --context <context>       Provide additional context
    --gpt-diff                Make AI generate diff of fixes (experimental)

  r, report                   Generate a report of issues with fix suggestions
    -i, --issues <issues>     Comma-separated list of issues to fix (disable scan)
    -s, --chunk-size <tokens> Set input chunk size (default: 1000)
    -o, --format <format>     Report format [html, md] (default: html)
    --context <context>       Provide additional context
    --gpt-diff                Make AI generate diff of fixes (experimental)

General options:
  --api                   Use specified API URL
  --verbose               Show detailed logs
  --help                  Show this help

You can also set the API URL using the A11Y_AI_API environment variable.

Examples

• Interactively scan & fix a local file:

  a11y fix site.html

• Generate a report of issues with fix suggestions for multiple URLs:

  a11y report https://microsoft.com https://docs.microsoft.com

• Interactively fix specific issues with additional context in a React component:

  a11y fix component.jsx \
    --issues "Add missing images alt attributes" \
    --context "This is a documentation where screenshots shows the different step to setup GitHub Copilot on your account" 

• Automagicically scan for all HTML files in the current directory and subdirectories, interactively fix the issues:

  a11y

Notes

The interactive fix command works best when used on small local files, HTML or components. For larger files or URLs, it is recommended to use the report command to generate a report of issues with fix suggestions.

As the tool is still experimental and its UI feedback limited at the moment, it is recommended to use the --verbose option to get more detailed logs of what's happening.

Accessibility issues scanning

Accessibility issues scan is done using Playwright with the axe-playwright plugin.

Troubleshooting

If you get an error like this:

Could not scan issues for 'index.html': Error while running axe scan: Command failed: npx playwright test --config "/usr/local/lib/node_modules/a11y-ai/scan/playwright.config.cjs"

It may mean that the Playwright browsers were not installed correctly during the package installation. You can fix that by running this command (you can ignore the warning message it will print)):

npx -y playwright install chromium

Known limitations

• Issue scanning is only supported for HTML files, not for JS/TS components (but fixing is supported)
• --gpt-diff options is experimental and may not work well in some cases, as the patch may fail to be applied at the right places