Change the Accessibility (A11y) Threshold
Customize and prioritize how your organization treats accessibility issues
A11y is a number-based abbreviation (or numeronym) for the word "accessibility", with "11" (eleven) representing the number of characters between the starting "a" and ending "y" in accessibility. Read on to learn more about the a11y threshold and the criteria Axe Developer Hub uses for its calculation.
What Is the A11y Threshold?
The a11y threshold reflects your organization's tolerance for accessibility errors, and it is a number that is computed from two criteria:
- Whether the computation uses all accessibility issues found by Axe Developer Hub during your test runs or only new issues discovered in the latest test run. (New issue detection is only available for web projects. Mobile coming soon!)
- Which levels of impact (Critical, Serious, Moderate, and Minor) will be included in the threshold calculation.
If you change any of the criteria for the a11y threshold, the change only affects calculations going forward. Older a11y threshold values are not recalculated. An icon will appear next to the calculation to indicate that the configuration has changed, and if you hover your cursor over it, you will see a reminder that the threshold has changed:
The a11y threshold allows you to customize Axe Developer Hub for what matters to your organization. Are new issues your organization's main concern, or do you want to track all issues? Which impact levels should be prioritized?
For example, your organization's current focus may be only in mitigating critical issues, or your aim may be to remediate both critical and serious issues. If your organization is just starting out addressing accessibility issues, you might need to limit the impact levels you prioritize to avoid being overwhelmed. Later, as your organization's knowledge of mitigating accessibility issues increases, you can change the a11y threshold to include accessibility issues with lower impact.
How Is the A11y Threshold Used?
The a11y threshold provides a quick gauge of the accessibility quality of your project and appears prominently as you drill down to identify issues in Axe Developer Hub. Any value over zero exceeds the allowed accessibility threshold and indicates issues that need to be addressed. Over time, you can track the accessibility threshold from commit to commit, and release to release, to develop a picture of the accessibility health of your project.
In the example below, you can see the calculated a11y threshold in the left section of each panel. Here, the value of 2 indicates two issues that exceed the current threshold:
Clicking on the a11y threshold value - here, 2 - adds the issues with corresponding impact levels to the filter, so you can drill down to only the issues that went over the a11y threshold. (In this case, clicking on 2 adds all the issues to the filter, because all were set in the a11y configuration.)
Configure the A11y Threshold
Only administrators can change the a11y threshold criteria. Doing so will change it for all users of the enterprise.
On your Axe Account page click on the CONFIGURATION tab at the top of the page. On the Configuration page, select Axe Developer Hub from the list on the left side of the page to view and edit the a11y threshold configuration.
After you've changed your a11y threshold settings, click SAVE.
Issues Included
The Issues Included value indicates whether to include in the threshold calculation all accessibility issues that meet the selected impacts, or only new accessibility issues. New accessibility issues are those detected in your current scan that were not found in the scan it is being compared to - whether that is the previous test run, the previous commit, or the latest scan on the default branch. The value displayed for the a11y threshold will be consistent across all pages when set to include all issues. When set to look at new issues only, the value may vary by page, because each page compares its scan against a different baseline.
Note: New issue detection is available for web projects only. Mobile coming soon.
Impacts Included
The Impacts Included value indicates which impact level or levels to include in the calculation. Issues with Critical impact cannot be deselected, since these issues completely block users with disabilities from accessing or interacting with a feature on a web page or mobile app. Learn more about all impact levels.
Using the A11y Threshold With the GitHub Action
When using the Axe Developer Hub GitHub Action for web projects, the a11y threshold serves as a gatekeeper to block pull requests that contain accessibility issues. The action will add a comment to the pull request indicating the problem:
In the above example, the pull request comment links to a page on the Axe Developer Hub website where you can view a list of issues that failed. You can change the default behavior of the GitHub Action to only warn users of accessibility issues instead of blocking the pull request from being merged.
How It Works
The GitHub Action queries the Axe Developer Hub server (via its REST endpoint) for the latest commit associated with the pull request. The web service returns the number of accessibility issues as determined by the a11y threshold settings. Any number of accessibility errors above zero is considered a failure, which adds a comment to the pull request and can block it from being merged.
See Using the GitHub Action for more information.