Skip to content
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

Jump to bottom

Guidelines for range related properties (replaced by #1279) #1000

Closed
wants to merge 5 commits into from
Closed

Guidelines for range related properties (replaced by #1279) #1000

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bb273b5
Draft range related properties
Mar 14, 2019
a8357c7
Minor fixes
Mar 14, 2019
6e43919
Address feedback
zcorpan Apr 23, 2019
01d7aef
Review feedback
Jun 20, 2019
d4a09ee
Move section into aria-practices.html
zcorpan Aug 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
135 changes: 133 additions & 2 deletions aria-practices.html
View file
Open in desktop
Expand Up @@ -3742,7 +3742,7 @@ <h3>What ARE Accessible Names and Descriptions?</h3>
For example, a switch button named <q>Mute Conversation</q> in the <q>off</q> state could be announced as <q>Mute Conversation switch button off</q>.
Because descriptions are optional strings that are usually significantly longer than names, they are presented last, sometimes after a slight delay.
For example, <q>Mute Conversation Switch button off, Silences alerts and notifications about activity in this conversation.</q>
To reduce verbosity, some screen readers do not announce descriptions by default but instead inform users of their presence so that users can press a key that will announce the description.
To reduce verbosity, some screen readers do not announce descriptions by default but instead inform users of their presence so that users can press a key that will announce the description.
</p>
</section>

Expand Down Expand Up @@ -4074,7 +4074,7 @@ <h5>Naming Tables and Figures with Captions</h5>
&lt;/figure></code></pre>
<p>
Like with <code>table</code> elements, if a <code>figure</code> is not named using <code>aria-label</code> or <code>aria-labelledby</code>, the content of the <code>figcaption</code> element will be used as the accessible name.
However unlike <code>table</code> elements, if the <code>figcaption</code> element is not used for the name, it does not become an accessible description unless it is referenced by <code>aria-describedby</code>.
However unlike <code>table</code> elements, if the <code>figcaption</code> element is not used for the name, it does not become an accessible description unless it is referenced by <code>aria-describedby</code>.
Nevertheless, assistive technologies will render the content of a <code>figcaption</code> regardless of whether it is used as a name, description, or neither.
</p>
<p>Using the <code>caption</code> element to name a <code>table</code> element, or a <code>figcaption</code> element to name a <code>figure</code> element, satisfies <a href="#naming_rule_visible_text">Rule 2: Prefer Visible Text</a> and <a href="#naming_rule_native_techniques">Rule 3: Prefer Native Techniques</a>.</p>
Expand Down Expand Up @@ -6279,6 +6279,137 @@ <h3>Indicating sort order with <code>aria-sort</code></h3>

</section>

<section id="range_related_properties">
<h2>Range Related Properties</h2>
zcorpan marked this conversation as resolved.
Show resolved Hide resolved
<p>ARIA provides the following four properties for communicating on the attributes of a range widget:</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aria-valuemin</code></td>
<td>Defines the minimum value in the range.</td>
</tr>
<tr>
<td><code>aria-valuemax</code></td>
<td>Defines the maximum value in the range.</td>
</tr>
<tr>
<td><code>aria-valuenow</code></td>
<td>Defines the value of the element. This value is a number between <code>aria-valuemin</code> and <code>aria-valuemax</code> (if they are present).</td>
</tr>
<tr>
<td><code>aria-valuetext</code></td>
<td>Defines a description of the value of the element.</td>
</tr>
</tbody>
</table>
<p>The range related properties are used to describe an element whose value can be one of a range of values to assistive technologies. These properties communicate the maximum and minimum values for the element and the element's current value.</p>
<p>The range properties can also be used to describe an element whose value can be one of a list of non-numeric values. In this scenario, all possible text values of the element will be programmatically mapped to numbers within the numeric range by the author.</p>
<p>These attributes are used with the following roles:</p>
<ul>
<li><code>slider</code></li>
<li><code>spinbutton</code></li>
<li><code>progressbar</code></li>
<li><code>meter</code></li>
<li><code>scrollbar</code></li>
<li><code>separator</code> (if the element is focusable)</li>
</ul>

<section id="range_related_properties_using_aria-valuemin_and_aria-valuemax">
<h3>Using <code>aria-valuemin</code> and <code>aria-valuemax</code></h3>
<p>When an element's possible values are contained within a known range, the attributes <code>aria-valuemin</code> and <code>aria-valuemax</code> are used to inform assistive technologies of the minimum and maximum values of the range. When using these properties, set <code>aria-valuemin</code> to the lowest value of the range and <code>aria-valuemax</code> to the greatest value.</p>
<p>When the range is unknown, omit both <code>aria-valuemin</code> and <code>aria-valuemax</code>. See an example of a indeterminate range element <a href="">indeterminate progress bar</a>.</p>
zcorpan marked this conversation as resolved.
Show resolved Hide resolved
<h2 id="using-aria-valuenow">Using <code>aria-valuenow</code></h2>
<p>The attribute <code>aria-valuenow</code> is used to inform assistive technologies of the current value of an element. When <code>aria-valuemin</code> and <code>aria-valuemax</code> are specified, set <code>aria-valuenow</code> to a numeric value that is within the range define by <code>aria-valuemin</code> and <code>aria-valuemax</code>.</p>
<h2 id="using-aria-valuetext">Using <code>aria-valuetext</code></h2>
<p>When the element&#39;s values are contained within a range but those values are not numeric (such as "small", "medium" and "large"), <code>aria-valuetext</code> is used to surface the text value to assistive technologies. Only use <code>aria-valuetext</code> when <code>aria-valuenow</code> does not have meaning for the user because using <code>aria-valuetext</code> will prevent assistive technologies from communicating <code>aria-valuenow</code>.</p>
</section>

<section id="range_related_properties_slider_role">
<h3><code>slider</code> Role</h3>
<p><code>aria-valuenow</code>, <code>aria-valuemin</code> and <code>aria-valuemax</code> are all required attributes for the <code>slider</code> role. <code>aria-valuetext</code> can be used when appropriate. Detailed description of the <code>slider</code> role can be found in the <a href="https://w3c.github.io/aria-practices/#slider">slider design pattern</a> and <a href="https://w3c.github.io/aria-practices/#slidertwothumb">slider (multi-thumb) design pattern</a>.</p>
<p>The following example is a temperature controller. <code>aria-valuetext</code> is not be used as the number value in <code>aria-valuenow</code> is meaningful to the user.</p>
<pre><code>&lt;div class="rail"&gt;
&lt;div id="thumb" role="slider" aria-valuemin="50" aria-valuenow="68" aria-valuemax="100"
aria-label="Temperature (F)" tabindex="0"&gt;
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>The slider example above can be made using the HTML input type=range element.</p>
<pre><code>&lt;input type="range" min="50" value="68" max="100" aria-label="Temperature (F)"&gt;
</code></pre><p>The following example is a fan control. The <code>aria-valuenow</code> value is "1", which is not meaningful to the user. The assistive technology will surface the value of <code>aria-valuetext</code> ("low") instead.</p>
<pre><code>&lt;div class="rail"&gt;
&lt;div id="thumb" role="slider" aria-valuemin="0" aria-valuenow="1" aria-valuemax="3"
aria-valuetext="low" aria-label="Fan speed" tabindex="0" &gt;
&lt;/div&gt;
&lt;div class="value"&gt; Off &lt;/div&gt;
&lt;div class="value"&gt; Low &lt;/div&gt;
&lt;div class="value"&gt; Medium &lt;/div&gt;
&lt;div class="value"&gt; High &lt;/div&gt;
&lt;/div&gt;</code></pre>
</section>

<section id="range_related_properties_spinbutton_role">
<h3><code>spinbutton</code> Role</h3>
<p><code>aria-valuenow</code>, <code>aria-valuemin</code> and <code>aria-valuemax</code> are all required attributes for the <code>spinbutton</code> role. <code>aria-valuetext</code> can be used when appropriate.</p>
<p>This example sets the price of paperclips in cents.</p>
<pre><code>&lt;div role="spinbutton" aria-valuemin="1" aria-valuenow="50" aria-valuemax="200" tabindex="0"&gt;
&lt;button id="lower-price"&gt;Lower&lt;/button&gt;
&lt;button id="raise-price"&gt;Raise&lt;/button&gt;
Price per paperclip: $&lt;span id="price"&gt;0.50&lt;/span&gt;
&lt;/div&gt;</code></pre>
<p>The slider example above can be made using the native HTML input type="number" element.</p>
<pre><code>&lt;input type="number" min="0.01" value="0.5" max="2" aria-labelledby="paperclip-label"&gt;
&lt;span id="paperclip-label"&gt;Price per paperclip&lt;/span&gt;:
$&lt;output id="price" aria-labelledby="paperclip-label"&gt;0.50&lt;/output&gt;</code></pre>
<pre><code>&lt;label&gt;Price per paperclip: $&lt;input type="number" min="0.01" value="0.5" max="2" step="0.01"&gt;&lt;/label&gt;</code></pre>
</section>

<section id="range_related_properties_progressbar_role">
<h3><code>progressbar</code> Role</h3>
<p><code>aria-valuenow</code>, <code>aria-valuemin</code> and <code>aria-valuemax</code> are not required attributes for the <code>progressbar</code> role, however, but the attributes might be necessary for communicating the state of a progress bar to assistive technologies.</p>
<p>This is an example of a progress bar represent by an SVG. The range properties are necessary to full explain the widget to assistive technologies.</p>
<pre><code>&lt;div&gt;Loading:
&lt;span role="progressbar" aria-valuemin="0" aria-valuenow="33" aria-valuemax="100" &gt;
&lt;svg width="100" height="10"&gt;
&lt;rect x="0" y="0" height="10" width="100" stroke="black" fill="none"/&gt;
&lt;rect x="0" y="0" height="10" width="33" fill="green" /&gt;
&lt;/svg&gt;
&lt;/span&gt;
&lt;/div&gt;</code></pre>
<p>To represent an indeterminate progress bar where the value range is unknown, omit the <code>aria-valuemin</code>, <code>aria-valuemax</code>, and <code>aria-valuenow</code> attributes.</p>
<pre><code>&lt;img role="progressbar" src="spinner.gif" alt="Loading..."&gt;</code></pre>
<p>The progress bar example can be made using the native HTML progress element.</p>
<pre><code>&lt;label for="loadstatus"&gt;Loading:&lt;/label&gt;
&lt;progress id="loadstatus" max="100" value="33"&gt;&lt;/progress&gt;
</code></pre>
</section>

<section id="range_related_properties_scrollbar_role">
<h3><code>scrollbar</code> Role</h3>
<p><code>aria-valuenow</code>, <code>aria-valuemin</code> and <code>aria-valuemax</code> are all required attributes for the <code>scrollbar</code> role. The value of <code>aria-valuenow</code> will generally be exposed as a percentage between <code>aria-valuemin</code> and <code>aria-valuemax</code> calculated by assistive technologies.</p>
<pre><code>&lt;div id="pi"&gt;
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
&lt;/div&gt;
&lt;div class="rail"&gt;
&lt;div
class="thumb"
role="scrollbar"
aria-controls="pi"
aria-orientation="horizontal"
aria-valuemin="0"
aria-valuemax="100"
aria-valuenow="25"&gt;
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>If <code>aria-valuemin</code> and <code>aria-valuemax</code> are omitted, then the browser will use the default values of 0 and 100, respectively.</p>
</section>
</section>

<section id="presentation_role">
<h2>Intentionally Hiding Semantics with the <code>presentation</code> Role</h2>
<p>
Expand Down