Add aria-description (#1137)

* Add aria-description
Co-Authored-By: Diane Ko <[email protected]>
Co-Authored-By: Carolyn MacLeod <[email protected]>

Author: 3 people

index.html

@@ -10761,8 +10761,8 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
 		<div class="property" id="aria-describedby">
 			<pdef>aria-describedby</pdef>
 			<div class="property-description">
-				<p>Identifies the <a>element</a> (or elements) that describes the <a>object</a>. See related <pref>aria-labelledby</pref>.</p>
-				<p>The <pref>aria-labelledby</pref> attribute is similar to the <pref>aria-describedby</pref> in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.</p>
+				<p>Identifies the <a>element</a> (or elements) that describes the <a>object</a>. See related <pref>aria-labelledby</pref> and <pref>aria-description</pref>.</p>
+				<p>The <pref>aria-labelledby</pref> attribute is similar to <pref>aria-describedby</pref> in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.</p>
 				<!-- keep previous sentence synced with the associated description in #aria-labelledby -->
 				<p>The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID.</p>
 			</div>
@@ -10800,7 +10800,47 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
 				</tbody>
 			</table>
 		</div>
-                <div class="property" id="aria-details">
+		<div class="property" id="aria-description">
+			<pdef>aria-description</pdef>
+			<div class="property-description">
+				<p>Defines a string value that describes or annotates the current element. See related <pref>aria-describedby</pref>.</p>
+				<p>The <pref>aria-description</pref> attribute is similar to <pref>aria-label</pref> in that both provide a flat string to associate with the element, but a label should be concise, whereas a description is intended to provide more verbose information.</p>
+				<p>The purpose of <pref>aria-description</pref> is the same as that of <pref>aria-describedby</pref>. It provides the user with additional descriptive text for the object. The most common <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a> mapping for a description is the <a>accessible description</a> property. User agents MUST give precedence to <pref>aria-describedby</pref> over <pref>aria-description</pref> when computing the accessible description property.</p>
+				<p>In cases where providing a visible description is not the desired user experience, authors MAY set the accessible description of the element using <pref>aria-description</pref>. However, if the description text is available in the DOM, authors SHOULD NOT use <pref>aria-description</pref>, but should use one of the following instead:</p>
+				<ul>
+					<li>Authors SHOULD use <pref>aria-describedby</pref> when the related description or annotation elements contain a simple, small description that is best experienced as a flat string, rather than by having the user navigate to them.</li>
+					<li>Authors SHOULD use <pref>aria-details</pref> when the related description or annotation elements contain useful semantics or structure, or there is a lot of content within them, making it difficult to experience as a flat string. Using <pref>aria-details</pref> will allow assistive technology users to visit the structured content and provide additional navigation commands, making it easier to understand the structure, or to experience the information in smaller pieces.</li>
+				</ul>
+			</div>
+			<table class="property-features">
+				<caption>Characteristics:</caption>
+				<thead>
+					<tr>
+						<th scope="col">Characteristic</th>
+						<th scope="col">Value</th>
+					</tr>
+				</thead>
+				<tbody>
+					<tr>
+						<th class="property-related-head" scope="row">Related Concepts:</th>
+						<td class="property-related"><code>title</code> attribute in [[HTML]]</td>
+					</tr>
+					<tr>
+						<th class="property-applicability-head" scope="row">Used in Roles:</th>
+						<td class="property-applicability">All elements of the base markup except for some roles or elements that prohibit its use</td>
+					</tr>
+					<tr>
+						<th class="property-descendants-head" scope="row">Inherits into Roles:</th>
+						<td class="property-descendants">Placeholder</td>
+					</tr>
+					<tr>
+						<th class="property-value-head" scope="row">Value:</th>
+						<td class="property-value"><a href="#valuetype_string">string</a></td>
+					</tr>
+				</tbody>
+			</table>
+		</div>
+		<div class="property" id="aria-details">
 			<pdef>aria-details</pdef>
 			<div class="property-description">
 				<p>Identifies the <a>element</a> that provides a detailed, extended description for the <a>object</a>. See related <pref>aria-describedby</pref>.</p>
@@ -11464,7 +11504,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
 				<tbody>
 					<tr>
 						<th class="property-related-head" scope="row">Related Concepts:</th>
-						<td class="property-related"><code>title</code> attribute in [[HTML]]</td>
+						<td class="property-related"> </td>
 					</tr>
 					<tr>
 						<th class="property-applicability-head" scope="row">Used in Roles:</th>
@@ -11484,7 +11524,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
 		<div class="property" id="aria-labelledby">
 			<pdef>aria-labelledby</pdef>
 			<div class="property-description">
-				<p>Identifies the <a>element</a> (or elements) that labels the current element. See related <pref>aria-describedby</pref>.</p>
+				<p>Identifies the <a>element</a> (or elements) that labels the current element. See related <pref>aria-label</pref> and <pref>aria-describedby</pref>.</p>
 				<p>The purpose of <pref>aria-labelledby</pref> is the same as that of <pref>aria-label</pref>. It provides the user with a recognizable name of the object. The most common <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a> mapping for a label is the <a>accessible name</a> property.</p>
 				<p>If the interface is such that it is not possible to have a visible label on the screen, authors SHOULD use <pref>aria-label</pref> and SHOULD NOT use <pref>aria-labelledby</pref>. As required by the <a href="#textalternativecomputation">accessible name and description computation</a>, user agents give precedence to <pref>aria-labelledby</pref> over <pref>aria-label</pref> when computing the accessible name property.</p>
 				<p>The <pref>aria-labelledby</pref> attribute is similar to <pref>aria-describedby</pref> in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.</p>
@@ -12987,6 +13027,7 @@ <h2>Conflicts with Host Language Semantics</h2>
 		<p>Certain ARIA features are critical to building a complete model in the accessibility API. Such features are not expected to conflict with native host language semantics (though they may complement them). Therefore, host languages MUST NOT declare strong native semantics that prevent use of the following ARIA features:</p>
 		<ul>
 			<li><pref>aria-describedby</pref></li>
+			<li><pref>aria-description</pref></li>
 			<li><pref>aria-label</pref></li>
 			<li><pref>aria-labelledby</pref></li>
 		</ul>
@@ -13214,6 +13255,7 @@ <h2>Interface Mixin <dfn>AriaAttributes</dfn></h2>
 				attribute FrozenArray&lt;Element&gt;? ariaControlsElements;
 				attribute DOMString? ariaCurrent;
 				attribute FrozenArray&lt;Element&gt;? ariaDescribedByElements;
+				attribute DOMString? ariaDescription;
 				attribute Element? ariaDetailsElement;
 				attribute DOMString? ariaDisabled;
 				attribute Element? ariaErrorMessageElement;
@@ -13270,6 +13312,7 @@ <h2>ARIA Attribute Reflection</h2>
 				<tr><td><dfn>ariaControlsElements</dfn></td><td><pref>aria-controls</pref></td></tr>
 				<tr><td><dfn>ariaCurrent</dfn></td><td><sref>aria-current</sref></td></tr>
 				<tr><td><dfn>ariaDescribedByElements</dfn></td><td><pref>aria-describedby</pref></td></tr>
+				<tr><td><dfn>ariaDescription</dfn></td><td><pref>aria-description</pref></td></tr>
 				<tr><td><dfn>ariaDetailsElement</dfn></td><td><pref>aria-details</pref></td></tr>
 				<tr><td><dfn>ariaDisabled</dfn></td><td><sref>aria-disabled</sref></td></tr>
 				<tr><td><dfn>ariaErrorMessageElement</dfn></td><td><pref>aria-errormessage</pref></td></tr>