Example results of the a11y audit can be found at https://exiguus.github.io/a11y-audit/

This repository contains a collection of tools and resources for conducting accessibility audits on web applications. The goal is to provide a comprehensive set of tools that can be used to identify and fix accessibility issues in web applications.

• SitemapScraper This is a tool that generates a sitemap for a web application. It can be used to identify all the pages in a web application. It use the sitemap.xml file of the Website to generate a URL list. The URL list is generated by crawling the sitemap recursive.
• Reporting htmlcs and axe runners by Keyle - These are the main tools used for conducting accessibility audits. They can be used to identify and fix accessibility issues in web applications. They report WCAG 2.1 issues and provide detailed information about each issue, including the location of the issue in the code and suggestions for fixing it.
• Results - Provides a summary of the accessibility issues found in the web application. It includes a list of all the issues found, along with their severity and location in the code. The results can be used to prioritize the issues that need to be fixed.

To get started with the tools, follow these steps:

1. Clone the repository to your local machine.
2. Pre-requisites:
   • Node.js > 22
   • Bun > 1.1.0
   • pnpm > 10
   • A web application to audit
3. Install the required dependencies using pnpm exec playwright install and pnpm install.
4. Copy the .env.example file to .env
5. Run the tools using the following command:

pnpm run a11y:audit

4. The results will be generated in the results directory. You can view the results in your web browser by opening the index.html file.
5. Use the results to identify and fix accessibility issues in your web application. The results include detailed information about each issue, including the location of the issue in the code and suggestions for fixing it.
6. Once you have fixed the issues, run the tools again to verify that the issues have been resolved.
7. Repeat the process until all accessibility issues have been resolved.

Options are stored in the .env file. The options are used to configure the tools and specify the web application to audit. The options include:

ORIGIN="www.gattner.name"
BACKUP_PATH="./backups"
REPORT_PATH="./reports"
RESULTS_PATH="./results"
RESULTS_IGNORE_WARNING="true"
SITEMAP_PATH="./sitemaps"
SITEMAP_URLS='[]'
URL_LIST='["https://www.gattner.name/", "https://www.gattner.name/about", "https://www.gattner.name/contact", "https://www.gattner.name/impressum"]'
TIMEOUT=30000
LANGUAGE="en"

• ORIGIN: The origin of the web application to audit. This is used to generate subdirectories and file names for the results.
• SITEMAP_URLS or URL_LIST: The list of URLs to audit. If SITEMAP_URLS is set, the tool will use the sitemap to generate the URL list. If URL_LIST is set, the tool will use the URL list directly. If both are set, the tool will use both.

Options to configure the browser and the audit can be found in the report.config.ts file. The options include:

export const defaultConfig: Partial<CrawlConfig> = {
	browserConfig: {
		headless: true,
		timeout: process.env.TIMEOUT ? Number.parseInt(process.env.TIMEOUT) : 30000,
	},
	kayleConfig: {
		includeWarnings: true,
		waitUntil: "networkidle",
		runners: ["htmlcs", "axe"],
		standard: Standard.WCAG2AA,
		timeout: process.env.TIMEOUT ? Number.parseInt(process.env.TIMEOUT) : 30000,
		language: process.env.LANGUAGE || "en",
	},
};

pnpm run a11y:audit

pnpm run a11y:audit:scrape

The scraper is used to generate a sitemap for a web application. It can be used to identify all the pages in a web application. The scraper uses the sitemap.xml file of the website to generate a URL list. The URL list is generated by crawling the sitemap recursively.

pnpm run a11y:audit:report

The reporting tools are used to conduct accessibility audits. They can be used to identify and fix accessibility issues in web applications. The reporting tools use the htmlcs and axe runners by Keyle to report WCAG 2.1 issues. The reports provide detailed information about each issue, including the location of the issue in the code and suggestions for fixing it.

pnpm run a11y:audit:result

The results provide a summary of the accessibility issues found in the web application. The results include a list of all the issues found, along with their severity and location in the code. The results can be used to prioritize the issues that need to be fixed.

pnpm run a11y:audit:backup

The backup command is used to create a backup of the results and sitemaps. Backups are compressed and stored with timestamps.

pnpm run a11y:audit:clean

The clean command is used to remove all the results and sitemaps. This command is useful for cleaning up the results and sitemaps after the audit is complete.

Recursive crawl a website and generate a sitemap.txt file.

./tools/crawl.sh https://www.example.org

The crawl.sh script use wget to recursively crawl a website and generate a sitemap.txt file. The file can be used to manualy export the URL_LIST with export URL_LIST=$(jq -R < sitemap.txt | jq -s .). It can be used if a sitemap.xml file is not available.

Currently, some rules for WCAG 2.1 AA and WCAG 2.2 AA are missing. This section lists these rules and how to test them.

Note: This list is generated with AI and may not be complete or accurate. It is recommended to consult the official WCAG guidelines for a comprehensive list of rules.

• Description: Content should not restrict its view and operation to a single display orientation unless essential.
• How to Test: Ensure content can be viewed and operated in both portrait and landscape modes on mobile devices.

• Description: The purpose of each input field collecting user information should be programmatically determinable.
• How to Test: Use browser developer tools to inspect form fields and ensure each input field has a clear and programmatically determinable purpose.

• Description: Status messages should be programmatically determinable and presented to users by assistive technologies without receiving focus.
• How to Test: Use screen readers to verify that status messages are announced automatically without requiring user focus.

• Description: Enhances the visibility of the focus indicator to ensure it is easily noticeable.
• How to Test: Navigate through the content using the keyboard and ensure the focus indicator is clearly visible and distinguishable.

• Description: Functionality that uses dragging movements should also be operable through other input methods unless dragging is essential.
• How to Test: Ensure alternative input methods (e.g., keyboard, voice commands) are available for functionality requiring dragging.

• Description: The size of the target for pointer inputs should be at least 24 by 24 CSS pixels, except when the target is in a sentence or block of text, or the size is essential.
• How to Test: Measure the clickable/tappable areas of interactive elements to ensure they meet the minimum size requirement.

• Description: Context-sensitive help should be available in a consistent manner.
• How to Test: Verify that help documentation or tooltips are consistently available and accessible across the application.

• Description: Provide alternative authentication methods that do not rely solely on cognitive function tests.
• How to Test: Check for alternative authentication methods (e.g., email links, backup codes) that do not require users to remember complex information or solve puzzles.

• Description: Information previously entered by the user should be retained or made easily available unless security or legal concerns require re-entry.
• How to Test: Fill out forms and navigate away or refresh the page to ensure previously entered information is retained or can be easily retrieved.

• WCAG 2.1 Guidelines
• WCAG 2.2 Guidelines
• W3C Web Accessibility Initiative (WAI)
• EN 301 549 Harmonisierte Europäsche Norm
• AXE
• kayle
• WAVE

This repository is provided as-is without any warranties or guarantees. The tools and resources are intended to assist in conducting accessibility audits but may not cover all aspects of accessibility. It is recommended to consult with accessibility experts and follow best practices for web accessibility.

Contributions are welcome! If you have suggestions for improvements or additional tools, please open an issue or submit a pull request. Ensure that your contributions adhere to the project's coding standards and guidelines.

This project is licensed under the MIT License. See the LICENSE file for details.

This project was inspired by the need for comprehensive accessibility auditing tools and the importance of web accessibility for all users. Thanks to Keyle for the kayle library and the contributors to the htmlcs and axe runners for doing the main work. Special thanks to the W3C for their work on web accessibility standards.

The EU has also made significant contributions to web accessibility through the EN 301 549 standard, which provides guidelines for making web content accessible to people with disabilities. This project aims to support these efforts and promote a more inclusive web for everyone.

For questions, feedback, or support, please contact the project maintainer or open an issue in the repository.