The HTML-AAM is part of the WAI-ARIA suite described in the
WAI-ARIA Overview.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the
W3C standards and drafts index.
Note
This document is subject to change without notice.
Publication as an Editor's Draft does not
imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than a work in progress.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent that the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
In some cases, often due to features of the HTML host language or the accessibility API in question, an element or attribute's mapping differs from the corresponding ARIA mappings specified in
the [core-aam-1.2]. Where an HTML element or attribute does not have any default WAI-ARIA semantics, the applicable mapping for each platform accessibility API is
defined by this specification.
Users often access HTML content using assistive technologies that rely on platform accessibility API to obtain and
interact with information from the page. This document is part of the following suite of accessibility API mapping specifications for content rendered by user agents:
If user agent developers need to expose information using other accessibility APIs, it is recommended that they work closely with the developer of the platform where
the API runs, and assistive technology developers on that platform.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all
capitals, as shown here.
Normative sections provide requirements that user agents and assistive technologies MUST follow for an implementation to conform to this specification.
Non-normative (informative) sections provide information useful to understanding the specification. Such sections may contain examples of recommended practice, but it is not required to follow
such recommendations in order to conform to this specification.
2.1 Deprecated
There are currently no deprecated requirements.
3. Mapping HTML to Accessibility APIs
3.1 General Rules for Exposing WAI-ARIA Semantics
Note
WAI-ARIA support was first introduced to HTML in [HTML5].
3.3 Exposing HTML Features That Do Not Directly Map to Accessibility APIs
HTML can include features that are not supported by accessibility APIs at the time of publication. There is not a one to one relationship between all features and
platform accessibility APIs. When HTML roles, states and properties do not directly map to an accessibility API, and there is a method in the
API to expose a text string, user agents MUST expose the undefined role, states and properties via that method.
3.4 Exposing HTML Features That Require a Minimum Role
A minimum role is the equivalent WAI-ARIA role an element will map to if the element does not have a more specific implicit role or platform role mappings, e.g., a non-generic
role. This can help ensure that users of assistive technologies get the best possible experience for commonly-used and valid HTML markup where otherwise a role would not be exposed.
A minimum role is provided when all of the following conditions are true:
the author has not specified a valid explicit WAI-ARIA role to the element, or the specified role is either none, presentation, or generic;
the element either has no implicit WAI-ARIA role or platform role mappings, or it has an implicit generic or none computed role;
and the author has specified attributes which require a minimum role mapping for the element.
When these conditions are met, user agents MUST expose an object using the mappings defined in CORE-AAM for the specified minimum role. If the element has multiple attributes specified which
require a minimum role be returned as the computed role for the element, prioritize the more specific role in the ARIA taxonomy.
3.5 HTML Element Role Mappings
User agents MUST map HTML elements with implicit WAI-ARIA role semantics to platform accessibility APIs according to the identified WAI-ARIA role mapping as defined
in the [core-aam-1.2] specification.
"Not mapped" means the element does not need to be exposed via an accessibility API. This is usually because the element is not displayed as part of the user
interface. However, authors can force some of these elements to be rendered. For instance, by overriding user agent styles to render elements that would have been otherwise set to
display: none. In these cases, the user agent SHOULD map such elements to the role of generic, unless other HTML features have been
specified which would require a more specific minimum role to be exposed.
Where an element is indicated as having "No corresponding (WAI-ARIA) role", or is mapped to the generic role, user agents
MUST NOT expose the aria-roledescription property value in the accessibility tree unless the element has an
explicit, conforming role attribute value which [WAI-ARIA-1.2] does not prohibit the use of aria-roledescription.
When HTML elements do not have an exact or equivalent mapping to a valid, non-abstract WAI-ARIA role, a unique computedrole
string has been specified to serve as the return value for interoperability testing purposes. For instance, user agents MAY expose the video element with a computedrole of
"html-video". Authors MUST NOT use any html-prefixed computed role string in the role attribute (such as html-video). User Agents MUST ignore any abstract or invalid role token.
All elements with accessible objects SHOULD implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.
UIA:
When a labelable element is referenced by a label element's for attribute, or a descendant of a label element, the labelable
element's UIA LabeledBy property points to the UIA element for the label element.
Elements mapped to the Text Control Type are not generally represented as accessible objects in the
accessibility tree, but are just part of the Text Control Pattern implemented for the whole HTML document. However, if they have any aria- attributes or an
explicit tabindex specified, elements mapped to the Text Control Type will be represented as accessible objects in the
accessibility tree.
AXAPI:
User agents SHOULD return a user-presentable, localized string value for the Mac Accessibility AXRoleDescription.
User agents MAY still expose an a element lacking the href attribute with a link role in the event an author specifies interactive behavior for the element. For example, if using
an event handler attribute.
Note: If the controls attribute is present, UI controls (e.g., play, volume) are exposed as children of the
audio element in the accessibility tree, and mapped as appropriate for the type of control (e.g.,
button or slider).
User agents MAY include the following in the accessibility tree and mark them as hidden or off-screen:
Note: If the controls attribute is present, UI controls (e.g., play, volume) are exposed as descendants of an
accessible object with a role of toolbar, and mapped as appropriate for the type of control (e.g.,
button or slider).
listbox role, with the aria-multiselectable property set to "true"
if the datalist's selection model allows multiple option elements to be selected at a time, and "false" otherwise
If an hgroup contains multiple heading elements, then the user agent MAY treat the heading element with the highest priority level as the sole heading of the hgroup. The user agent
MAY expose all other heading elements as if they were p elements. See paragraph role on Core AAM.
If an img has an empty alt, but has been provided an accessible name via another valid naming mechanism per the
naming steps of this specification, user agents will expose the element with its implicit image role.
If implemented as a color picker, any UI controls presented for selecting a color are exposed in the accessibility tree, associated with the input element,
and mapped as appropriate for the type of control (e.g., button or slider).
Role:ROLE_SYSTEM_SPINBUTTON if implemented as a simple widget; ROLE_SYSTEM_GROUPING with child controls mapped as appropriate if
implemented as a complex widget
Role:ATK_ROLE_SPINBUTTON if implemented as a simple widget.
If implemented as a complex widget use: Role:ROLE_PANEL and map child controls as appropriate.
No accessible object. Styles used are exposed by UIA text attribute identifiers of the TextRange Control Pattern implemented on a parent accessible object.
Relations:IA2_RELATION_LABEL_FOR with a labelable element that is child to the label or referred to by the label element's
for attribute. The associated labelable element has IA2_RELATION_LABELLED_BY pointing to the label.
When the label element contains a labelable element, the LabeledBy property for the element points to the UIA element for the
label element.
When the label element has a for attribute referencing a labelable element, the LabeledBy
property for the referenced element points to the UIA element for the label element.
Relations:ATK_RELATION_LABEL_FOR for a child labelable element or labelable element referred by
for attribute. Note, related labelable element provides ATK_RELATION_LABELLED_BY pointing to the label.
listitem role with aria-setsize value reflecting number of li
elements within the parent ol, menu or ul and aria-posinset
value reflecting the li elements position within the set.
If li element is not a child of ol , menu or ul, or if the containing list element is no longer exposed
with a list role, then expose the li element with a generic role.
Role:AXImageMap if used as an image map. Otherwise, Role:AXGroup if associated with an img with no alt. Otherwise,
not mapped if not associated with an img.
The menu element is a semantic alternative to the ul element. It has no implemented mappings or behavior that reflect the semantics
of the ARIA menu role.