Name Computation

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

Editorial Note (Joseph): The following special case is specific to HTML, and should be moved elsewhere.

Special Case: If the element is an img element that is exposed in the accessibility tree; and the computed text alternative is empty, then check for the presence of role presentation or any labeling attribute that specifies an empty label, specifically aria-label, aria-labelledby, alt or title. The presence of any of these indicates the author's intention to indicate that the img is decorative or redundant. In this case, the user agent MUST set the name to an empty string. If none of these attributes are present, this indicates the author simply did not provide an accessible label for the image, and the implementation MUST return an accessible name of NULL instead of an empty string if the API supports it. This hints to the assistive technology to do its own heuristic processing to repair the missing accessible name.

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.

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

      Editorial note: (Joseph) Need to address aria-describedby here, using the the same loop mechanism to process the referenced nodes except where the current node is already part of an aria-describedby traversal.

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

      Editorial Note: (Joseph) Pro: the example shows the interaction of aria-labelledby and aria-label when on the same element. Con: it uses HTML.

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

      Editorial note: 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 value of 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":
      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.

         Editorial Note: (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.

      Editorial Note: (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.