Skip to content

Add aria-description #1137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 21 commits into from
Jan 16, 2020
Merged

Add aria-description #1137

Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ae5906a
Add aria-description
Dec 11, 2019
277ce84
Update index.html
aleventhal Dec 20, 2019
fef0cff
Clarify
Dec 20, 2019
b2701ce
Merge branch 'aria_description_issue_891' of github.com:w3c/aria into…
Dec 20, 2019
fb818b3
Add aria-description
Dec 11, 2019
f64925b
Clarify
Dec 20, 2019
0e3cd23
Update index.html
aleventhal Dec 20, 2019
12114e1
Add precedence info
Jan 6, 2020
00fba29
Say DOM
Jan 6, 2020
2156d9e
Fix conflict
Jan 6, 2020
2c88718
Remove confusing info about hidden description in DOM, since it isn't…
Jan 7, 2020
7d68704
Update index.html
aleventhal Jan 9, 2020
c7113b6
Use word visible
Jan 9, 2020
c269817
Merge branch 'aria_description_issue_891' of github.com:w3c/aria into…
Jan 9, 2020
1a4eb7d
Update index.html
aleventhal Jan 9, 2020
a8cd90a
Improvements from carmacleod
Jan 10, 2020
a9fad19
Update index.html
aleventhal Jan 10, 2020
e94818b
Correctly alphabetized
Jan 14, 2020
94082f5
Correctly alphabetized
Jan 14, 2020
1dd399a
Merge branch 'aria_description_issue_891' of github.com:w3c/aria into…
Jan 14, 2020
73f119d
Add related info to aria-describedby
jnurthen Jan 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 48 additions & 5 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10672,8 +10672,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>
Expand Down Expand Up @@ -10711,7 +10711,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>
Expand Down Expand Up @@ -11375,7 +11415,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>
Expand All @@ -11395,7 +11435,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>
Expand Down Expand Up @@ -12898,6 +12938,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>
Expand Down Expand Up @@ -13125,6 +13166,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;
Expand Down Expand Up @@ -13181,6 +13223,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>
Expand Down