The accessible name and description computation specification defines support that applies across multiple content technologies. This includes accessible name and description provided by general-purposeWAI-ARIA [WAI-ARIA]roles,states, andproperties as well as features specific to individual content languages.
Publication as an Editor's Draft does not imply endorsement byW3C 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.
User agents acquire information from theDOM [DOM] and create a parallel structure called theaccessibility tree, made up ofaccessible objects. An accessible object provides information about itsrole,states, andproperties. An example is an accessible object whose role ismenuitem, is currently in anenabled state, with ahaspopup property, indicating that it leads to a sub-menu.
The two properties of accessible objects described in this document are itsaccessible name andaccessible 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 isNew, 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.
AccessibilityAPIs 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 ofaccessible objects as exposed byAccessibilityAPIs. However, they are frequently referred to hereafter as simply "name" and "description".
2.Important Terms
This section is non-normative.
While some terms are defined in place, the following definitions are used throughout this document.
Assistive Technologies
Hardware and/or software that:
relies on services provided by auser agent to retrieve and render Web content
works with a user agent or web content itself through the use ofAPIs, and
provides services beyond those offered by the user agent to facilitate user interaction with web content by people with disabilities
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:
screen magnifiers, which are used to enlarge and improve the visual readability of rendered text and images;
screen readers, which are most-often used to convey information through synthesized speech or a refreshable Braille display;
text-to-speech software, which is used to convert text into synthetic speech;
speech recognition software, which is used to allow spoken control and dictation;
alternate input technologies (including head pointers, on-screen keyboards, single switches, and sip/puff devices), which are used to simulate the keyboard;
alternate pointing devices, which are used to simulate mouse pointing and clicking.
Accessible Description
An accessible description provides additional information, related to an interface element, that complements theaccessible name. The accessible description might or might not be visually perceivable.
Accessible Name
The accessible name is the name of a user interface element. Each platformaccessibilityAPI 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 relatedaccessible 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 platformaccessibilityAPIs orassistive technologies.
Tooltip attribute
Any host language attribute that would result in a user agent generating a tooltip such as in response to a mouse hover in desktop user agents.
3.Conformance
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 wordsMAY,MUST, andMUST NOT in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Normative sections provide requirements that authors, user agents and assistive technologiesMUST 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.
4.Name and Description
The starting point of the name and description computation is aDOMelement. The output is a flat, unstructured string that can be as simple as a single word, or a string of space-separated tokens. Examples includeSave andReload from disk.
name is generated from values provided by the author in explicit markup features such as thearia-label andaria-labelledbyattribute, or a host language labeling mechanism, such as thealt ortitleattribute inHTML, or thedescelement inSVG.
contents
name is generated from thetext nodes associated with theelement. Although this may be allowed in addition to "author" in someroles, "content" is used only if higher priority "author" features are not provided. Priority is defined by thetext equivalent computation algorithm.
prohibited
the element has no name. AuthorsMUST NOT use thearia-label oraria-labelledby attributes to name the element.
The following table provides the order of precedence for markup that can be applied to compute anaccessible description.User agentsMUST use the first applicable entry from the table where the listed conditions are met, as described in the last column. The user agentMUST NOT use any markup other that the first relevant markup found, even if that markup results in an empty description:
Either atext equivalent computation of the host language element, or the string value of the host language attribute.
4
host language tooltip attribute or equivalent feature (e.g.,HTMLtitle attribute)
Any element
Only use if not already used for the accessible name of this node
As a flat string
4.3Text Equivalent Computation
The text equivalent computation is used by both theaccessible name andaccessible description. There are different rules provided for several different types ofelements,nodes, and combinations of markup. Text alternatives are built up, when appropriate, from all the relevant content contained within anelement. 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 aperceivable label or description for alternative presentations, in the form of a flat string of space separated textual tokens.
4.3.1Terminology
Root node
TheDOMnode orelement for which the text alternative is sought.
Current node
TheDOMnode currently traversed to compute theroot node's text equivalent. Initially, thecurrent node is theroot node, but at later stages is either some descendant of theroot node, or another referenced node.
Rendered child nodes
Thenodes that are rendered as child nodes of a given node when takingshadow roots andslots into consideration.
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 thecurrent 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 theresult to X.
If X is non-empty, copy theresult to the end of X.
Append the result, with a space, to X
If X is empty, copy theresult to X.
If X is non-empty, add a space to the end of X and then copy theresult to X after the space.
Prepend result, without a space, to X
If X is empty, copy theresult to X.
If X is non-empty, copy theresult to the start of X.
Prepend the result, with a space, to X
If X is empty, copy theresult to X.
If X is non-empty, copy theresult to the start of X, and add a space after the copy.
4.3.2Computation steps
The text alternative for a given element is computed as follows:
Initialization: Set theroot node to the given element, thecurrent node to theroot node, and thetotal accumulated text to the empty string (""). If theroot node's role prohibits naming, return the empty string ("").
Computation: Compute the text alternative for thecurrent node:
Hidden Not Referenced: If thecurrent node ishiddenand is:
Not part of anaria-labelledby oraria-describedby traversal, where the node directly referenced by that relation was hidden.
Nor part of a native host language text alternativeelement (e.g.label inHTML) orattribute traversal, where the root of that traversal was hidden.
Return the empty string.
Note
It's important to clarify the broad definition of hidden for the purposes of accessible name calculation:
Nodes with thearia-hidden="true" property: it is considered hidden, matching the "explicitly hidden" guideline.
Nodes hidden off screen or behind another object: they are not considered hidden. They are exposed in the accessibility tree and they can even name on-screen objects.
The following examples show the meaning of the clause "Not part of anaria-labelledby oraria-describedby traversal, where the node directy referenced by that relation was hidden.".
First,element1'saccessible name is "hello" because, althoughelement3 is hidden, it is part of anaria-labelledby traversal started inelement2, which is hidden too.
Conversely,element1 has noaccessible name ifelement3 is hidden and it is part of anaria-labelledby traversal started inelement2, butelement2 is not hidden.
LabelledBy: Otherwise, if thecurrent node has anaria-labelledbyattribute that contains at least one valid IDREF, and thecurrent node is not already part of an ongoingaria-labelledby oraria-describedby traversal, process its IDREFs in the order they occur:
Set theaccumulated text to the empty string.
For each IDREF:
Set thecurrent node to the node referenced by the IDREF.
LabelledBy Traversal: Compute the text alternative of thecurrent node beginning with the overallComputation step. Set theresult to that text alternative.
Append a space character and theresult to theaccumulated text.
Return theaccumulated text if it is not the empty string ("").
The following example shows the meaning of the clause "… and thecurrent node is not already part of anaria-labelledby traversal …" .
element1'saccessible name is "hello" because this is a first traversal of itsaria-labelledby, leading toelement3.
element2 has noaccessible name. The computation involves a first traversal of itsaria-labelledby leading toelement1, butelement1'saria-labelledby is not subsequently followed.
Embedded Control: Otherwise, if thecurrent node is a control embedded within the label (e.g. any element directly referenced byaria-labelledby) for anotherwidget, where the user can adjust the embedded control's value, then return the embedded control as part of the text alternative in the following manner:
Textbox: If the embedded control has roletextbox, return its value.
Combobox/Listbox: If the embedded control has rolecombobox orlistbox, return the text alternative of the chosenoption.
Consider acheck box label that contains a text input field: "Flash the screen [input] times". If the input field has the value "5", the complete label is "Flash the screen 5 times", e.g.:
<label for="flash"> <input type="checkbox" id="flash"> Flash the screen <span tabindex="0" role="textbox" aria-label="number of times" contenteditable>5</span> times.</label>
AriaLabel: Otherwise, if thecurrent node is not aslot element and has anaria-labelattribute whose value is not undefined, not the empty string, nor, when trimmed ofwhitespace, is not the empty string:
The following example shows the interaction ofaria-labelledby andaria-label when anode has anaria-labelledby that refers to itself. The<span role="button"> elements have theaccessible names "Delete Documentation.pdf" and "Delete HolidayLetter.pdf", respectively.
Determine Child Nodes: Determine therendered child nodes of thecurrent node:
If thecurrent node has an attachedshadow root, set therendered child nodes to be the child nodes of theshadow root.
Otherwise, if thecurrent node is aslot withassigned nodes, set therendered child nodes to be theassigned nodes of thecurrent node.
Otherwise, set therendered child nodes to be the child nodes of thecurrent node.
Name From Each Child: For eachrendered child node of thecurrent node:
Set thecurrent node to therendered child node.
Compute the text alternative of thecurrent node beginning with the overallComputation step. Set theresult to that text alternative.
Append theresult to theaccumulated text.
Return theaccumulated text if it is not the empty string ("").
Important: Eachnode 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.
Note
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 thecurrent node's subtree, no matter how deep it is. However, any given descendantnode'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.
27-June-2019: Add statement allowing for the possibility of naming being prohibited on the root node. Note: This change in and of itself has no implementation impact, but it allows other specifications to optionally prohibit naming for a top-level element. Furthermore, even if this prohibition is made within a specification, that prohibition will not have any impact on calculating name from contents.
6.2Acknowledgments
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, then under contract number HHSP23301500054C, and now under HHS75P00120P00168. 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.