Copyright © 2014-2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document describes how user agents determine names and descriptions of accessible objects from web content languages and expose them in accessibility APIs. This allows assistive technologies to associate and relay the name or description of objects to users. Documenting the algorithm and mappings promotes interoperable exposure of these properties and events as implemented by different accessibility APIs, and helps to ensure that this information appears in a manner consistent with author intent.
The accessible name and description computation and mappings specification defines support that applies across multiple content technologies. This includes accessible name and description provided by general-purpose WAI-ARIA [WAI-ARIA] roles, states, and properties as well as features specific to individual content languages. The accessible name and description computation extends the mapping guidance provided by CORE-AAM [CORE-AAM] and technology-specific accessibility API mappings.
This document updates and will eventually supersede the accessible name and description guidance in the WAI-ARIA 1.0 User Agent Implementation Guide [WAI-ARIA-IMPLEMENTATION] W3C Recommendation. It is part of the WAI-ARIA suite described in the WAI-ARIA Overview.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is a Working Draft of Accessible Name and Description: Computation and API Mappings 1.1 by the Accessible Rich Internet Applications Working Group of the Web Accessibility Initiative. It supports WAI-ARIA 1.1 [WAI-ARIA] and complements Core Accessibility API Mappings 1.1 [CORE-AAM]. This version has editorial changes to better sync with companion documents. A history of changes to Accessible Name and Description: Computation and API Mappings is available in the appendix.
Feedback on any aspect of the specification is accepted. For this publication, the Accessible Rich Internet Applications Working Group particularly seeks feedback on the following questions:
To comment, send email to public-aria@w3.org (comment archive) or file an issue in the W3C ARIA GitHub repository. Comments are requested by 15 April 2016. In-progress updates to the document may be viewed in the publicly visible editors' draft.
Publication as a Working Draft does not imply endorsement by the W3C Membership. 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 work in progress.
This document was produced by a group operating under the 5 February 2004 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 which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
This section is informative.
User agents acquire information from the DOM and create a parallel structure called the accessibility tree, made up of accessible objects. An accessible object provides information about its role, states, and properties. An example is an accessible object whose role is menuitem
, is currently in an enabled
state, with a haspopup
property, indicating that it leads to a sub-menu.
The two properties of accessible objects described in this document are its accessible name and accessible description. The name is a short label that provides information about the purpose of the object. An example of an accessible name for a menu item is New
, signifying that the menu item provides for the creation of new documents, windows, and so on.
The description is a short explanation that further clarifies the nature of the accessible object. It is not always necessary to provide a description if the name is sufficient, but it can help a user better understand the use of the object.
Accessibility APIs currently support flat, unstructured strings for accessible names and descriptions. The result of the name/description computation is thus a flat string.
The terms "accessible name" and "accessible description" are used to emphasize that they are properties of accessible objects as exposed by Accessibility APIs. However, they are frequently referred to hereafter as simply "name" and "description".
This section is normative.
This specification indicates whether a section is normative or informative and the classification applies to the entire section. A statement "This section is normative" or "This section is informative" applies to all sub-sections of that section.
Normative sections provide requirements that user agents must follow for an implementation to conform to this specification. The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in Keywords for use in RFCs to indicate requirement levels [RFC2119]. RFC-2119 keywords are formatted in uppercase and contained in a strong
element with class="rfc2119"
. When the keywords shown above are used, but do not share this format, they do not convey formal information in the RFC 2119 sense, and are merely explanatory, i.e., informative. As much as possible, such usages are avoided in this specification.
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.
This section is normative.
While some terms are defined in place, the following definitions are used throughout this document.
Operating systems and other platforms provide a set of interfaces that expose information about objects and events to assistive technologies. Assistive technologies use these interfaces to get information about and interact with those widgets. Examples of accessibility APIs are Microsoft Active Accessibility [MSAA], Microsoft User Interface Automation [UI-AUTOMATION], MSAA with UIA Express [UIA-EXPRESS], the Mac OS X Accessibility Protocol [AXAPI], the Linux/Unix Accessibility Toolkit [ATK] and Assistive Technology Service Provider Interface [AT-SPI], and IAccessible2 [IAccessible2].
Tree of accessible objects that represents the structure of the user interface (UI). Each node in the accessibility tree represents an element in the UI as exposed through the accessibility API; for example, a push button, a check box, or container.
An accessible description provides additional information, related to an interface element, that complements the accessible name. The accessible description might or might not be visually perceivable.
The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element. See related accessible description.
A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g., "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.
A node in the accessibility tree of a platform accessibility API. Accessible objects expose various states, properties, and events for use by assistive technologies. In the context of markup languages (e.g., HTML and SVG) in general, and of WAI-ARIA in particular, markup elements and their attributes are represented as accessible objects.
Hardware and/or software that:
This definition may differ from that used in other documents.
Examples of assistive technologies that are important in the context of this document include the following:
In this specification, attribute is used as it is in markup languages. Attributes are structural features added to elements to provide information about the states and properties of the object represented by the element.
A set of instance objects that share similar characteristics.
In this specification, element is used as it is in markup languages. Elements are the structural elements in markup language that contains the data profile for objects.
A programmatic message used to communicate discrete changes in the state of an object to other objects in a computational system. User input to a web page is commonly mediated through abstract events that describe the interaction and can provide notice of changes to the state of a document object. In some programming languages, events are more commonly known as notifications.
Indicates that the element is not visible, perceivable, or interactive to any user. An element is considered hidden if it or any one of its ancestor elements is not rendered or is explicitly hidden.
Content provided for information purposes and not required for conformance. Content required for conformance is referred to as normative.
Basic type of object in the DOM tree or accessibility tree. DOM nodes are further specified as Element or Text nodes, among other types. The nodes of an accessibility tree are accessible objects.
Required for conformance. By contrast, content identified as informative or "non-normative" is not required for conformance.
In the context of user interfaces, an item in the perceptual user experience, represented in markup languages by one or more elements, and rendered by user agents.
In the context of programming, the instantiation of one or more classes and interfaces which define the general characteristics of similar objects. An object in an accessibility API may represent one or more DOM objects. Accessibility APIs have defined interfaces that are distinct from DOM interfaces.Presentable to users in ways they can sense. References in this document relate to WCAG 2.0 Principle 1: Content must be perceivable [WCAG20].
Attributes that are essential to the nature of a given object, or that represent a data value associated with the object. A change of a property may significantly impact the meaning or presentation of an object. Certain properties (for example, aria-multiline) are less likely to change than states, but note that the frequency of change difference is not a rule. A few properties, such as aria-activedescendant, aria-valuenow, and aria-valuetext are expected to change often. See clarification of states versus properties.
Main indicator of type. This semantic association allows tools to present and support interaction with the object in a manner that is consistent with user expectations about other objects of that type.
The meaning of something as understood by a human, defined in a way that computers can process a representation of an object, such as elements and attributes, and reliably represent the object in a way that various humans will achieve a mutually consistent understanding of the object.
A state is a dynamic property expressing characteristics of an object that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities. See clarification of states versus properties.
Type of DOM node that represents the textual content of an attribute or an element. A Text node has no child nodes.
Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.
Discrete user interface object with which the user can interact. Widgets range from simple objects that have one value or operation (e.g., check boxes and menu items), to complex objects that contain many managed sub-objects (e.g., trees and grids).
This section is normative.
The starting point of the name and description computation is a DOM element. The output is a flat, unstructured string that can be as simple as a single word, or a string of space-separated tokens. Examples include Save
and Reload from disk
.
An important factor is the element's role, that determines which content contributes to the name string. Roles have a nameFrom
RDF property, with two possible values:
aria-label
and aria-labelledby
attribute, or a host language labeling mechanism, such as the alt
or title
attribute in HTML, or the desc
element in SVG. (Joseph) Need links into ARIA spec to (1) a list of nameFrom:author roles, and (2) a list of nameFrom:contents roles. Reference these at step 2F below.
User agents MUST compute an accessible name using the rules outlined below in the section titled Text Alternative Computation.
If aria-describedby
is present, user agents MUST compute the accessible description by concatenating the text alternatives for elements referenced by an aria-describedby
attribute on the current element. The text alternatives for the referenced elements are computed using a number of methods, outlined below in the section titled Text Alternative Computation.
The text alternative computation is used to generate both the accessible name and accessible description. There are different rules provided for several different types of elements, nodes, and combinations of markup. Text alternatives are built up, when appropriate, from all the relevant content contained within an element. This is accomplished via steps 2B and 2F, which are recursive, using the full set of rules to retrieve text from its own children or nodes it references.
The purpose of the computation is to create a perceivable label or description for alternative presentations, in the form of a flat string of space separated textual tokens.
root node
's text equivalent. Initially, the current node
is the root node
, but at later stages is either some descendant of the root node
, or another referenced node.current node
.result
to X.result
to the end of X.result
to X.result
to X after the space.result
to X.result
to the start of X.result
to X.result
to the start of X, and add a space after the copy.The text alternative for a given element is computed as follows:
root node
to the given element, the current node
to the root node
, and the total accumulated text
to the empty string ("").current node
:
current node
is hidden and is not referenced by aria-labelledby
or aria-describedby
, nor referenced by a native host language text alternative element or attribute, return the empty string.
current node
has a non-empty aria-labelledby
attribute, and the current node
is not already part of an aria-labelledby
traversal, process its IDREFs in the order they occur: current node
has a non-empty aria-describedby
attribute, and the current node
is not already part of an aria-describedby
traversal, process its IDREFs in the order they occur:
accumulated text
to the empty string.current node
to the node referenced by the IDREF.current node
beginning with step 2. Set the result
to that text alternative.result
, with a space, to the accumulated text
.accumulated text
.current node
has a non-empty aria-label
attribute:
current node
is due to recursion and the current node
is an embedded control as defined in step 2E, ignore aria-label
and skip to rule 2E.aria-label
.current node
's native markup provides an attribute or element that defines a text alternative, return that alternative as a flat string
, unless the element is marked as presentational (role="presentation"
or role="none"
).
Above wording taken from second note in ISSUE-522.
current node
is a control embedded within the label of another widget, where the user can adjust the embedded control's value, then include the embedded control as part of the text alternative in the following manner:
aria-valuetext
property is present, return its value, aria-valuenow
property is present, return its value,current node's
role allows "Name From: contents", or if the current node
is referenced by aria-labelledby
, aria-describedby
, or is a native host language text alternative element:
accumulated text
to the empty string.current node
and include it in the accumulated text
:
list-style-type
is not "none"
, user agents MUST prepend the list item indicator text to the item's text. If the list item indicator text includes a space, prepend the indicator text without a space; otherwise prepend with a space.:before
and :after
pseudo elements can provide textual content for elements that have a content model.
:before
pseudo elements, User agents MUST prepend CSS textual content, without a space, to the textual content of the current node
. :after
pseudo elements, User agents MUST append CSS textual content, without a space, to the textual content of the current node
. current node
:
current node
to the child node.current node
beginning with step 2. Set the result
to that text alternative.result
to the accumulated text
. (Joseph) the last step above needs work since there are cases where you "append with a space" and others where you "append without a space". Example of the latter: <label> <input type="checkbox"> Make this the <em>top</em>most element</label>
. The result is "Make this the topmost element", not "Make this the top most element" – do not append a space after "top".
accumulated text
.Important: Each node in the subtree is consulted only once. If text has been collected from a descendant, but is referenced by another IDREF in some descendant node, then that second, or subsequent, reference is not followed. This is done to avoid infinite loops.
current node
is a Text node, return its textual contents.current node
has a tooltip attribute, return its value.
Append the result
of each step above, with a space, to the total accumulated text
.
After all steps are completed, the total accumulated text
is used as the accessible name or accessible description of the element that initiated the computation.
Each step of the algorithm generates a flat text string
. An implementation trims the text and concatenates it with the text alternative computed by previous steps. The result is a single flat string name or description associated with the element for which the text alternative computation was executed. The computed string is used to set the accessible name or accessible description property of the accessible object corresponding to the element. The specifics of each accessibility API mapping is given in the following table.
Accessibility API Property | MSAA + IAccessible2 | UIA | ATK/AT-SPI | AXAPI |
---|---|---|---|---|
accessible name |
Expose in accName property.
|
Expose in Name property.
|
Expose in the name property of the accessible object.
|
Expose as string AXTitle , AXDescription , or AXTitleUIElement :
|
accessible description |
Expose in accDescription property.
|
TBD.
(See ACTION-1104) |
Expose in the description property of the accessible object.
|
Expose as string AXHelp . |
More information concerning name and description accessibility API mappings, including relationships, such as labelled-by/label-for and described-by/description-for, is documented in the Core Accessibility API Mappings document [CORE-AAM]. See the mapping table entries for aria-label
, aria-labelledby
, and aria-describedby
.
(Joseph) Certain Accessibility APIs emit events for name and/or description property changes. Document that here (see, for example, FF bugzilla 991969).
Although rare, sometimes an accessible name or accessible description may change. Examples include:
The following table lists the events or notifications provided by Accessibility APIs if the name or description changes. Assistive technologies can make use of these events to provide the current label as needed.
Accessibility API Property | MSAA + IAccessible2 | UIA | ATK/AT-SPI | AXAPI |
---|---|---|---|---|
accessible name |
EVENT_OBJECT_NAMECHANGE |
PropertyChangeEvent |
object:property-change:accessible-name |
TitleChangedNotification |
accessible description |
EVENT_OBJECT_DESCRIPTIONCHANGE |
PropertyChangeEvent |
object:property-change:accessible-description |
TBD. |
<img>
to HTML-AAM.This section is non-normative.
The following people contributed to the development of this document.
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.