Axe Core Guide
<html> element must have a lang attribute
For multilingual screen reader users who would prefer a language other than the default, the HTML document element must have a valid lang property or match to a valid lang code.
The default language is chosen by users when setting up a screen reader. The screen reader uses the user’s default language preference when a webpage’s language is not specified. When people visit websites in more than one language and speak various languages, language settings become a problem. To ensure that website text is pronounced accurately, a language must be specified and validated.
Based on the pronunciation and traits of each language, screen readers employ distinct sound libraries for each one. If the documents state which language(s) to read when, screen readers can effortlessly switch between these language libraries. The screen reader will read the page in the user’s default language if the language is not set, which will result in an odd accent. When screen readers are utilizing the incorrect language library, nothing can be understood.
What this Accessibility Rule Checks
Ensures that the lang attribute is present in every HTML document.
Learn more:
Related Accessibility Rules
For multilingual screen reader users who may prefer a language different than the default, the HTML content must contain a valid lang attribute or correlate to a valid lang code.
Users choose a default language when configuring a screen reader. If the language of a webpage is not provided, the screen reader uses the user’s default language. Language settings are a problem for users who speak different languages and visit websites in multiple languages. It is critical to declare a language and guarantee that it is valid in order for website text to be properly pronounced.
Screen readers employ various sound libraries for each language based on its pronunciation and characteristics. Screen readers can readily switch between these language libraries, but only if the documents specify which language(s) they should read. If no language is supplied, the screen reader reads the content in the user’s default language, which results in a perplexing accent! When screen readers use the incorrect language library, it is difficult to understand anything.
What this Accessibility Rule Checks
Ensures that every HTML document contains a lang or xml:lang property with a valid value.
Not all ARIA role-attribute combinations are valid. This rule ensures that each role has the required qualities.
Using ARIA attributes in roles where they are not permitted can impair web page accessibility. Using an improper role-attribute combination will have no effect on application accessibility at best and may trigger behavior that blocks accessibility for entire areas of an application at worst.
When ARIA attributes are used on HTML elements that do not conform to WAI-ARIA 1.1, they interfere with the semantics of the elements, causing assistive technology products to display nonsensical user interface (UI) information that does not represent the document’s true UI.
What this Accessibility Rule Checks
Checks that each element with an ARIA role is using only the ARIA attributes that are permitted for that role.
This rule determines whether or not aria-hidden elements contain focusable elements.
Using the property aria-hidden="true" on an element removes the element and all of its child nodes from the accessibility API, rendering the element fully unavailable to screen readers and other assistive technology.
aria-hidden may be used with extreme discretion to hide visibly displayed content from assistive technologies if the act of hiding this content is meant to enhance the experience of assistive technology users by reducing redundant or superfluous content.
If aria-hidden is employed to hide material from screen readers, the same or equal meaning and functionality must be made available to assistive technologies.
Using aria-hidden="false" on content that is a descendant of an element that is hidden using aria-hidden="true" will not reveal that content to the accessibility API, nor will it be accessible to screen readers or other assistive technology.
The rule applies to any element whose aria-hidden attribute value is true.
By adding aria-hidden="true" to an element, authors assure that assistive technologies will disregard the element.
This can be used to hide aesthetic elements, such as icon typefaces, that are not intended to be read by assistive technologies.
A focusable element with aria-hidden="true" is disregarded as part of the reading order, but is still part of the focus order, making it unclear if it is visible or hidden.
What this Accessibility Rule Checks
For all user interface components, including form elements, links, and script-generated components, the name and role can be identified programmatically; user-specified states, properties, and values can be set programmatically; and user agents, including assistive technologies, are notified of changes.
Ensures every ARIA input field has an accessible name.
This rule ensures that each ARIA input field has a name that is accessible.
There must be accessible names for the following input field roles:
- combobox
- listbox
- searchbox
- slider
- spinbutton
- textbox
What this Accessibility Rule Checks
The names of ARIA input fields must be accessible.
Ensures that the aria-roledescription attribute is only applied to elements having explicit or implicit role values.
Inappropriate aria-roledescription attribute values that clash with an element’s implicit or explicit role value can impede the web page’s accessibility. A contradictory aria-roledescription attribute value may have no effect on the application’s accessibility and may trigger behavior that blocks accessibility for entire application sections.
When aria-roledescription attributes are applied to HTML elements not in accordance with WAI-ARIA 1.1, a semantic conflict may occur between the aria-roledescription value and the implicit or explicit element role value, resulting in assistive technology products reporting nonsensical user interface (UI) information that does not accurately represent the intended UI experience.
What this Accessibility Rule Checks
Use aria-roledescription values to adequately explain implicit or explicit element role values.
ARIA role values must be assigned valid values. Role values must be appropriately written, correlate to existing ARIA role values, and not be abstract roles in order to correctly display the element’s purpose.
Assistive technologies do not read elements with erroneous ARIA role values as intended by the developer.
When screen readers and other assistive devices do not know the function of each element on a web page, they are unable to interact with or communicate the function to the user. When a role value is invalid, an element’s characteristics, properties, and ways of transmitting information to and/or from the user can be communicated via assistive technologies.
What this Accessibility Rule Checks
Examines each element containing the WAI-ARIA role property to check that its value is valid.
Makes certain that each ARIA toggle field has an accessible name.
Ensures that any element having a semantic role has a name that is easily accessible.
Among the semantic roles are:
- checkbox
- menu
- menuitemcheckbox
- menuitemradio
- radio
- radiogroup
- switch
What this Accessibility Rule Checks
There is an accessible name for ARIA toggle fields.
Valid values must be present for ARIA properties that begin with aria-.
To fulfill the intended accessibility purpose, these values must be written correctly and relate to values that make sense for a certain property.
ARIA attributes (those beginning with aria-) must have legitimate values. For a given attribute to fulfill the intended accessibility function, these values must be written correctly and correlate to values that make sense.
A diverse range of values are accepted for many ARIA attributes. There must be permitted values, acceptable “undefined” values, and acceptable “default” values.
Content that does not adhere to the permitted values is inaccessible to users of assistive technology.
What this Accessibility Rule Checks
Verifies that the WAI-ARIA attributes’ values are correct for each element that contains them.
Each page must have a main landmark to allow users to rapidly traverse repetitive blocks of material or interface elements (such as the header and navigation) and get the primary content.
Due to the fact that websites frequently display secondary, repetitive content on several pages (such as navigation links, heading graphics, and advertising frames), keyboard-only users benefit from faster, more direct access to a page’s principal content. This saves keystrokes and reduces physical discomfort.
It is more difficult and time-consuming for users who cannot use a mouse to navigate using the keyboard if the interface does not provide features to facilitate keyboard navigation. To activate a link in the middle of a web page, for instance, a keyboard user may have to browse through a significant number of links and buttons in the page’s header and primary navigation.
Extremely motor-impaired users may require several minutes to browse through all of these pieces, which can cause to tiredness and potential physical pain for some users. Even users with less severe limitations will require more time than users with a mouse, who can click on the desired link in less than a second.
What this Accessibility Rule Checks
Checks for the presence of at least one of the following features:
- an internal skip link
- a header
- a geographical landmark
Definition lists (dl) may only contain dt and dd groups, div, script, or template elements that are properly organized.
Screen readers have a particular method for reading definition lists. When such lists are not correctly marked up, screen reader output may be erroneous or confusing.
A list of definitions is used to explain the meaning of words or phrases. Using the dl element, the definition list is formatted. Within the list, each term is enclosed in its own dt element, and its definition is enclosed in the dd element that immediately follows.
What this Accessibility Rule Checks
Ensures that each dl element is correctly constructed.