Introduction

This specification defines how HTML user agents must respond to and expose role, state and property information provided for Web content. Unless indicated otherwise, an HTML element or attribute with default Accessible Rich Internet Applications (WAI-ARIA) 1.1 [[!WAI-ARIA]] semantics must be exposed to the platform accessibility APIs according to the relevant WAI-ARIA mappings defined in the Core Accessibility API Mappings [[!CORE-AAM]] specification. 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]]. 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.

These RFC2119 key words are formatted in uppercase and contained in a strong element with class="rfc2119". When these key words are used, but do not share this format, they do not convey any formal conformance requirements in the RFC2119 sense, and are merely explanatory, i.e., informative. As much as possible, such usage is avoided in this specification.

The classification of a section as normative or non-normative applies to the entire section and all sub-sections of that section.

Normative sections provide requirements that authors, user agents, and assistive technologies MUST follow for an implementation to conform to this specification.

Non-normative 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.

Conflicts Between Native Markup Semantics and WAI-ARIA

Exposing HTML Features That Do Not Directly Map to Accessibility APIs

HTML may have 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.

Other Accessibility Implementations

In MSAA, the value of an accessible object's Role property is retrieved with the IAccessible::get_accRole method. This method returns a VARIANT that is limited to a finite number of integer role constants insufficient for describing the role of every HTML element, especially new elements introduced by HTML5. To address this limitation, some user agents, e.g., Firefox and Chrome in cooperation with some screen readers, have elected to expose certain roles by returning a string value (BSTR) in that VARIANT in a way that is not described by the MSAA specification.

Where an element is indicated as having "No corresponding [WAI-ARIA] 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.

IAccessible2:

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 explict tabindex specified, elements mapped to the Text Control Type will be represented as accessible objects in the accessibility tree.

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).

Text objects associated with loading or error messages, and any UI control not currently displayed, MAY be present in the accessibility tree and marked as hidden or off-screen.

Role: ATK_ROLE_AUDIO

AXRole: AXGroup

AXSubrole: AXAudio

AXRoleDescription: "audio playback"

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).

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).

Relations: IA2_RELATION_LABEL_FOR with a form control that is child to the label or referred to by the label element's for attribute. The associated form element has IA2_RELATION_LABELLED_BY pointing to the label.

Interfaces: IAccessibleText2; IAccessibleHypertext2

Control Type: Text

Other properties: When the label element contains an input element, the LabeledBy property for the input element points to the UIA element for the label element.

When the label element has a for attribute referencing another element, the LabeledBy property for the referenced element points to the UIA element for the label element.

Role: ATK_ROLE_LABEL

Relations: ATK_RELATION_LABEL_FOR for a child form element or form element
referred by for attribute. Note,
related form element provides ATK_RELATION_LABELLED_BY
pointing to the label.

Note: There are instances where CSS properties can affect what is exposed by accessibility APIs. For instance, display: none or visibility: hidden will remove an element from the accessibility tree and hide its presence from assistive technologies.

Note: If the controls attribute is present, UI controls (e.g. play, volume) are exposed as children of the video element in the accessibility tree, and mapped as appropriate for the type of control (e.g. button or slider).

Text objects associated with loading or error messages, and any UI control not currently displayed, MAY be present in the accessibility tree and marked as hidden or off-screen.

Role: ATK_ROLE_VIDEO

AXRole: AXGroup

AXSubrole: AXVideo

AXRoleDescription: "video playback"

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).

If a line break is added, expose it with IAccessibleText on the text container

Not mapped

A line break if added is exposed via Text interface on its text container

AXRole: AXGroup

AXSubrole: (nil)

AXRoleDescription: "group"

HTML Attribute State and Property Mappings

Notes:

HTML attributes with default WAI-ARIA state and property semantics must be mapped to platform accessibility APIs according to those WAI-ARIA state and property mappings as defined in the Core Accessibility API Mappings [[!CORE-AAM]] specification.

A '?' in a cell indicates the data has yet to be provided.

"Not mapped" (Not Applicable) means the attribute does not need to be exposed via an accessibility API. This is usually because the attribute is not displayed as part of the user interface.

All elements having an accessible object in IAccessible2 mapping are supposed to implement IAccessible, IAccessible2 and IAccessible2_2 interfaces.

Links the cell to its header cells. Exposed via IAccessibleTableCell::rowHeaderCells and IAccessibleTableCell::columnHeaderCells.

Links the cell to its header cells. Exposed via Table.ItemColumnHeaderItems and Table.ItemRowHeaderItems.

Links the cell to its row and column header cells
(note, only one row and one column header cells can be exposed because of API restrictions).
See atk_table_get_row_header and atk_table_get_column_header.

The value of the lang attribute is exposed as a locale identifier by Culture property of the UIA element representing the HTML element, and by Culture attribute of the TextRange Control Pattern implemented on a parent accessible object.

When the placeholder and aria-placeholder attributes are both present, and the placeholder attribute's value is non-empty, user agents MUST expose the value of the placeholder attribute, and ignore aria-placeholder. If the placeholder attribute's value is empty, then user agents MUST expose the value of the aria-placeholder attribute.

Defines the list item marker, which has no accessible object, but is exposed as content in the accessible text of the associated list item.

Interfaces: IAccessibleText2

Defines the list item marker, which has no accessible object, but is exposed as content in the accessible text of the associated list item.

Control Pattern: Text

Defines the list item marker, which has no accessible object, but is exposed as content in the accessible text of the associated list item.

Interfaces: ATKText

Defines the list item marker, which is exposed as content in AXValue, and rendered as an accessible object:

AXRole: AXListMarker

AXSubrole: (nil)

AXRoleDescription: "list marker"

Some platforms (IAccessible2, ATK, UIA) do not expose an accessible object for the list item marker, whether it was created and then pruned from the accessibility tree, or never created in the first place. Instead, they expose the list item marker as part of the associated list item's accessible text. In these cases, implementors need to consider such things as adjusting the offsets (e.g. for caret-moved events, text-selection events, etc.) for the updated list item text that now also contains the list item marker as content, rather than just taking the offsets unmodified from the list item renderer.

Accessible Feature Implementation Examples

summary and details Elements

Focus and Keyboard Interaction

The summary element should be focusable by default.

The details element should not focusable by default.

Pressing the spacebar or enter key when the summary element has focus will show the details element content if the content is hidden. If the details element content is showing and the summary element has focus, pressing the spacebar or enter key will hide the details element content.

The default accessible name for the summary element is the text content of the summary element.

When the details element content is hidden, the state of the content should be reflected by an accessible state or property.

Example 1: In the Mac accessibility API on the summary element (AXDisclosureTriangle), set AXExpanded property to NO. When the details element content is shown, on the summary element (AXDisclosureTriangle), set theAXExpanded property to YES. The hidden and shown states of the details element content is reflected by the absence or presence of the open attribute.

Example 2: In the IA2 accessibility API on the summary element (ROLE_SYSTEM_PUSHBUTTON), set STATE_SYSTEM_COLLAPSED. When the details element content is shown, on the summary element (ROLE_SYSTEM_PUSHBUTTON), set STATE_SYSTEM_EXPANDED. The hidden and shown states of the details element content is reflected by the absence or presence of the open attribute.

The figure and figcaption Elements

to do

Appendices

Change Log

Substantive changes since moving entirely to the Web Platform Working Group (01-Oct-2016)

07-Feb-2018: Added entries for the rb and rtc elements, and updated AXAPI mappings for the rb, rt and ruby elements. See GitHub issue #115.

Acknowledgments

The following people contributed to the development of this document.

Participants active in the HTML Accessibility Task Force active at the time of publication

@@

Enabling funders

This publication has been funded in part with U.S. Federal funds from the Department of Education, National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR), initially under contract number ED-OSE-10-C-0067 and currently under contract number HHSP23301500054C. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.