@sa11y/preset-rules

@sa11y/preset-rules

Accessibility preset rule configs for axe

• Usage
• Ruleset Mapping
  • WCAG 2.0 Level A & AA Rules
  • WCAG 2.1 Level A & AA Rules
  • Best Practices Rules
  • Experimental Rules

Usage

import axe from 'axe-core';
import { recommended } from '@sa11y/preset-rules';

const a11yResults = await axe.run(recommended);
console.log(a11yResults);

Ruleset Mapping

@sa11y/preset-rules provides three pre-configured rulesets curated from axe: Base, Recommended and Full.

• Below is the full set of rules from axe rule descriptions and their current mapping to the Base and Recommended rulesets in @sa11y/preset-rules.
• Full ruleset consists of all rules that are enabled by default in axe.

WCAG 2.0 Level A & AA Rules

Rule ID	Description	Impact	Issue Type	In Base Ruleset	In Recommended Ruleset	Notes
area-alt	Ensures <area> elements of image maps have alternate text	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
aria-allowed-attr	Ensures ARIA attributes are allowed for an element's role	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
aria-hidden-body	Ensures aria-hidden='true' is not present on the document body.	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
aria-hidden-focus	Ensures aria-hidden elements do not contain focusable elements	Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
aria-input-field-name	Ensures every ARIA input field has an accessible name	Moderate, Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
aria-required-attr	Ensures elements with ARIA roles have all required ARIA attributes	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
aria-required-children	Ensures elements with an ARIA role that require child roles contain them	Critical	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
aria-required-parent	Ensures elements with an ARIA role that require parent roles are contained by them	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
aria-roledescription	Ensure aria-roledescription is only used on elements with an implicit or explicit role	Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
aria-roles	Ensures all elements with a role attribute use a valid value	Serious, Critical	failure	:heavy_check_mark:	:heavy_check_mark:
aria-toggle-field-name	Ensures every ARIA toggle field has an accessible name	Moderate, Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
aria-valid-attr-value	Ensures all ARIA attributes have valid values	Critical	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
aria-valid-attr	Ensures attributes that begin with aria- are valid ARIA attributes	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
audio-caption	Ensures <audio> elements have captions	Critical	needs review	:heavy_check_mark:	:heavy_check_mark:
blink	Ensures <blink> elements are not used	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
button-name	Ensures buttons have discernible text	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
bypass	Ensures each page has at least one mechanism for a user to bypass navigation and jump straight to the content	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
color-contrast	Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds	Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
dlitem	Ensures <dt> and <dd> elements are contained by a <dl>	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
document-title	Ensures each HTML document contains a non-empty <title> element	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
duplicate-id-active	Ensures every id attribute value of active elements is unique	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
duplicate-id-aria	Ensures every id attribute value used in ARIA and in labels is unique	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
duplicate-id	Ensures every id attribute value is unique	Minor	failure	:heavy_check_mark:	:heavy_check_mark:
form-field-multiple-labels	Ensures form field does not have multiple label elements	Moderate	needs review	:heavy_check_mark:	:heavy_check_mark:
frame-title	Ensures <iframe> and <frame> elements contain a non-empty title attribute	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
html-has-lang	Ensures every HTML document has a lang attribute	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
html-lang-valid	Ensures the lang attribute of the <html> element has a valid value	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
html-xml-lang-mismatch	Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page	Moderate	failure	:heavy_check_mark:	:heavy_check_mark:
image-alt	Ensures <img> elements have alternate text or a role of none or presentation	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
input-button-name	Ensures input buttons have discernible text	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
input-image-alt	Ensures <input type="image"> elements have alternate text	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
label	Ensures every form element has a label	Minor, Critical	failure	:heavy_check_mark:	:heavy_check_mark:
link-name	Ensures links have discernible text	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
list	Ensures that lists are structured correctly	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
listitem	Ensures <li> elements are used semantically	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
marquee	Ensures <marquee> elements are not used	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
meta-refresh	Ensures <meta http-equiv="refresh"> is not used	Critical	failure	:heavy_check_mark:	:heavy_check_mark:
object-alt	Ensures <object> elements have alternate text	Serious	failure	:x:	:heavy_check_mark:	<obj> rarely used
role-img-alt	Ensures [role='img'] elements have alternate text	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
scrollable-region-focusable	Elements that have scrollable content should be accessible by keyboard	Moderate	failure	:heavy_check_mark:	:heavy_check_mark:
server-side-image-map	Ensures that server-side image maps are not used	Minor	needs review	:heavy_check_mark:	:heavy_check_mark:
svg-img-alt	Ensures svg elements with an img, graphics-document or graphics-symbol role have an accessible text	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
td-headers-attr	Ensure that each cell in a table using the headers refers to another cell in that table	Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
th-has-data-cells	Ensure that each table header in a data table refers to data cells	Serious	failure, needs review	:heavy_check_mark:	:heavy_check_mark:
valid-lang	Ensures lang attributes have valid values	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
video-caption	Ensures <video> elements have captions	Critical	needs review	:heavy_check_mark:	:heavy_check_mark:

WCAG 2.1 Level A & AA Rules

Rule ID	Description	Impact	Issue Type	In Base Ruleset	In Recommended Ruleset	Notes
autocomplete-valid	Ensure the autocomplete attribute is correct and suitable for the form field	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
avoid-inline-spacing	Ensure that text spacing set through style attributes can be adjusted with custom stylesheets	Serious	failure	:x:	:heavy_check_mark:	TBD on how widespread this issue is

Best Practices Rules

Rules that do not necessarily conform to WCAG success criterion but are industry accepted practices that improve the user experience.

Rule ID	Description	Impact	Issue Type	In Base Ruleset	In Recommended Ruleset	Notes
accesskeys	Ensures every accesskey attribute value is unique	Serious	failure	:x:	:heavy_check_mark:	Rarely applicable
aria-allowed-role	Ensures role attribute has an appropriate value for the element	Minor	failure, needs review	:x:	:heavy_check_mark:
empty-heading	Ensures headings have discernible text	Minor	failure	:heavy_check_mark:	:heavy_check_mark:
frame-tested	Ensures <iframe> and <frame> elements contain the axe-core script	Critical	failure, needs review	:x:	:heavy_check_mark:
frame-title-unique	Ensures <iframe> and <frame> elements contain a unique title attribute	Serious	failure	:x:	:x:	May not be able to control for this on highly customizable pages with many embedded components
heading-order	Ensures the order of headings is semantically correct	Moderate	failure	:heavy_check_mark:	:heavy_check_mark:
identical-links-same-purpose	Ensure that links with the same accessible name serve a similar purpose	Minor	needs review	:x:	:heavy_check_mark:	May not be able to control for this on highly customizable pages with many embedded components
image-redundant-alt	Ensure image alternative is not repeated as text	Minor	failure	:heavy_check_mark:	:heavy_check_mark:	Common bug worth catching!
label-title-only	Ensures that every form element is not solely labeled using the title or aria-describedby attributes	Serious	failure	:heavy_check_mark:	:heavy_check_mark:
landmark-banner-is-top-level	Ensures the banner landmark is at top level	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-complementary-is-top-level	Ensures the complementary landmark or aside is at top level	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-contentinfo-is-top-level	Ensures the contentinfo landmark is at top level	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-main-is-top-level	Ensures the main landmark is at top level	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-no-duplicate-banner	Ensures the document has at most one banner landmark	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-no-duplicate-contentinfo	Ensures the document has at most one contentinfo landmark	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-no-duplicate-main	Ensures the document has at most one main landmark	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-one-main	Ensures the document has a main landmark	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
landmark-unique	Landmarks must have a unique role or role/label/title (i.e. accessible name) combination	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
meta-viewport-large	Ensures <meta name="viewport"> can scale a significant amount	Minor	failure	:x:	:heavy_check_mark:
meta-viewport	Ensures <meta name="viewport"> does not disable text scaling and zooming	Critical	failure	:x:	:heavy_check_mark:
page-has-heading-one	Ensure that the page, or at least one of its frames contains a level-one heading	Moderate	failure	:heavy_check_mark:	:heavy_check_mark:	This should always be true
region	Ensures all page content is contained by landmarks	Moderate	failure	:x:	:heavy_check_mark:	Still have landmark work to do before enabling in "Base" set
scope-attr-valid	Ensures the scope attribute is used correctly on tables	Moderate, Critical	failure	:heavy_check_mark:	:heavy_check_mark:	This should always be true
skip-link	Ensure all skip links have a focusable target	Moderate	failure, needs review	:x:	:x:	Strict test for in-page links, doesn't pass for JS skip links
tabindex	Ensures tabindex attribute values are not greater than 0	Serious	failure	:heavy_check_mark:	:heavy_check_mark:	This should always be true
table-duplicate-name	Ensure that tables do not have the same summary and caption	Minor	failure	:x:	:x:	Table captions rarely used in our apps

Experimental Rules

Rules we are still testing and developing. They are not enabled by default in axe-core, but are enabled for the axe browser extensions.

Rule ID	Description	Impact	Issue Type	In Base Ruleset	In Recommended Ruleset	Notes
css-orientation-lock	Ensures content is not locked to any specific display orientation, and the content is operable in all display orientations	Serious	failure, needs review	:x:	:heavy_check_mark:
focus-order-semantics	Ensures elements in the focus order have an appropriate role	Minor	failure	:heavy_check_mark:	:heavy_check_mark:
hidden-content	Informs users about hidden content.	Minor	failure, needs review	:x:	:x:	Can have false positives
label-content-name-mismatch	Ensures that elements labelled through their content must have their visible text as part of their accessible name	Serious	failure	:x:	:heavy_check_mark:
link-in-text-block	Links can be distinguished without relying on color	Serious	failure, needs review	:x:	:heavy_check_mark:
no-autoplay-audio	Ensures <video> or <audio> elements do not autoplay audio for more than 3 seconds without a control mechanism to stop or mute the audio	Moderate	failure, needs review	:x:	:heavy_check_mark:
p-as-heading	Ensure p elements are not used to style headings	Serious	failure	:x:	:heavy_check_mark:
table-fake-caption	Ensure that tables with a caption use the <caption> element.	Serious	failure	:x:	:x:	Table captions rarely used in our apps
td-has-header	Ensure that each non-empty data cell in a large table has one or more table headers	Critical	failure	:heavy_check_mark:	:heavy_check_mark: