Skip to content

Commit

Permalink
Resolving user agent must not statement and whitespace defs (#1778)
Browse files Browse the repository at this point in the history 
- link to definition of whitespace in the aria-braillelabel and aria-brailleroledescription, aria-roledescription sections
- remove reference to whitespace from user agents must not aria-roledescription requirement
- remove author error correction User Agents MUST NOT expose prohibited ARIA attributes statement from correcting for author errors section.
- adds authors MUST NOT specify aria-roledescription on elements with roles where the attribute is prohibited.
- removed non-normative "should" from aria-brailleroledescription
- adds authors MUST NOT use aria-brailleroledescription where prohibited 
- adds authors MUST NOT use aria-label and aria-labelledby where prohibited
Co-authored-by: James Craig <[email protected]>
  • Loading branch information
@scottaohara @jnurthen
scottaohara authored and jnurthen committed Oct 10, 2023
1 parent 0559b3d commit 032fe93
Showing 1 changed file with 11 additions and 10 deletions.
21 changes: 11 additions & 10 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10592,7 +10592,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<p> When using <code>aria-braillelabel</code>, authors SHOULD also ensure that:</p>
<ol>
<li>The element to which <code>aria-braillelabel</code> is applied has a valid accessible name.</li>
<li>The value of <code>aria-braillelabel</code> is not empty or does not contain only whitespace characters.</li>
<li>The value of <code>aria-braillelabel</code> is not empty or does not contain only [=ascii whitespace|whitespace=] characters.</li>
<li>The value of <code>aria-braillelabel</code> does not contain any characters in <a>Unicode Braille Patterns</a> or consists of only characters in <a>Unicode Braille Patterns</a>; the value does not only contain Braille Pattern dots-0.</li>
<li>The value of <code>aria-braillelabel</code> is not identical to the element's accessible name.</li>
</ol>
Expand Down Expand Up @@ -10639,19 +10639,20 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<p><a>Defines</a> a human-readable, author-localized abbreviated description for the <a>role</a> of an <a>element</a>, which is intended to be converted into Braille. See related <pref>aria-roledescription</pref>.</p>
<p>Some <a>assistive technologies</a>, such as screen readers, present the role of an element as part of the user experience. Such assistive technologies typically localize the name of the role, and they may customize it as well. Users of these assistive technologies depend on the presentation of the role name, such as "region," "button," or "slider," for an understanding of the purpose of the element and, if it is a widget, how to interact with it.</p>
<p>The <code>aria-brailleroledescription</code> property gives authors the ability to override how <a>assistive technologies</a> localize and express the name of a role in Braille. Thus inappropriately using <code>aria-brailleroledescription</code> may inhibit users' ability to understand or interact with an element on braille interfaces. Authors SHOULD limit use of <code>aria-brailleroledescription</code> to clarifying the purpose of non-interactive container roles like <rref>group</rref> or <rref>region</rref>, or to providing a <em>more specific</em> description of a <rref>widget</rref> in a braille context.</p>
<p>Authors MUST NOT use <code>aria-brailleroledescription</code> without providing <code>aria-roledescription</code>. In general, <code>aria-brailleroledescription</code> should only be used in rare cases when a <code>aria-roledescription</code> is excessively verbose when rendered in Braille.</p>
<p> When using <code>aria-brailleroledescription</code>, authors SHOULD also ensure that:</p>
<p>Authors MUST NOT use <code>aria-brailleroledescription</code> without providing <code>aria-roledescription</code>. Additionally, as with <code>aria-roledescription</code>, authors MUST NOT specify <code>aria-brailleroledescription</code> on an element which has an explicit or implicit WAI-ARIA role where <code>aria-brailleroledescription</code> is <a href="#prohibitedattributes">prohibited</a>.</p>
<p>In general, <code>aria-brailleroledescription</code> is only meant to be used in rare cases when a <code>aria-roledescription</code> is excessively verbose when rendered in Braille.</p>
<p>When using <code>aria-brailleroledescription</code>, authors SHOULD also ensure that:</p>
<ol>
<li>The element to which <code>aria-brailleroledescription</code> is applied has a valid <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> role or has an implicit WAI-ARIA role semantic.</li>
<li>The value of <code>aria-brailleroledescription</code> is not empty or does not contain only whitespace characters.</li>
<li>The value of <code>aria-brailleroledescription</code> is not empty or does not contain only [=ascii whitespace|whitespace=] characters.</li>
<li>The value of <code>aria-brailleroledescription</code> does not contain any characters in <a>Unicode Braille Patterns</a> or consists of only characters in <a>Unicode Braille Patterns</a>; the value does not only contain Braille Pattern dots-0.</li>
<li>The value of <code>aria-brailleroledescription</code> should not be identical to the element's WAI-ARIA <code>aria-roledescription</code>, WAI-ARIA <code>role</code> or implicit WAI-ARIA role semantic.</li>
</ol>
<p class="note">Note that <a>Assistive Technologies</a> with braille support can convert <code>aria-roledescription</code> content to Braille. In addition, assistive technologies will be able to customize such braille output according to user preferences. Using only <code>aria-roledescription</code> is <strong>almost always</strong> the better user experience and authors are <strong>strongly discouraged</strong> from using <code>aria-brailleroledescription</code> to replicate <code>aria-roledescription</code>. Instead, <code>aria-brailleroledescription</code> is meant to be used only when <code>aria-roledescription</code> cannot provide an adequate braille representation, i.e., when a specialized braille description is very different from a text description converted to Braille. It is very important to note that when using <code>aria-brailleroledescription</code> authors are solely responsible for localizing the attribute value so that it aligns with the document language. In addition, authors need to design a way to clearly communicate the use of this attribute to the user. For example, this could be done in the product documentation. This is even more important when the value consists of Unicode Braille Patterns because <a>Assistive Technologies</a> will pass such content directly to the user without applying user specific braille translations; in general, authors are <strong>strongly discouraged</strong> from using Unicode Braille Patterns in <code>aria-brailleroledescription</code>.
</p>
<p>User agents MUST NOT expose the <code>aria-brailleroledescription</code> property if any of the following conditions exist:</p>
<ol>
<li>The value of <code>aria-brailleroledescription</code> is empty or contains only whitespace characters or the empty Braille pattern: dots-0 (U+2800).</li>
<li>The value of <code>aria-brailleroledescription</code> is empty or contains only whitespace characters, which includes standard [=ascii whitespace|whitespace=] and the empty Braille pattern: dots-0 (U+2800).</li>
<li>The element to which <code>aria-brailleroledescription</code> is applied has an explicit or implicit WAI-ARIA role where <code>aria-brailleroledescription</code> is <a href="#prohibitedattributes">prohibited</a>.</li>
<li>The element to which <code>aria-brailleroledescription</code> is applied does not have a valid WAI-ARIA <code>aria-roledescription</code>.</li>
</ol>
Expand Down Expand Up @@ -11942,7 +11943,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<div class="property-description">
<p><a>Defines</a> a string value that labels the current element. See related <pref>aria-labelledby</pref>.</p>
<p>The purpose of <pref>aria-label</pref> is the same as that of <pref>aria-labelledby</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 label text is available in the DOM (i.e. typically visible text content), authors SHOULD use <pref>aria-labelledby</pref> and SHOULD NOT use <pref>aria-label</pref>. There may be instances where the name of an element cannot be determined programmatically from the DOM, and there are cases where referencing DOM content is not the desired user experience. Most host languages provide an attribute that could be used to name the element (e.g., the <code>title</code> attribute in [[HTML]]), yet this could present a browser tooltip. In the cases where DOM content or a tooltip is undesirable, authors MAY set the accessible name of the element using <pref>aria-label</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>Most host languages provide an attribute that could be used to name the element (e.g., the <code>title</code> attribute in [[HTML]]), yet this could present a browser tooltip. In the cases where DOM content or a tooltip is undesirable, authors MAY set the accessible name of the element using <pref>aria-label</pref>, if the element does not <a href="#prohibitedattributes">prohibit</a> use of the attribute. If the label text is available in the DOM (i.e. typically visible text content), authors SHOULD use <pref>aria-labelledby</pref> and SHOULD NOT use <pref>aria-label</pref>. There may be instances where the name of an element cannot be determined programmatically from the DOM, and there are cases where referencing DOM content is not the desired user experience. Authors MUST NOT specify <code>aria-label</code> on an element which has an explicit or implicit WAI-ARIA role where <code>aria-label</code> is <a href="#prohibitedattributes">prohibited</a>. 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>
</div>
<table class="property-features">
<caption>Characteristics:</caption>
Expand Down Expand Up @@ -11977,7 +11978,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<div class="property-description">
<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>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>. Authors MUST NOT specify <code>aria-labelledby</code> on an element which has an explicit or implicit WAI-ARIA role where <code>aria-labelledby</code> is <a href="#prohibitedattributes">prohibited</a>. 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 (an accessible name, and description, respectively). While a concise accessible name is preferable, 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>
Expand Down Expand Up @@ -12714,13 +12715,14 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<p>When using <code>aria-roledescription</code>, authors SHOULD also ensure that:</p>
<ol>
<li>The element to which <code>aria-roledescription</code> is applied has a valid <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> role or has an implicit WAI-ARIA role semantic.</li>
<li>The value of <code>aria-roledescription</code> is not empty or does not contain only whitespace characters.</li>
<li>The value of <code>aria-roledescription</code> is not empty or does not contain only [=ascii whitespace|whitespace=] characters.</li>
</ol>
<p class="note">Depending on the assistive technology, user verbosity settings, or other factors, certain elements' role descriptions might not be conveyed. If specifying <code>aria-roledescription</code> on such elements, then the custom role descriptions may also not be conveyed by these assistive technologies.</p>
<p>Additionally, authors MUST NOT specify <code>aria-roledescription</code> on an element which has an explicit or implicit WAI-ARIA role where <code>aria-roledescription</code> is <a href="#prohibitedattributes">prohibited</a>.</p>
<p>User agents MUST NOT expose the <code>aria-roledescription</code> property if any of the following conditions exist:</p>
<ol>
<li>The element to which <code>aria-roledescription</code> is applied has an explicit or implicit WAI-ARIA role where <code>aria-roledescription</code> is <a href="#prohibitedattributes">prohibited</a>.</li>
<li>The value of <code>aria-roledescription</code> is empty or contains only whitespace characters.</li>
<li>The value of <code>aria-roledescription</code> is undefined or the empty string.</li>
</ol>
<p><a>Assistive technologies</a> SHOULD use the value of <code>aria-roledescription</code> when presenting the role of an element, but SHOULD NOT change other functionality based on the role of an element that has a value for <code>aria-roledescription</code>. For example, an assistive technology that provides functions for navigating to the next <rref>region</rref> or <rref>button</rref> SHOULD allow those functions to navigate to regions and buttons that have an <code>aria-roledescription</code>.</p>
<p>The following two examples show the use of <code>aria-roledescription</code> to indicate that a non-interactive container is a "slide" in a web-based presentation application.</p>
Expand Down Expand Up @@ -13516,7 +13518,6 @@ <h3>States and Properties</h3>
<li>When the state or property has only one ID reference that cannot be resolved, treat as if the state or property is not present.</li>
<li>When the state or property has a list of ID references, ignore any that can't be resolved. If none in the list can be resolved, treat as if the state or property is not present.</li>
</ul>
<p>User Agents MUST NOT expose an ARIA attribute to the platform accessibility API when the element's computed role <a href="#prohibitedattributes">prohibits</a> use of the attribute.</p>
<p>If a required <abbr title="Accessible Rich Internet Application">WAI-ARIA</abbr> attribute for a given role is missing, user agents SHOULD process the attribute as if the values given in the following table were provided.</p>
<table id="authorErrorDefaultValuesTable">
<caption>Fallback values for missing required attributes</caption>
Expand Down

0 comments on commit 032fe93

Please sign in to comment.