Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@sa11y/preset-rules

salesforce76.4kBSD-3-Clause7.3.1TypeScript support: included

Accessibility preset rule configs for axe

accessibility, automated testing, axe

readme

@sa11y/preset-rules

Accessibility preset rule configs for axe

Usage

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

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

Ruleset Mapping

@sa11y/preset-rules provides three pre-configured rule set curated from axe: base, extended and full.

  • Below is the set of rules from axe rule descriptions and their current mapping to the base and extended rulesets in @sa11y/preset-rules.
  • base contains WCAG 2.1 AA rules available in axe-core.
  • extended contains WCAG AAA rules, experimental rules and non-WCAG best-practice rules.
  • full ruleset consists of all rules that are enabled by default in axe.
  • The default ruleset used by the sa11y APIs is base.
    • This can be overridden using the SA11Y_RULESET process environment variable (set to base, extended, or full).
  • The SA11Y_RULESET_PRIORITY process environment variable can be used to select rules of specified priority in a ruleset (e.g., P1, P2, P3).

Rules

Rule ID Description WCAG SC WCAG Level Priority In Base ruleset In Extended ruleset
area-alt Ensure <area> elements of image maps have alternative text 4.1.2 A P1 ✅ ✅
aria-allowed-attr Ensure an element's role supports its ARIA attributes 4.1.2 A P1 ✅ ✅
aria-allowed-role Ensure role attribute has an appropriate value for the element 4.1.2 A P1 ✅ ✅
aria-braille-equivalent Ensure aria-braillelabel and aria-brailleroledescription have a non-braille equivalent 4.1.2 A P2 ✅ ✅
aria-conditional-attr Ensure ARIA attributes are used as described in the specification of the element's role 4.1.2 A P2 ✅ ✅
aria-deprecated-role Ensure elements do not use deprecated roles 4.1.2 A P3 ✅ ✅
aria-command-name Ensure every ARIA button, link and menuitem has an accessible name 4.1.2 A P1 ✅ ✅
aria-dialog-name Ensure every ARIA dialog and alertdialog node has an accessible name 4.1.2 A P1 ✅ ✅
aria-hidden-body Ensure aria-hidden="true" is not present on the document body. 4.1.2 A P1 ✅ ✅
aria-hidden-focus Ensure aria-hidden elements are not focusable nor contain focusable elements 4.1.2 A P1 ✅ ✅
aria-input-field-name Ensure every ARIA input field has an accessible name 4.1.2 A P1 ✅ ✅
aria-meter-name Ensure every ARIA meter node has an accessible name 1.1.1 A P1 ✅ ✅
aria-progressbar-name Ensure every ARIA progressbar node has an accessible name 1.1.1 A P1 ✅ ✅
aria-prohibited-attr Ensure ARIA attributes are not prohibited for an element's role 4.1.2 A P2 ✅ ✅
aria-required-attr Ensure elements with ARIA roles have all required ARIA attributes 4.1.2 A P1 ✅ ✅
aria-required-children Ensure elements with an ARIA role that require child roles contain them 1.3.1 A P1 ✅ ✅
aria-required-parent Ensure elements with an ARIA role that require parent roles are contained by them 1.3.1 A P1 ✅ ✅
aria-roles Ensure all elements with a role attribute use a valid value 4.1.2 A P1 ✅ ✅
aria-toggle-field-name Ensure every ARIA toggle field has an accessible name 4.1.2 A P1 ✅ ✅
aria-tooltip-name Ensure every ARIA tooltip node has an accessible name 4.1.2 A P1 ✅ ✅
aria-treeitem-name Ensure every ARIA treeitem node has an accessible name 4.1.2 A P1 ✅ ✅
aria-valid-attr Ensure attributes that begin with aria- are valid ARIA attributes 4.1.2 A P1 ✅ ✅
aria-valid-attr-value Ensure all ARIA attributes have valid values 4.1.2 A P1 ✅ ✅
autocomplete-valid Ensure the autocomplete attribute is correct and suitable for the form field 1.3.5 AA P2 ✅ ✅
avoid-inline-spacing Ensure that text spacing set through style attributes can be adjusted with custom stylesheets 1.4.12 AA P2 ✅ ✅
button-name Ensure buttons have discernible text 4.1.2 A P1 ✅ ✅
bypass Ensure each page has at least one mechanism for a user to bypass navigation and jump straight to the content 2.4.1 A P3 ✅ ✅
color-contrast Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds 1.4.3 AA P1 ✅ ✅
definition-list Ensure <dl> elements are structured correctly 1.3.1 A P2 ✅ ✅
dlitem Ensure <dt> and <dd> elements are contained by a <dl> 1.3.1 A P2 ✅ ✅
document-title Ensure each HTML document contains a non-empty <title> element 2.4.2 A P2 ✅ ✅
duplicate-id-aria Ensure every id attribute value used in ARIA and in labels is unique 4.1.2 A P1 ✅ ✅
form-field-multiple-labels Ensure form field does not have multiple label elements 3.3.2 A P2 ✅ ✅
frame-focusable-content Ensure <frame> and <iframe> elements with focusable content do not have tabindex=-1 2.1.1 A P1 ✅ ✅
frame-title Ensure <iframe> and <frame> elements have an accessible name 4.1.2 A P1 ✅ ✅
frame-title-unique Ensure <iframe> and <frame> elements contain a unique title attribute 4.1.2 A P3 ✅ ✅
html-has-lang Ensure every HTML document has a lang attribute 3.1.1 A P2 ✅ ✅
html-lang-valid Ensure the lang attribute of the <html> element has a valid value 3.1.1 A P2 ✅ ✅
html-xml-lang-mismatch Ensure that HTML elements with both valid lang and xml:lang attributes agree on the base language of the page 3.1.1 A P2 ✅ ✅
image-alt Ensure <img> elements have alternative text or a role of none or presentation 1.1.1 A P1 ✅ ✅
input-button-name Ensure input buttons have discernible text 4.1.2 A P1 ✅ ✅
input-image-alt Ensure <input type="image"> elements have alternative text 4.1.2 A P1 ✅ ✅
label Ensure every form element has a label 4.1.2 A P1 ✅ ✅
link-in-text-block Ensure links are distinguished from surrounding text in a way that does not rely on color 1.4.1 A P2 ✅ ✅
link-name Ensure links have discernible text 4.1.2 A P1 ✅ ✅
list Ensure that lists are structured correctly 1.3.1 A P2 ✅ ✅
listitem Ensure <li> elements are used semantically 1.3.1 A P2 ✅ ✅
marquee Ensure <marquee> elements are not used 2.2.2 A P1 ✅ ✅
meta-refresh Ensure <meta http-equiv="refresh"> is not used for delayed refresh 2.2.1 A P1 ✅ ✅
nested-interactive Ensure interactive controls are not nested as they are not always announced by screen readers or can cause focus problems for assistive technologies 4.1.2 A P1 ✅ ✅
no-autoplay-audio Ensure <video> or <audio> elements do not autoplay audio for more than 3 seconds without a control mechanism to stop or mute the audio 1.4.2 A P1 ✅ ✅
object-alt Ensure <object> elements have alternative text 1.1.1 A P1 ✅ ✅
presentation-role-conflict Elements marked as presentational should not have global ARIA or tabindex to ensure all screen readers ignore them 4.1.2 A P2 ✅ ✅
role-img-alt Ensure [role="img"] elements have alternative text 1.1.1 A P1 ✅ ✅
scrollable-region-focusable Ensure elements that have scrollable content are accessible by keyboard 2.1.1 A P1 ✅ ✅
select-name Ensure select element has an accessible name 4.1.2 A P1 ✅ ✅
server-side-image-map Ensure that server-side image maps are not used 2.1.1 A P1 ✅ ✅
summary-name Ensure summary elements have discernible text 4.1.2 A P1 ✅ ✅
svg-img-alt Ensure <svg> elements with an img, graphics-document or graphics-symbol role have an accessible text 1.1.1 A P1 ✅ ✅
target-size Ensure touch targets have sufficient size and space 2.5.8 AA P2 ✅ ✅
td-headers-attr Ensure that each cell in a table that uses the headers attribute refers only to other cells in that table 1.3.1 A P1 ✅ ✅
th-has-data-cells Ensure that <th> elements and elements with role=columnheader/rowheader have data cells they describe 1.3.1 A P1 ✅ ✅
valid-lang Ensure lang attributes have valid values 3.1.2 A P2 ✅ ✅
video-caption Ensure <video> elements have captions 1.2.2 A P1 ✅ ✅
accesskeys Ensure every accesskey attribute value is unique 2.1.1 A P3 ✖️ ✅
aria-text Ensure role="text" is used on elements with no focusable descendants 4.1.2 A P3 ✖️ ✅
blink Ensure <blink> elements are not used 2.2.2 A P1 ✖️ ✅
color-contrast-enhanced Ensure the contrast between foreground and background colors meets WCAG 2 AAA enhanced contrast ratio thresholds 1.4.6 AAA P3 ✖️ ✅
css-orientation-lock Ensure content is not locked to any specific display orientation, and the content is operable in all display orientations 1.3.4 AA P3 ✖️ ✅
empty-heading Ensure headings have discernible text 1.3.1 A P3 ✖️ ✅
empty-table-header Ensure table headers have discernible text 1.3.1 A P3 ✖️ ✅
focus-order-semantics Ensure elements in the focus order have a role appropriate for interactive content | P3 ✖️ ✅
frame-tested Ensure <iframe> and <frame> elements contain the axe-core script | P3 ✖️ ✅
heading-order Ensure the order of headings is semantically correct 1.3.1 A P3 ✖️ ✅
hidden-content Informs users about hidden content. | P3 ✖️ ✅
identical-links-same-purpose Ensure that links with the same accessible name serve a similar purpose 2.4.9 AAA P3 ✖️ ✅
image-redundant-alt Ensure image alternative is not repeated as text 1.1.1 A P3 ✖️ ✅
label-content-name-mismatch Ensure that elements labelled through their content must have their visible text as part of their accessible name 2.5.3 A P2 ✖️ ✅
label-title-only Ensure that every form element has a visible label and is not solely labeled using hidden labels, or the title or aria-describedby attributes 3.3.2 A P3 ✖️ ✅
landmark-banner-is-top-level Ensure the banner landmark is at top level 4.1.1 A P3 ✖️ ✅
landmark-complementary-is-top-level Ensure the complementary landmark or aside is at top level 4.1.1 A P3 ✖️ ✅
landmark-contentinfo-is-top-level Ensure the contentinfo landmark is at top level 4.1.1 A P3 ✖️ ✅
landmark-main-is-top-level Ensure the main landmark is at top level 4.1.1 A P3 ✖️ ✅
landmark-no-duplicate-banner Ensure the document has at most one banner landmark 4.1.1 A P3 ✖️ ✅
landmark-no-duplicate-contentinfo Ensure the document has at most one contentinfo landmark 4.1.1 A P3 ✖️ ✅
landmark-no-duplicate-main Ensure the document has at most one main landmark 4.1.1 A P3 ✖️ ✅
landmark-one-main Ensure the document has a main landmark 4.1.1 A P3 ✖️ ✅
landmark-unique Ensure landmarks are unique 4.1.1 A P3 ✖️ ✅
meta-refresh-no-exceptions Ensure <meta http-equiv="refresh"> is not used for delayed refresh | P3 ✖️ ✅
meta-viewport Ensure <meta name="viewport"> does not disable text scaling and zooming 1.4.4 AA P2 ✖️ ✅
meta-viewport-large Ensure <meta name="viewport"> can scale a significant amount 1.4.4 AA P2 ✖️ ✅
page-has-heading-one Ensure that the page, or at least one of its frames contains a level-one heading 1.3.1 A P2 ✖️ ✅
p-as-heading Ensure bold, italic text and font-size is not used to style <p> elements as a heading 1.3.1 A P2 ✖️ ✅
region Ensure all page content is contained by landmarks 1.3.1 | P3 ✖️ ✅
scope-attr-valid Ensure the scope attribute is used correctly on tables 1.3.1 A P3 ✖️ ✅
skip-link Ensure all skip links have a focusable target 2.4.1 | P3 ✖️ ✅
tabindex Ensure tabindex attribute values are not greater than 0 2.4.3 A P3 ✖️ ✅
table-duplicate-name Ensure the <caption> element does not contain the same text as the summary attribute 1.3.1 | P3 ✖️ ✅
table-fake-caption Ensure that tables with a caption use the <caption> element. | P3 ✖️ ✅
td-has-header Ensure that each non-empty data cell in a <table> larger than 3 by 3 has one or more table headers 1.3.1 A P1 ✖️ ✅
aria-roledescription Ensure aria-roledescription is only used on elements with an implicit or explicit role | P3 ✖️ ✅
audio-caption Ensure <audio> elements have captions | P3 ✖️ ✅
duplicate-id Ensure every id attribute value is unique | P3 ✖️ ✅
duplicate-id-active Ensure every id attribute value of active elements is unique | P3 ✖️ ✅

changelog

Changelog

All notable changes to this project will be documented in this file.

4.0.0 (2022-10-20)

⚠ BREAKING CHANGES

  • Explicitly supporting NodeJS 14.x and 16.x
  • sa11y will no longer support Node.js 12, which is EOL since 30 April 2022

Features

Bug Fixes

Changelog

3.1.0 (2021-11-18)

Bug Fixes

  • automatic checks file filter to be exclusion only to keep it simple
  • add sa11y common pkg as dep instead of dev dep

3.0.2 (2021-11-02)

Reverts

  • filtering of non-a11y results introduced in 3.0.1
    • as it is causing issues with certain CI workflows that produce no test results file

3.0.1 (2021-10-21)

Refactor

  • exclude descendancy rules from Jest API
    • these are rules that might fail at unit/component level but might pass at page level
  • change sa11y results processor to output only a11y failures

3.0.0 (2021-09-16)

  • Moving to unified versioning of @sa11y packages instead of independent versioning for reducing complexity of managing independent versions
  • No code changes, No breaking changes

0.11.2-beta (2021-09-13)

WDIO

0.11.1-beta (2021-09-10)

Automatic checks

  • Add ability and convenience shortcut for excluding files from automatic checks (#74)

Results processor

  • Move the WCAG metadata and Priority info to class name in Jest results so that downstream CI systems make use of the info accordingly
    • Remove WCAG version, Level for brevity
  • Error msgs: Move help URL up in order to prevent it from getting truncated e.g. when CSS selectors are long

WDIO

  • Fix race condition when loading axe using poll with timeout

0.11.0-beta (2021-08-26)

BREAKING CHANGES ⚠️

  • Refactor rulesets into base, extended (#73)
    • with extended replacing recommended
    • base contains WCAG 2.1 AA rules available in axe-core
    • extended contains AAA rules, experimental rules and non-WCAG best practice rules
    • These ruleset changes could result in different test results from previous versions

Features

  • Add priority and WCAG Success Criteria metadata to preset-rules
  • Add config to run rules selectively by priority
  • Add script to generate preset rules markdown table in Readme with provided rules metadata

0.10.0-beta (2021-08-04)

Features

  • jest: add config to run automatic checks only on selected files
  • preset-rules: add config to override default ruleset using environment variable

0.9.1-beta (2021-07-05)

Fix

  • jest(result processor): move WCAG metadata from suite name to test name (#69)
  • jest: add workaround for mock timer timeout issue for API and automatic checks (#69)
  • build: move webdriverIO to dev dependency in sa11y common pkg (#68)

0.9.0-beta (2021-06-15)

Features

  • jest: de-duplicate a11y failures for automatic checks (#61)
  • jest: add a custom test results processor (#62)
    • create a new test suite to hold a11y errors
    • add wcag metadata to results output
    • transform a11y error details into suite, test names

0.8.0-beta (2021-03-19)

Features

  • browser-lib: add support for selecting specific css selector to check for a11y
  • wdio: add scope to target only given css selector for a11y checks
    • add custom browser commands for the sa11y APIs

BREAKING CHANGES

  • @sa11y/wdio APIs take an WdioOptions object instead of individual parameters (Webdriver, ExceptionList)

Refactor

  • refactor(test-integration): to use wdio runner rather than jest
  • refactor(test-utils): remove obsolete wdio jest bridge utils
  • test(wdio): refactor to common func to check a11y error
  • refactor: extract common types, interfaces into common package
  • build: update to axe v4.1.3
  • chore: update run script for husky v6

0.7.0-beta (2021-02-24)

Features

  • jest: add opts to invoke checks automatically after each test (#54)
  • Update axe-core to 4.1.2 (#54)

0.6.0-beta (2021-01-22)

Features

  • wdio: add exception list opt to wdio APIs (#51)
  • typescript: include d.ts TypeScript definitions in packages (#52)

0.5.0-beta (2020-12-01)

Features

  • preset-rules: add new rules from axe v4.1.1

0.4.1-beta (2020-11-24)

Bug Fixes

  • Upgrade to axe v4.1.1 which include bug fixes from v4.1.0 and v4.1.1 (#46)

0.4.0-beta (2020-10-31)

Features

  • browser-lib: add wrapper func to check a11y with opt to filter violations
  • format: add an exception list filter to filter a11y violations

Refactor

  • test(wdio): refactor to extract wdio standalone setup, teardown
  • refactor(common): create type alias for axe results for reuse

0.3.2-beta (2020-09-22)

Bug Fixes

  • preset-rules: disable preloading media in axe config to fix timeout (#41)

Refactor

  • chore: update typescript and typescript/eslint plugin to v4 (#37)

0.3.1-beta (2020-08-20)

Refactor

  • chore: update to the latest major release of axe

0.3.0-beta (2020-08-19)

Features

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

0.2.0-beta (2020-06-25)

Features

  • wdio: add assert accessible API for WDIO (#21)

  • preset-rules: add a full ruleset with all rules from axe (#21)

Bug Fixes

  • format: fix a11y error message to use formatted output (#21)
  • format: check explicitly for undefined to allow custom formatter (#21)
  • jest: fix a11y error being undefined when used with not matcher (#21), closes #18

BREAKING CHANGES

  • preset-rules: align name and behavior to follow common naming conventions in terms of preset configs (#21)
    • rename extended ruleset to recommended
      • it continues to be the default and recommended
    • rename recommended preset rule to base
    • If you are not using the preset-rules explicitly in the APIs, this change will not affect you
    • But if you are using the preset-rules explicitly in your APIs, you will have to change them
      • If you are using the recommended preset-rule rename it to base
      • If you are using the extended preset-rule rename it to recommended

v0.1.0-alpha (2020-06-02)

Features

  • format: add num of issues, unicode chars, jest matcher helper (#13)
  • format: sort a11y issues by impact (#13)

(2020-05-29)

Features

  • jest: add jest accessibility matcher (#9)

(2020-05-07)

Bug Fixes

  • preset-rules: revert object freeze on a11y config object

Features

  • assert: add assert accessible api (#7)
  • jest: add basic scaffolding for jest integration
  • jest: add scaffolding for jest expect matcher
  • jest: add toBeAccessibleWith jest a11y matcher for use with config
  • test-utils: add a test utilities package

(2020-04-07)

Bug Fixes

  • assert: fix stale import of a11y config
  • rules: fix import paths of modules in rules package

Features

  • assert: add scaffolding for assert package
  • format: add basic scaffolding for format package

(2020-03-20)

Bug Fixes

  • rules: add missed out rule label-content-name-mismatch

Features

  • ruleset: add recommended, extended rulesets (#3)