rule-descriptions.md 37.4 KB

Rule Descriptions

Table of Contents

WCAG 2.0 Level A & AA Rules

Rule ID Description Impact Tags Issue Type
area-alt Ensures <area> elements of image maps have alternate text Critical cat.text-alternatives, wcag2a, wcag111, wcag244, wcag412, section508, section508.22.a, ACT failure, needs review
aria-allowed-attr Ensures ARIA attributes are allowed for an element's role Critical cat.aria, wcag2a, wcag412 failure
aria-command-name Ensures every ARIA button, link and menuitem has an accessible name Serious cat.aria, wcag2a, wcag412 failure, needs review
aria-hidden-body Ensures aria-hidden='true' is not present on the document body. Critical cat.aria, wcag2a, wcag412 failure
aria-hidden-focus Ensures aria-hidden elements do not contain focusable elements Serious cat.name-role-value, wcag2a, wcag412, wcag131 failure, needs review
aria-input-field-name Ensures every ARIA input field has an accessible name Moderate, Serious cat.aria, wcag2a, wcag412, ACT failure, needs review
aria-meter-name Ensures every ARIA meter node has an accessible name Serious cat.aria, wcag2a, wcag111 failure, needs review
aria-progressbar-name Ensures every ARIA progressbar node has an accessible name Serious cat.aria, wcag2a, wcag111 failure, needs review
aria-required-attr Ensures elements with ARIA roles have all required ARIA attributes Critical cat.aria, wcag2a, wcag412 failure
aria-required-children Ensures elements with an ARIA role that require child roles contain them Critical cat.aria, wcag2a, wcag131 failure, needs review
aria-required-parent Ensures elements with an ARIA role that require parent roles are contained by them Critical cat.aria, wcag2a, wcag131 failure
aria-roledescription Ensure aria-roledescription is only used on elements with an implicit or explicit role Serious cat.aria, wcag2a, wcag412 failure, needs review
aria-roles Ensures all elements with a role attribute use a valid value Serious, Critical cat.aria, wcag2a, wcag412 failure
aria-toggle-field-name Ensures every ARIA toggle field has an accessible name Moderate, Serious cat.aria, wcag2a, wcag412, ACT failure, needs review
aria-tooltip-name Ensures every ARIA tooltip node has an accessible name Serious cat.aria, wcag2a, wcag412 failure, needs review
aria-valid-attr-value Ensures all ARIA attributes have valid values Critical cat.aria, wcag2a, wcag412 failure, needs review
aria-valid-attr Ensures attributes that begin with aria- are valid ARIA attributes Critical cat.aria, wcag2a, wcag412 failure
audio-caption Ensures <audio> elements have captions Critical cat.time-and-media, wcag2a, wcag121, section508, section508.22.a needs review
blink Ensures <blink> elements are not used Serious cat.time-and-media, wcag2a, wcag222, section508, section508.22.j failure
button-name Ensures buttons have discernible text Critical cat.name-role-value, wcag2a, wcag412, section508, section508.22.a, ACT failure, needs review
bypass Ensures each page has at least one mechanism for a user to bypass navigation and jump straight to the content Serious cat.keyboard, wcag2a, wcag241, section508, section508.22.o failure
color-contrast Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds Serious cat.color, wcag2aa, wcag143 failure, needs review
definition-list Ensures <dl> elements are structured correctly Serious cat.structure, wcag2a, wcag131 failure
dlitem Ensures <dt> and <dd> elements are contained by a <dl> Serious cat.structure, wcag2a, wcag131 failure
document-title Ensures each HTML document contains a non-empty <title> element Serious cat.text-alternatives, wcag2a, wcag242, ACT failure
duplicate-id-active Ensures every id attribute value of active elements is unique Serious cat.parsing, wcag2a, wcag411 failure
duplicate-id-aria Ensures every id attribute value used in ARIA and in labels is unique Critical cat.parsing, wcag2a, wcag411 failure
duplicate-id Ensures every id attribute value is unique Minor cat.parsing, wcag2a, wcag411 failure
form-field-multiple-labels Ensures form field does not have multiple label elements Moderate cat.forms, wcag2a, wcag332 needs review
frame-title Ensures <iframe> and <frame> elements contain a non-empty title attribute Serious cat.text-alternatives, wcag2a, wcag241, wcag412, section508, section508.22.i failure, needs review
html-has-lang Ensures every HTML document has a lang attribute Serious cat.language, wcag2a, wcag311, ACT failure
html-lang-valid Ensures the lang attribute of the <html> element has a valid value Serious cat.language, wcag2a, wcag311, ACT failure
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 cat.language, wcag2a, wcag311, ACT failure
image-alt Ensures <img> elements have alternate text or a role of none or presentation Critical cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a, ACT failure, needs review
input-button-name Ensures input buttons have discernible text Critical cat.name-role-value, wcag2a, wcag412, section508, section508.22.a failure, needs review
input-image-alt Ensures <input type="image"> elements have alternate text Critical cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a, ACT failure, needs review
label Ensures every form element has a label Minor, Critical cat.forms, wcag2a, wcag412, wcag131, section508, section508.22.n, ACT failure, needs review
link-name Ensures links have discernible text Serious cat.name-role-value, wcag2a, wcag412, wcag244, section508, section508.22.a, ACT failure, needs review
list Ensures that lists are structured correctly Serious cat.structure, wcag2a, wcag131 failure
listitem Ensures <li> elements are used semantically Serious cat.structure, wcag2a, wcag131 failure
marquee Ensures <marquee> elements are not used Serious cat.parsing, wcag2a, wcag222 failure
meta-refresh Ensures <meta http-equiv="refresh"> is not used Critical cat.time-and-media, wcag2a, wcag2aaa, wcag221, wcag224, wcag325 failure
object-alt Ensures <object> elements have alternate text Serious cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a failure, needs review
role-img-alt Ensures [role='img'] elements have alternate text Serious cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a, ACT failure, needs review
scrollable-region-focusable Elements that have scrollable content should be accessible by keyboard Moderate cat.keyboard, wcag2a, wcag211 failure
select-name Ensures select element has an accessible name Minor, Critical cat.forms, wcag2a, wcag412, wcag131, section508, section508.22.n, ACT failure, needs review
server-side-image-map Ensures that server-side image maps are not used Minor cat.text-alternatives, wcag2a, wcag211, section508, section508.22.f needs review
svg-img-alt Ensures svg elements with an img, graphics-document or graphics-symbol role have an accessible text Serious cat.text-alternatives, wcag2a, wcag111, section508, section508.22.a, ACT failure, needs review
td-headers-attr Ensure that each cell in a table using the headers refers to another cell in that table Serious cat.tables, wcag2a, wcag131, section508, section508.22.g failure, needs review
th-has-data-cells Ensure that each table header in a data table refers to data cells Serious cat.tables, wcag2a, wcag131, section508, section508.22.g failure, needs review
valid-lang Ensures lang attributes have valid values Serious cat.language, wcag2aa, wcag312 failure
video-caption Ensures <video> elements have captions Critical cat.text-alternatives, wcag2a, wcag122, section508, section508.22.a needs review

WCAG 2.1 Level A & AA Rules

Rule ID Description Impact Tags Issue Type
autocomplete-valid Ensure the autocomplete attribute is correct and suitable for the form field Serious cat.forms, wcag21aa, wcag135 failure
avoid-inline-spacing Ensure that text spacing set through style attributes can be adjusted with custom stylesheets Serious cat.structure, wcag21aa, wcag1412 failure

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 Tags Issue Type
accesskeys Ensures every accesskey attribute value is unique Serious cat.keyboard, best-practice failure
aria-allowed-role Ensures role attribute has an appropriate value for the element Minor cat.aria, best-practice failure, needs review
aria-dialog-name Ensures every ARIA dialog and alertdialog node has an accessible name Serious cat.aria, best-practice failure, needs review
aria-treeitem-name Ensures every ARIA treeitem node has an accessible name Serious cat.aria, best-practice failure, needs review
empty-heading Ensures headings have discernible text Minor cat.name-role-value, best-practice failure, needs review
frame-tested Ensures <iframe> and <frame> elements contain the axe-core script Critical cat.structure, review-item, best-practice failure, needs review
frame-title-unique Ensures <iframe> and <frame> elements contain a unique title attribute Serious cat.text-alternatives, best-practice failure
heading-order Ensures the order of headings is semantically correct Moderate cat.semantics, best-practice failure
identical-links-same-purpose Ensure that links with the same accessible name serve a similar purpose Minor cat.semantics, wcag2aaa, wcag249, best-practice needs review
image-redundant-alt Ensure image alternative is not repeated as text Minor cat.text-alternatives, best-practice failure
label-title-only Ensures that every form element is not solely labeled using the title or aria-describedby attributes Serious cat.forms, best-practice failure
landmark-banner-is-top-level Ensures the banner landmark is at top level Moderate cat.semantics, best-practice failure
landmark-complementary-is-top-level Ensures the complementary landmark or aside is at top level Moderate cat.semantics, best-practice failure
landmark-contentinfo-is-top-level Ensures the contentinfo landmark is at top level Moderate cat.semantics, best-practice failure
landmark-main-is-top-level Ensures the main landmark is at top level Moderate cat.semantics, best-practice failure
landmark-no-duplicate-banner Ensures the document has at most one banner landmark Moderate cat.semantics, best-practice failure
landmark-no-duplicate-contentinfo Ensures the document has at most one contentinfo landmark Moderate cat.semantics, best-practice failure
landmark-no-duplicate-main Ensures the document has at most one main landmark Moderate cat.semantics, best-practice failure
landmark-one-main Ensures the document has a main landmark Moderate cat.semantics, best-practice failure
landmark-unique Landmarks must have a unique role or role/label/title (i.e. accessible name) combination Moderate cat.semantics, best-practice failure
meta-viewport-large Ensures <meta name="viewport"> can scale a significant amount Minor cat.sensory-and-visual-cues, best-practice failure
meta-viewport Ensures <meta name="viewport"> does not disable text scaling and zooming Critical cat.sensory-and-visual-cues, best-practice, ACT failure
page-has-heading-one Ensure that the page, or at least one of its frames contains a level-one heading Moderate cat.semantics, best-practice failure
presentation-role-conflict Flags elements whose role is none or presentation and which cause the role conflict resolution to trigger. Minor cat.aria, best-practice failure
region Ensures all page content is contained by landmarks Moderate cat.keyboard, best-practice failure
scope-attr-valid Ensures the scope attribute is used correctly on tables Moderate, Critical cat.tables, best-practice failure
skip-link Ensure all skip links have a focusable target Moderate cat.keyboard, best-practice failure, needs review
tabindex Ensures tabindex attribute values are not greater than 0 Serious cat.keyboard, best-practice failure
table-duplicate-name Ensure that tables do not have the same summary and caption Minor cat.tables, best-practice failure

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 Tags Issue Type
css-orientation-lock Ensures content is not locked to any specific display orientation, and the content is operable in all display orientations Serious cat.structure, wcag134, wcag21aa, experimental failure, needs review
focus-order-semantics Ensures elements in the focus order have an appropriate role Minor cat.keyboard, best-practice, experimental failure
hidden-content Informs users about hidden content. Minor cat.structure, experimental, review-item, best-practice failure, needs review
label-content-name-mismatch Ensures that elements labelled through their content must have their visible text as part of their accessible name Serious cat.semantics, wcag21a, wcag253, experimental failure
link-in-text-block Links can be distinguished without relying on color Serious cat.color, experimental, wcag2a, wcag141 failure, needs review
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 cat.time-and-media, wcag2a, wcag142, experimental failure, needs review
p-as-heading Ensure p elements are not used to style headings Serious cat.semantics, wcag2a, wcag131, experimental failure
table-fake-caption Ensure that tables with a caption use the <caption> element. Serious cat.tables, experimental, wcag2a, wcag131, section508, section508.22.g failure
td-has-header Ensure that each non-empty data cell in a large table has one or more table headers Critical cat.tables, experimental, wcag2a, wcag131, section508, section508.22.g failure

Deprecated Rules

Deprecated rules are not enabled by default and will be removed in the next major release.

There are no matching rules