Skip to content

Commit

Permalink
Editorial: clarify expectations for name/desc verbosity
Browse files Browse the repository at this point in the history
closes #1649 

These editorial changes attempt to clarify that a description _doesn't have to be verbose_.

It also adjusts some wording so when talking about an accessible name, the spec is saying that, and not using the term "label"

This update touches `aria-labelledby` and `aria-describedby` - because they share the same paragraph between the two.  It also touches `aria-description` which also was semi-reusing the paragraph that was repeated between `aria-labelledby` and `aria-describedby` - but it also needed a few wording changes.


Happy for others to add onto this or make further wording adjustments as need be.
  • Loading branch information
scottaohara authored Nov 24, 2021
1 parent fcea743 commit 0e28ff1
Showing 1 changed file with 3 additions and 3 deletions.
6 changes: 3 additions & 3 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -11217,7 +11217,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<pdef>aria-describedby</pdef>
<div class="property-description">
<p><a>Identifies</a> 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>
<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. While a concise accessible name is preferrable, a description can either be concise, or 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 @@ -11259,7 +11259,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<pdef>aria-description</pdef>
<div class="property-description">
<p><a>Defines</a> 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 <pref>aria-description</pref> attribute is similar to <pref>aria-label</pref> in that both provide a flat string to associate with the element (an accessible description, and name, respectively). Unlike an accessible name, which is generally preferred to be concise, a description can provide more verbose information, as necessary.</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>
Expand Down Expand Up @@ -12000,7 +12000,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<p><a>Identifies</a> 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>
<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 (an accessible name, and description, respectively). While a concise accessible name is preferrable, a description can either be concise, or provide more verbose information.</p>
<!-- keep previous sentence synced with the associated description in #aria-describedby -->
<p class="note">The expected spelling of this property in <abbr title="United States">U.S.</abbr> English is "labeledby." However, the <a>accessibility <abbr title="Application Programing Interfaces">API</abbr></a> features to which this property is mapped have established the "labelledby" spelling. This property is spelled that way to match the convention and minimize the difficulty for developers.</p>
</div>
Expand Down

0 comments on commit 0e28ff1

Please sign in to comment.