Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sinedied/a11y-ai
Experimental tool to automatically detect accessibility issues in web pages and provide suggestions for fixing them
https://github.com/sinedied/a11y-ai
accessibility ai cli fix openai
Last synced: 3 days ago
JSON representation
Experimental tool to automatically detect accessibility issues in web pages and provide suggestions for fixing them
- Host: GitHub
- URL: https://github.com/sinedied/a11y-ai
- Owner: sinedied
- License: mit
- Created: 2023-02-23T19:45:06.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T07:08:02.000Z (3 months ago)
- Last Synced: 2025-01-15T08:29:24.997Z (10 days ago)
- Topics: accessibility, ai, cli, fix, openai
- Language: TypeScript
- Homepage:
- Size: 376 KB
- Stars: 50
- Watchers: 3
- Forks: 8
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# :robot: a11y-ai
[](https://www.npmjs.com/package/a11y-ai)
[](https://github.com/sinedied/a11y-ai/actions)
[](https://github.com/sindresorhus/xo)
[](LICENSE)
> 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+](https://nodejs.org/). We recommended to install Node.js using [NVM](https://github.com/nvm-sh/nvm) (Mac OS, Linux or WSL) or [nvm-windows](https://github.com/coreybutler/nvm-windows) (Windows) to avoid issues.
```bash
npm install -g a11y-ai
```
## Usage
```
Usage: a11y [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 Report format [text, json] (default: text)
f, fix Fix accessibility issues interactively
-i, --issues Comma-separated list of issues to fix (disable scan)
-s, --chunk-size Set input chunk size (default: 1000)
-c, --char-diff Use character diff instead of patch-like diff
-y, --yes Apply fixes without prompting
--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 Comma-separated list of issues to fix (disable scan)
-s, --chunk-size Set input chunk size (default: 1000)
-o, --format Report format [html, md] (default: html)
--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:
```bash
a11y fix site.html
```
- Generate a report of issues with fix suggestions for multiple URLs:
```bash
a11y report https://microsoft.com https://docs.microsoft.com
```
- Interactively fix specific issues with additional context in a React component:
```bash
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:
```bash
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](https://playwright.dev/) with the [axe-playwright](https://www.npmjs.com/package/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)):
```bash
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