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.

Introduction

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

Normative User Agent Implementation Requirements for WAI-ARIA

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.

Important Terms

This section is normative.

Name and Description

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:

author
name is generated from values provided by the author in explicit markup features such as the 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.
contents
name is generated from the Text nodes associated with the element. Although this may be allowed in addition to "author" in some roles, "content" is used only if higher priority "author" features are not provided. Priority is defined by the text alternative computation algorithm.

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

Name Computation

User agents MUST compute an accessible name using the rules outlined below in the section titled Text Alternative Computation.

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

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.

Terminology

Root node
The DOM node or element for which the text alternative is sought.
Current node
The DOM node currently traversed to compute the 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.
Flat string
A string of characters where all carriage returns, newlines, tabs, and form-feeds are replaced with a single space, and multiple spaces are reduced to a single space. The string contains only character data; it does not contain any markup.
Total Accumulated text
The text equivalent computed up to, but not including the current node.
Accumulated text
Text accumulated at a step or sequence of steps described below. It is temporary storage for those steps.
Result
The text equivalent computed at one of the steps described below.
Append the result, without a space, to X
  • If X is empty, copy the result to X.
  • If X is non-empty, copy the result to the end of X.
Append the result, with a space, to X
  • If X is empty, copy the result to X.
  • If X is non-empty, add a space to the end of X and then copy the result to X after the space.
Prepend result, without a space, to X
  • If X is empty, copy the result to X.
  • If X is non-empty, copy the result to the start of X.
Prepend the result, with a space, to X
  • If X is empty, copy the result to X.
  • If X is non-empty, copy the result to the start of X, and add a space after the copy.

The text alternative for a given element is computed as follows:

  1. Initialize: Set the root node to the given element, the current node to the root node, and the total accumulated text to the empty string ("").
  2. Compute the text alternative for the current node:
    1. If the 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.
      Comment:

      By default, assistive technologies do not relay hidden information, but an author can explicitly override that and include hidden text as part of the accessible name or accessible description by using aria-labelledby or aria-describedby.

    2. Otherwise:
      • if computing a name, and the 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:
      • or, if computing a description, and the 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:
        1. Set the accumulated text to the empty string.
        2. For each IDREF:
          1. Set the current node to the node referenced by the IDREF.
          2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
          3. Append the result, with a space, to the accumulated text.
        3. Return the accumulated text.
      Example:

      The following example shows the meaning of the clause "… and the current node is not already part of an aria-labelledby traversal …" .

      • element1's accessible name is "hello" because this is a first traversal of its aria-labelledby, leading to element3.
      • element2 has no accessible name. The computation involves a first traversal of its aria-labelledby leading to element1, but element1's aria-labelledby is not subsequently followed.
      <element1 id="el1" aria-labelledby="el3" />
      <element2 id="el2" aria-labelledby="el1" />
      <element3 id="el3"> hello </element3>
                      
    3. Otherwise, if computing a name, and if the current node has a non-empty aria-label attribute:
      • If traversal of the 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.
      • Otherwise, return the value of aria-label.
      Example:

      The following example shows the interaction of aria-labelledby and aria-label when a node has an aria-labelledby that refers to itself. The <span role="button"> elements have the accessible names "Delete Documentation.pdf" and "Delete HolidayLetter.pdf", respectively.

      <h1>Files</h1>
      <ul>
        <li>
          <a id="file_row1" href="./files/Documentation.pdf">Documentation.pdf</a>
          <span role="button" tabindex="0" id="del_row1" aria-label="Delete" aria-labelledby="del_row1 file_row1"></span>
        </li>
        <li>
          <a id="file_row2" href="./files/HolidayLetter.pdf">HolidayLetter.pdf</a>
          <span role="button" tabindex="0" id="del_row2" aria-label="Delete" aria-labelledby="del_row2 file_row2"></span>
        </li>
      </ul>
    4. Otherwise, if the 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.

      Comment:

      For example, in HTML, the img element's alt attribute defines a text alternative string, and the label element provides text for the referenced form element. In SVG2, the desc and title elements provide a description of their parent element.

    5. Otherwise, if the 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:
      • If the embedded control has role textbox, return its value.
      • If the embedded control has role menu button, return the text alternative of the button.
      • If the embedded control has role combobox, return the text alternative of the chosen option.
      • If the embedded control has role range (e.g., a spinbutton or slider):
        • If the aria-valuetext property is present, return its value,
        • Otherwise, if the aria-valuenow property is present, return its value,
        • Otherwise, use the value as specified by a host language attribute.
      Example:

      Consider a check box label that contains a text input field: "Flash the screen [input] times". If the user has entered "5" for the embedded textbox, the complete label is "Flash the screen 5 times", e.g.:

      <div role="checkbox" aria-checked="false">Flash the screen <span role="textbox" aria-multiline="false"> 5 </span> times</div>
    6. Otherwise, if the 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:
      1. Set the accumulated text to the empty string.
      2. Check for CSS generated textual content associated with the current node and include it in the accumulated text:
        • The "bullet" or "number" characters associated with a list item are not present in the DOM, but are provided by the user agent's style engine. If the CSS 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.
        • Similarly, the CSS :before and :after pseudo elements can provide textual content for elements that have a content model.
          • For :before pseudo elements, User agents MUST prepend CSS textual content, without a space, to the textual content of the current node.
          • For :after pseudo elements, User agents MUST append CSS textual content, without a space, to the textual content of the current node.
      3. For each child node of the current node:
        1. Set the current node to the child node.
        2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
        3. Append the 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".

      4. Return the 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.

      Comment:

      This step can apply to the child nodes themselves, which means the computation is recursive and results in text collected from all the elements in the current node's subtree, no matter how deep it is. However, any given descendant node's text alternative can result from higher precedent markup described in steps B through D above, where "Namefrom: author" attributes provide the text alternative for the entire subtree.

    7. Otherwise, if the current node is a Text node, return its textual contents.
    8. Otherwise, if the current node has a tooltip attribute, return its value.
      Comment:

      Tooltip attributes are used only if nothing else, including subtree content, has provided results.

      (Joseph) Define "tooltip attribute"?

    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.

Accessible Name and Description Mapping

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.

Accessible name and accessible description mapping table
Accessibility API Property MSAA + IAccessible2 UIA ATK/AT-SPI AXAPI
accessible name Expose in accName property.

aria-labelledby: If the referenced objects are in the accessibility tree expose pointers to them using IA2_RELATION_LABELLED_BY, and expose reverse relations as described in Relations.

Expose in Name property.

aria-labelledby: If the referenced objects are in the accessibility tree, expose pointers to them using the LabeledBy property.

Expose in the name property of the accessible object.

aria-labelledby: If the referenced objects are in the accessibility tree, expose pointers to them using RELATION_LABELLED_BY, and expose reverse relations as described in Relations.

Expose as string AXTitle, AXDescription, or AXTitleUIElement:
  • Accessible name values that are exposed visually, as in the case of a button, should be exposed as string AXTitle.
  • AXDescription is recommended for accessible name values that are not exposed visually, such as @alt and @aria-label.

aria-labelledby:

  • If aria-labelledby references a single element, expose the labeling relationship as element AXTitleUIElement.
  • If aria-labelledby references multiple elements, or if the labeling element is invisible or otherwise not exposed in the accessibility tree, expose as string AXDescription.
accessible description Expose in accDescription property.

aria-describedby: If the referenced objects are in the accessibility tree, expose pointers to them using IA2_RELATION_DESCRIBED_BY, and expose reverse relations as described in Relations.

TBD.

aria-describedby: If the referenced objects are in the accessibility tree, expose pointers to the referenced accessible objects using the DescribedBy property.

(See ACTION-1104)

Expose in the description property of the accessible object.

aria-describedby: If the referenced objects are in the accessibility tree, expose reverse relations as described in Relations.

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.

Name and Description Change Events

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

Table of events fired in each API for changes in name or desription property.
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.

Appendices

Change Log

Substantive changes since the last public working draft

  • 05-Nov-2015: Removed all MSAA+UIA Express mappings.
  • 10-Jun-2015: Moved special case of unlabeled <img> to HTML-AAM.
  • 05-Jan-2015: Glossary entry for "value" removed; removed links to that entry.