This document describes how user agents determine the names and descriptions of accessible objects from web content languages. This information is in turn exposed through accessibility APIs so that assistive technologies can identify these objects and present their names or descriptions to users. Documenting the algorithm through which names and descriptions are to be determined promotes interoperable exposure of these properties among different accessibility APIs and helps to ensure that this information appears in a manner consistent with author intent.
The accessible name and description computation 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.
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 is a Candidate Recommendation of Accessible Name and Description Computation 1.1 by the Accessible Rich Internet Applications Working Group. This is a call for implementations; the Accessible Rich Internet Applications Working Group requests that implementations be submitted by 17 July 2018. The Working Group targets 17 July 2018 to complete the testing process and produce the implementation report. The Working Group plans to advance past Candidate Recommendation when the Candidate Recommendation Exit Criteria have been met.
The Accessible Rich Internet Applications Working Group primarily seeks feedback in relation to implementation of AccName, but feedback on any aspect of the specification is accepted. When submitting feedback, please consider issues in the context of the companion documents. To comment, file an issue in the W3C accname GitHub repository. If this is not feasible, send email to public-aria@w3.org (comment archive). Comments are requested by 17 July 2018. In-progress updates to the document may be viewed in the publicly visible editors' draft.
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".
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.
The indication whether a section is normative or non-normative (informative) applies to the entire section including sub-sections.
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.
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]].
An accessible object in the accessibility tree and its descendants in that tree. It does not include objects which have relationships other than parent-child in that tree. For example, it does not include objects linked via aria-flowto unless those objects are also descendants in the accessibility tree.
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.
The action taken when an event, typically initiated by users through an input device, causes an element to fulfill a defined role. The role may be defined for that element by the host language, or by author-defined variables, or both. The role for any given element may be a generic action, or may be unique to that element. For example, the activation behavior of an HTML or SVG <a> element shall be to cause the user agent to traverse the link specified in the href attribute, with the further optional parameter of specifying the browsing context for the traversal (such as the current window or tab, a named window, or a new window); the activation behavior of an HTML <input> element with the type attribute value submit shall be to send the values of the form elements to an author-defined IRI by the author-defined HTTP method.
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.
A deprecated role, state, or property is one which has been outdated by newer constructs or changed circumstances, and which may be removed in future versions of the WAI-ARIA specification. User agents are encouraged to continue to support items identified as deprecated for backward compatibility. For more information, see Deprecated Requirements in the Conformance section.
Event from/to the host operating system via the accessibility API, notifying of a change of input focus.
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.
Translated to platform-specific accessibility APIs as defined in the Core Accessibility API Mappings. [[CORE-AAM-1.1]]
A document containing graphic representations with user-navigable parts. Charts, maps, diagrams, blueprints, and dashboards are examples of graphical documents. A graphical document is composed using any combination of symbols, images, text, and graphic primitives (shapes such as circles, points, lines, paths, rectangles, etc).
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.
Accessible to the user using a keyboard or assistive technologies that mimic keyboard input, such as a sip and puff tube. References in this document relate to WCAG 2.1 Guideline 2.1: Make all functionality available from a keyboard [[WCAG21]].
A type of region on a page to which the user may want quick access. Content in such a region is different from that of other regions on the page and relevant to a specific user purpose, such as navigating, searching, perusing the primary content, etc.
Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere. These regions are not always updated as a result of a user interaction. This practice has become commonplace with the growing use of Ajax. Examples of live regions include a chat log, stock ticker, or a sport scoring section that updates periodically to reflect game statistics. Since these asynchronous areas are expected to update outside the user's area of focus, assistive technologies such as screen readers have either been unaware of their existence or unable to process them for the user. WAI-ARIA has provided a collection of properties that allow the author to identify these live regions and process them: aria-live, aria-relevant, aria-atomic, and aria-busy.
An implementing host language's primary content element, such as the body element in HTML.
Accessibility API state that is controlled by the user agent, such as focus and selection. These are contrasted with "unmanaged states" that are typically controlled by the author. Nevertheless, authors can override some managed states, such as aria-posinset and aria-setsize. Many managed states have corresponding CSS pseudo-classes, such as :focus, and pseudo-elements, such as ::selection, that are also updated by the user agent.
The Nemeth Braille Code for Mathematics is a braille code for encoding mathematical and scientific notation. See Nemeth Braille on Wikipedia.
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.A description of the characteristics of classes and how they relate to each other.
Usable by users in ways they can control. References in this document relate to WCAG 2.1 Principle 2: Content must be operable [[WCAG21]]. See Keyboard Accessible.
An 'owned element' is any DOM descendant of the element, any element specified as a child via aria-owns, or any DOM descendant of the owned child.
An 'owning element' is any DOM ancestor of the element, or any element with an aria-owns attribute which references the ID of the element.
Presentable to users in ways they can sense. References in this document relate to WCAG 2.1 Principle 1: Content must be perceivable [[WCAG21]].
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.
A connection between two distinct things. Relationships may be of various types to indicate which object labels another, controls another, etc.
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 primary element containing non-metadata content. In many languages, this is the document element but in HTML, it is the <body>.
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.
Any document created from a <frame>, <iframe> or similar mechanism. A sub-document may contain a document, an application or any widget such as a calendar pulled in from another server. In the accessibility tree there are two accessible objects for this situation—one represents the <frame>/<iframe> element in the parent document, which parents a single accessible object child representing the spawned document contents.
An element specified in a WAI-ARIA relation. For example, in <div aria-controls=”elem1”>, where “elem1” is the ID for the target element.
A hierarchical definition of how the characteristics of various classes relate to each other, in which classes inherit the properties of superclasses in the hierarchy. A taxonomy can comprise part of the formal definition of an ontology.
Type of DOM node that represents the textual content of an attribute or an element. A Text node has no child nodes.
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.
Presentable to users in ways they can construct an appropriate meaning. References in this document relate to WCAG 2.1 Principle 3: Information and the operation of user interface must be understandable [[WCAG21]].
Any software that retrieves, renders and facilitates end user interaction with Web content. This definition may differ from that used in other documents.
A reference to a target element in the same document that has a matching ID
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).
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. The Accessible Rich Internet Applications (WAI-ARIA) 1.1 [[!WAI-ARIA]] specification provides lists of roles that support name from author and name from content.
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 directly referenced by aria-labelledby or aria-describedby, nor directly referenced by a native host language text alternative element (e.g. label in HTML) or attribute, return the empty string.
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.
current node has an aria-labelledby attribute that contains at least one valid IDREF, and the current node is not already part of an aria-labelledby traversal, process its IDREFs in the order they occur: current node has an aria-describedby attribute that contains at least one valid IDREF, 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.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>
current node has an aria-label attribute whose value is not the empty string, nor, when trimmed of white space, is not the empty string:
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.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>current node's native markup provides an attribute (e.g. title) or element (e.g. HTML label) that defines a text alternative, return that alternative in the form of a flat string as defined by the host language, unless the element is marked as presentational (role="presentation" or role="none").
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.
current node is a control embedded within the label (e.g. the label element in HTML or any element directly referenced by aria-labelledby) for 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,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>current node's role allows name from content, or if the current node is referenced by aria-labelledby, aria-describedby, or is a native host language text alternative element (e.g. label in HTML), or is a descendant of a native host language text alternative element:
accumulated text to the empty string.current node and include it in the accumulated text. The CSS :before and :after pseudo elements [[!CSS2]] 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. 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.
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.
current node is a Text node, return its textual contents.current node is a descendant of an element whose Accessible Name or Accessible Description is being computed, and contains descendants, proceed to 2F.i.
current node has a Tooltip attribute, return its value.
Tooltip attributes are used only if nothing else, including subtree content, has provided results.
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.
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 specification [[!CORE-AAM-1.1]]. See the mapping table entries for aria-label, aria-labelledby, and aria-describedby.
<img> to HTML-AAM.The Accessible Rich Internet Applications Working Group intends to exit the Candidate Recommendation stage and submit this document for consideration as a W3C Proposed Recommendation after documenting implementation of each feature. For each aspect of the name and description computation, at least two implementations will demonstrate implementability of that feature. Implementations consist of web browsers which expose the computed accessible name or description to accessibility APIs in a manner appropriate to the platform. Specific accessibility API mappings are not in scope of this specification; they are used only to evaluate the computed name and description. Documented implementation of AccName is in the implementation report.