@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 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-command-name	Ensures every ARIA button, link and menuitem has an accessible name	Serious	failure, needs review	: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-meter-name	Ensures every ARIA meter node has an accessible name	Serious	failure, needs review	:x:	:heavy_check_mark:
aria-progressbar-name	Ensures every ARIA progressbar node has an accessible name	Serious	failure, needs review	:x:	: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-tooltip-name	Ensures every ARIA tooltip node has an accessible name	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:
definition-list	Ensures <dl> elements are structured correctly	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:
select-name	Ensures select element has an accessible name	Minor, Critical	failure, needs review	: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: | | | aria-dialog-name | Ensures every ARIA dialog and alertdialog node has an accessible name | Serious | failure, needs review | :x: | :heavy_check_mark: | | | aria-treeitem-name | Ensures every ARIA treeitem node has an accessible name | Serious | failure, needs review | :heavy_check_mark: | :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 | | presentation-role-conflict | Flags elements whose role is none or presentation and which cause the role conflict resolution to trigger. | Minor | failure | failure | :x: | :heavy_check_mark: | | | 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:

Changelog

0.3.0-beta (2020-08-19)

Features

• browser-lib: add a new package for producing bundled minified version of sa11y (#32)