Axe Core Guide

WAI-ARIA role attribute values must be correct. This means that values must be written correctly, correlate to existing ARIA role values, and not be abstract roles in order to properly display the element’s purpose.

When an assigned WAI-ARIA role value for the parent element is invalid, a developer’s intended accessible technology activity is disabled.

When screen readers and other assistive devices do not understand the job of each element on a web page, they cannot interact with it intelligently or explain the role to the user. When the value for a role is invalid, assistive technologies are unable to communicate the element’s features, properties, and methods. Applying role="table" to a <ul>, for example, effectively hijacks the default semantics associated with the <ul> element in a way that screenreaders do not expect, resulting in unexpected behavior.

What this Accessibility Rule Checks

Check all elements with WAI-ARIA role attribute values to confirm the role value is correct. The role value must be appropriate for the element in the context of the document.

It is a best practice to make sure each heading element, denoted by the tags <h1> through <h6>, contains text.

Users of screen readers are informed when a heading tag is present. Users may become confused or even unable to access information on the page’s structure if the headline is blank or the text cannot be accessible.

Users of this technology won’t be able to hear the content of a header if the text inside it is inaccessible to a screen reader. Users using screen readers must be able to access the contents since headings reveal the structure of a webpage.

Applying header markup (<h1> through <h6>) is a quick approach to make content stand out, but doing so will make it more difficult for those using assistive technology to navigate a website.

Due to the fact that search engines use headings when filtering, arranging, and showing results, headers offer advantages beyond just making a page more accessible. Making your website more searchable is another benefit of making it more accessible.

Users of screen readers can navigate between headings in the same manner that sighted users might skim a page to gain a sense of its contents. Users, especially those who use screen readers, can save a ton of time and stress by using well-written, logically-arranged headings.

What this Accessibility Rule Checks

Ensures that headings have content and that a screen reader can access that content.

Whether native HTML or a custom widget, user input elements need to play the right roles in order to make their meaning clear to screen reader users when they are focused on and landed on. If a custom widget, the element’s function must be correctly exposed by using appropriate ARIA role values rather than abstract roles.

In order for screen reader technology to convey information to users, elements in the focus order must play a function appropriate for interactive content.

If interactive content elements do not have the proper roles, the developer’s planned accessibility function cannot be carried out by the role.

When screen readers and other assistive technologies cannot communicate to the user the proper role of each element on the web page, they are unable to interact with it sensibly. Assistive technology cannot communicate with an HTML element’s set of features, properties, and ways of communicating information to and/or from the user when the value for a role is invalid.

What this Accessibility Rule Checks

Verifies that the role attribute value is accurate and suitable for all interactive components in the focus order, regardless of whether they are native HTML or customized ARIA widgets.

Markup for data tables can be tedious and complex. Make sure the summary table’s properties and the caption don’t match. There are several capabilities in screen readers that help with table navigation, but for these features to function properly, the tables must be accurately marked up.

Tables are announced in a certain way by screen readers. The potential for unclear or erroneous screen reader output exists when tables are not properly marked up.

Screen reader users may become perplexed and struggle to understand the name and function of the table if the summary and caption text for the table are identical.

What this Accessibility Rule Checks

Verifies that the wording in data tables that have both a summary and a caption is not the same.

Values assigned to ARIA role values must not be deprecated.

Using deprecated WAI-ARIA roles is bad for accessibility. They will not be recognized or correctly processed by screen readers and other assistive technologies. Using these means not everyone will be able to access essential information.

Ensure all values assigned to role="" correspond to WAI-ARIA roles that are not deprecated, or abstract. The following list indicates for each deprecated role a potential alternative that is better supported by assistive technologies:

• directory: Consider using section, list, or tree instead. Which is most appropriate depends on how directory was used.

What this Accessibility Rule Checks

Check all elements containing WAI-ARIA role attribute to ensure that the role is not deprecated in the latest version of the WAI-ARIA specification.

To avoid assistive technology missing the second instance, the value supplied to an id property must be distinct. In other words, id attributes may not be used more than once to distinguish one element from another within the same document.

Elements on a page are uniquely identified via the ID attribute. It makes no sense to make a second id.

Duplicate ids can make labels for forms, table header cells, etc. inaccessible since screen readers and client-side scripts pass over the second iteration. They are typical markup validation mistakes that, if they do not damage accessibility, can reduce potential causes of accessibility issues.

Those who are familiar with client-side scripting are aware that when an ID is reused, the script normally only reacts to the first instance of that id use. Similar to this, assistive technology might only appropriately reference the first id when referencing an id.

What this Accessibility Rule Checks

Makes certain that every element on the page with an id attribute has a distinct value for the id attribute.

The text in table header components should be visible. Make sure screen reader users can access the table header. It is preferable to mark up an element with a td if it is not a header.

Both sighted users and screen reader users should be able to comprehend the visible text that explains the purpose of the row or column in table header components.

What this Accessibility Rule Checks

Verifies that each table header element has a visible text.

Tests with axe-core are required for frames.

The tool cannot do violation testing on numerous levels of nested iframes without the axe-core script.

What this Accessibility Rule Checks

Axe is instructed to run within iframes when the iframes property is set to true. This checks for the axe-core script to deliver a “review item” result using both frame and iframe selectors.

The h1 through h6 element tags must be in a sequentially-descending order for headings to be in a correct logical order.

The fundamental goal of headers is to communicate the page’s organizational structure. The same goal is served by employing various font sizes for sighted users.

For screen reader users, however, text size is useless because a screen reader can only recognize a header if it is correctly marked up. When header components are used correctly, both sighted and screen reader users will find it much simpler to traverse the page.

Users of screen readers can navigate between headings in the same manner that sighted users might skim a page to gain a sense of its contents. Users, especially those who use screen readers, can save a ton of time and stress by using well-written, logically-arranged headings.

Headings serve to explain the organization of the webpage, not only to draw attention to key text. They ought to be succinct, distinct, and accompanied by h1 through h6 components used in hierarchical order. Headings are useful tools for screen reader users because of all of these characteristics. Screen reader users can move among headings in a manner akin to how sighted readers can quickly scan a page and get a sense of its content. Screen readers can save time and stress by using headings that are clearly written and arranged.

Since search engines employ headings when filtering, arranging, and showing results, headings offer other advantages outside just making the page more easily accessible. Making your website more searchable is another benefit of making it more accessible.

What this Accessibility Rule Checks

Ensures the semantic accuracy of the headings’ order.

Notifies users of content that is hidden and unable to be checked for accessibility issues.

It is impossible to automatically check hidden content for accessibility rules breaches.

Screen reader users and sighted people must both be able to view visually hidden content. When content needs to be hidden from seeing users for a compelling reason, it is typically also necessary to hide it from blind users for the same reason. Making the content accessible to blind users makes sense when it is already available to sighted users.

When the CSS values display: none or visibility: hidden are used, content will be hidden from screen reader users (and all sighted users as well). The items become accessible to screen reader users when CSS properties are changed to display: block, display: inline, or other display values.

What this Accessibility Rule Checks

Checks for the presence of the hidden item content CSS style property values of display: none and visibility: hidden, and notifies users of their presence.