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 #1279

Merged
merged 63 commits into from
Jul 7, 2020
Merged

Guidelines for range related properties #1279

Changes from all commits
Commits
Show all changes
63 commits
Select commit Hold shift + click to select a range
3a2d977
Draft range related properties
Mar 14, 2019
7955203
Minor fixes
Mar 14, 2019
b382e78
Address feedback
zcorpan Apr 23, 2019
9eefa62
Review feedback
Jun 20, 2019
8065be0
Move section into aria-practices.html
zcorpan Aug 30, 2019
2f8d7a1
Fix a broken link
zcorpan Dec 3, 2019
2b5fa5a
Fix markup
zcorpan Dec 3, 2019
ff195f2
Rename some headings, add a table for valuemin/max
zcorpan Dec 3, 2019
e7ccbb8
Expand on aria-valuenow
zcorpan Dec 3, 2019
33fa65e
Formatting of markup
zcorpan Dec 3, 2019
f28246b
Fix a factual error about which properties are required for spinbutton
zcorpan Dec 3, 2019
4ebf1d7
Clarify table for aria-valuemin/max
zcorpan Dec 4, 2019
8af8dc1
Reorder roles alphabetically
zcorpan Dec 4, 2019
de54321
The only range without min/max is spinbutton
zcorpan Dec 4, 2019
171151a
Add an example for aria-valuetext
zcorpan Dec 4, 2019
4dffa19
Tweaks wording for undefined range; indeterminate progress bars can s…
zcorpan Dec 4, 2019
541b9d4
Editorial revisions to introduction
mcking65 Dec 10, 2019
1f02c30
Further editorial simplification of introduction
mcking65 Dec 10, 2019
bfbfe30
Further editorial revision to intro
mcking65 Dec 10, 2019
c0a18e9
Refine definition table in intro
mcking65 Dec 10, 2019
f4c9cc1
Delete unnecessary 'is'
mcking65 Dec 10, 2019
9d5b744
Editorial revisions to min and max section
mcking65 Dec 10, 2019
55b86f6
Editorial revisions to valuenow section
mcking65 Dec 10, 2019
7882709
Section title: of -> for
mcking65 Dec 10, 2019
3c27fea
Apply suggestions from code review
zcorpan Jan 9, 2020
f7631e9
added meter example under range properties
a11ydoer Feb 22, 2020
a97ebf3
Editorial: meter shows current (not changed) CPU usage
carmacleod Feb 26, 2020
8890612
Editorial: aria-valuenow is required, so no default value
carmacleod Feb 26, 2020
00f796b
Add label to example code
carmacleod Feb 26, 2020
1e7c627
Update section 8.1
carmacleod Mar 3, 2020
ad2e512
update range aria value properties in summary table and each role acc…
a11ydoer Apr 5, 2020
af32cfc
update meter ranage and add and modify suggested ph exmaple
a11ydoer Apr 6, 2020
ae55151
editorial and exmaple code change with comments
a11ydoer May 11, 2020
2ed177f
fixed some of testing failure
a11ydoer May 11, 2020
d26175b
Change H2 to H3 for subsections that had wrong heading level
mcking65 May 12, 2020
f617409
valuetext: minor editorial revisions for style
mcking65 May 12, 2020
a5551cb
valuetext subsection: Remove value min and max from meter example
mcking65 May 12, 2020
03fc089
meter role: editorial revisions for style
mcking65 May 12, 2020
8de7bc1
Add link to meter design pattern
mcking65 May 12, 2020
454c86c
add missing end tag for code
carmacleod May 26, 2020
60b1dc3
remove "not exactly" so that progressbar aria-valuenow is required if…
carmacleod May 26, 2020
8c39d7f
use more common language
carmacleod May 27, 2020
fd01798
fix plural/singular
carmacleod May 27, 2020
6c66a07
fewer words
carmacleod May 27, 2020
8223e98
add missing "the"
carmacleod May 27, 2020
dbf9361
fix tense
carmacleod May 27, 2020
6ba425c
editorial: full explain -> fully explain
carmacleod May 27, 2020
82ff06e
reword so that using aria-valuetext is sentence subject, not AT
carmacleod May 27, 2020
7857586
fix plural/singular in sentence and role name
carmacleod May 27, 2020
acc9d88
add missing code tags
carmacleod May 27, 2020
f94fa26
reorder sentence for clarity
carmacleod May 27, 2020
2b9cdf4
use slightly more interesting word
carmacleod May 27, 2020
62ffa4d
fix plural/singular
carmacleod May 27, 2020
045f597
change range property table and code comment type
a11ydoer Jun 2, 2020
864db2b
remove duplicate html spin button example and switch the order of ind…
a11ydoer Jun 2, 2020
75daeb2
textual > text
mcking65 Jul 1, 2020
6253cd7
Revise intro to second meter example for ease of understanding
mcking65 Jul 1, 2020
fe3a311
Editorial simplification of progress bar
mcking65 Jul 1, 2020
6c9081c
Minor editorial revisions to spinbutton section for clarity
mcking65 Jul 1, 2020
07541b7
Apply suggestions by @carmacleod from review
mcking65 Jul 7, 2020
1985db4
Clarify usage of min, max, and now per feedback from @jongund
mcking65 Jul 7, 2020
d893526
change capitalized The to lowercase the
carmacleod Jul 7, 2020
311e7be
Merge branch 'master' into zcorpan/range-related-properties-2
mcking65 Jul 7, 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
310 changes: 310 additions & 0 deletions aria-practices.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6426,6 +6426,316 @@ <h3>Indicating sort order with <code>aria-sort</code></h3>

</section>

<section id="range_related_properties">
<h2>Communicating Value and Limits for Range Widgets</h2>
<p>
ARIA defines the following roles as range widgets, which means they communicate a value that is typically numeric and constrained to defined limits.
</p>
<ul>
<li><code>meter</code></li>
<li><code>progressbar</code></li>
<li><code>scrollbar</code></li>
<li><code>separator</code> (if focusable)</li>
<li><code>slider</code></li>
<li><code>spinbutton</code></li>
</ul>
<p>
For example, a spin button for choosing a day within the month of January would allow integer values that range from 1 to 31.
In some cases, the value is represented numerically, but is not presented as a number to users.
For instance, a spin button for choosing a day of the week could support values from 1 to 7 but they could be presented to the user as day names, e.g., "Monday", "Tuesday", etc.
</p>
<p>
This section describes considerations for using the following four properties that communicate characteristics of a range widget:
</p>
<table>
<thead>
<tr>
<th>Property</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<th><code>aria-valuemin</code></th>
<td>Defines the minimum value allowed by a range widget.</td>
</tr>
<tr>
<th><code>aria-valuemax</code></th>
<td>Defines the maximum value allowed by a range widget.</td>
</tr>
<tr>
<th><code>aria-valuenow</code></th>
<td>Defines the current value of a range widget. This value is a number greater than or equal to <code>aria-valuemin</code> and less than or equal to <code>aria-valuemax</code> (if they are specified).</td>
</tr>
<tr>
<th><code>aria-valuetext</code></th>
<td>If a numeric value is not sufficiently descriptive, this property can define a text description of the current value of a range widget.</td>
</tr>
</tbody>
</table>

<section id="range_related_properties_using_aria-valuemin_aria-valuemax_and_aria-valuenow">
<h3>Using <code>aria-valuemin</code>, <code>aria-valuemax</code> and <code>aria-valuenow</code></h3>
<p>
When the value of a range widget is constrained to known limits, the <code>aria-valuemin</code> and <code>aria-valuemax</code> properties are used to inform assistive technologies of the minimum and maximum values of the range.
For some widgets, assistive technologies use this information to present the current value as a percentage.
When using these properties, set <code>aria-valuemin</code> to the lowest value allowed for the widget and <code>aria-valuemax</code> to the highest allowed value.
If values for <code>aria-valuemin</code> and <code>aria-valuemax</code> are not set, default values are exposed to assistive technologies unless the widget is a <code>spinbutton</code>, which is the only range widget that does not have default limits.
</p>
<p>
The <code>aria-valuenow</code> property is used to inform assistive technologies of the current value of a range widget.
Set <code>aria-valuenow</code> to the current value of the widget, ensuring the value of <code>aria-valuenow</code> falls within the range defined by <code>aria-valuemin</code> and <code>aria-valuemax</code>.
If the current value of a <code>progressbar</code> or <code>spinbutton</code> is indeterminate or unknown, omit the <code>aria-valuenow</code> property.
The <code>aria-valuenow</code> property is required for the <code>meter</code>, <code>scrollbar</code>, <code>separator</code> (if the element is focusable), and <code>slider</code> roles.
</p>
<p>
The range widget roles have the following default values and requirements for <code>aria-valuemin</code>, <code>aria-valuemax</code> and <code>aria-valuenow</code>.
</p>
<table>
<thead>

<tr>
<th scope="col">Role</th>
<th scope="col"><code>aria-valuemin</code><br>(default)</th>
<th scope="col"><code>aria-valuemax</code><br>(default)</th>
<th scope="col"><code>aria-valuemin</code><br>(required)</th>
<th scope="col"><code>aria-valuemax</code><br>(required)</th>
<th scope="col"><code>aria-valuenow</code><br>(required)</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row"><code>meter</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>progressbar</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<th scope="row"><code>scrollbar</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>separator</code> <small>(if focusable)</small></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>slider</code></th>
<td>0</td>
<td>100</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
</tr>
<tr>
<th scope="row"><code>spinbutton</code></th>
<td>None</td>
<td>None</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
</tbody>
</table>
</section>

<section id="range_related_properties_using_aria-valuetext">
<h3>Using <code>aria-valuetext</code></h3>

<p>
When the element's values are contained within a range but those values are not numeric (such as "small", "medium" and "large"),
or they are numeric but there is value in communicating more information than just a number,
<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> is not sufficiently meaningful for users because using <code>aria-valuetext</code> will prevent assistive technologies from communicating <code>aria-valuenow</code>.
</p>

<div class="example">
<p>
For example, for a battery indicator, it would be useful to know how many minutes are remaining, in addition to the percentage of charge remaining.
</p>

<pre><code>
&lt;span id="battery-label">Battery&lt;/span>
&lt;span role="meter" aria-labelledby="battery-label"
aria-valuenow="5"
aria-valuetext="5%, 18 minutes remaining.">
&lt;/span>
</code></pre>
</div>
</section>

<section id="range_related_properties_meter_role">
<h3>Range properties with meter</h3>
<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for elements with role <code>meter</code> if the meter's minimum value is not 0 or its maximum value is not 100.
It is necessary, however, to always specify a value for <code>aria-valuenow</code> and to ensure the value is greater than or equal to the minimum allowed value and less than or equal to the maximum allowed value.
A detailed description of the <code>meter</code> role is in the <a href="#meter">meter design pattern</a>.</p>

<p>This example of a meter shows the current Central Processing Unit (CPU) usage. </p>

<pre><code>&lt;span id="cpu_usage_label">CPU usage&lt;/span>
&lt;!-- The CPU usage uses the default values of 0 and 100 for aria-valuemin and aria-valuemax --&gt;
&lt;div role="meter"
aria-valuenow="90"
aria-labelledby="cpu_usage_label"&gt;
&lt;/div&gt;</code></pre>

<p>
The <code>aria-valuetext</code> property can be set to a string that makes the meter value understandable. For example, a CPU usage meter value might be conveyed as <code>aria-valuetext="90% of CPU is being used"</code>.
</p>
<p>Here is another example of a meter that has a range different from the default of 0 for <code>aria-valuemin</code> and 100 for <code>aria-valuemax</code>.</p>

<pre><code>&lt;span id="ph_alkaline_meter_label">Alkaline pH(Power of Hydrogen) Level&lt;/span>
&lt;div role="meter"
aria-valuenow="9"
aria-valuemin="7"
aria-valuemax="14"
aria-labelledby="ph_alkaline_meter_label"&gt;
&lt;/div&gt;</code></pre>
</section>
<section id="range_related_properties_progressbar_role">
<h3>Range properties with progress bars</h3>

<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for the <code>progressbar</code> role when the progress bar's minimum is not 0 or the maximum value is not 100.
The aria-valuenow property needs to be set for a <code>progressbar</code> if its value is known (e.g. not indeterminate).
If the <code>aria-valuenow</code> property is set, the author needs to make sure it is within the minimum and maximum values.
</p>
<p>Following is an example of a progress bar represented by an SVG.</p>

<pre><code>&lt;div&gt;&lt;span id="loadlabel"&gt;Loading:&lt;/span&gt;
&lt;!-- The progress bar uses the default values of 0 and 100 for aria-valuemin and aria-valuemax --&gt;
&lt;span role="progressbar"
aria-labelledby="loadlabel"
aria-valuenow="33" &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>This progress bar can also be made using the native HTML <code>progress</code> 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>

<p>To represent an indeterminate progress bar where the value range is unknown, omit the <code>aria-valuenow</code> attribute.</p>

<pre><code>&lt;img role="progressbar" src="spinner.gif" alt="Loading..."&gt;</code></pre>
</section>

<section id="range_related_properties_scrollbar_role">
<h3>Range properties with scrollbars</h3>

<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for the <code>scrollbar</code> role when it's minimum value is not 0 or the maximum value is not 100. The <code>aria-valuenow</code> property is required for <code>scrollbar</code> and the author needs to make sure it is within the minimum and maximum values.
</p>
<p>
<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;span id="pi-label"&gt;Pi&lt;/div&gt;
&lt;div id="pi"&gt;
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
&lt;/div&gt;
&lt;div class="rail"&gt;
&lt;!-- The scrollbar uses the default values of 0 and 100 for aria-valuemin and aria-valuemax --&gt;
&lt;div
class="thumb"
role="scrollbar"
aria-labelledby="pi-label"
aria-controls="pi"
aria-orientation="horizontal"
aria-valuenow="25"&gt;
&lt;/div&gt;
&lt;/div&gt;</code></pre>


</section>

<section id="range_related_properties_slider_role">
<h3>Range properties with sliders</h3>
<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties only need to be set for the <code>slider</code> role when the slider's minimum is not 0 or the maximum value is not 100.
The <code>aria-valuenow</code> property is required for <code>slider</code> role and the author needs to make sure it is within the minimum and maximum values.
A detailed description of the <code>slider</code> role can be found in the <a href="#slider">slider design pattern</a> and <a href="#slidertwothumb">slider (multi-thumb) design pattern</a>.
</p>
<p>
The following example shows a temperature controller.
In this example, <code>aria-valuenow</code> is meaningful to the user, and so <code>aria-valuetext</code> is not used.
</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 <code>&lt;input type="range"></code> 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 <code>aria-valuetext</code> property is used so that assistive technology will surface its value ("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>Range properties with spin buttons</h3>

<p>
The <code>aria-valuemin</code> and <code>aria-valuemax</code> properties are used only when a <code>spinbutton</code> has a defined range.
They do not have default values, so if they are not specified, range limits will not be exposed to assistive technologies.
Similarly, the <code>aria-valuenow</code> property is set only when a <code>spinbutton</code> has a value.
If it is not set, a value is not exposed to assistive technologies for the <code>spinbutton</code>.
<code>aria-valuetext</code> can be used when appropriate.
A detailed description of the <code>spinbutton</code> role can be found in the <a href="#spinbutton">spinbutton design pattern</a>.
</p>

<p>The following example sets the price of paperclips in cents.</p>

<pre><code>&lt;div role="spinbutton" aria-labelledby="price-label" aria-valuenow="50" tabindex="0"&gt;
&lt;button id="lower-price"&gt;Lower&lt;/button&gt;
&lt;button id="raise-price"&gt;Raise&lt;/button&gt;
&lt;span id="price-label"&gt;Price per paperclip: $&lt;/span&gt;&lt;span id="price"&gt;0.50&lt;/span&gt;
&lt;/div&gt;</code></pre>

<p>If there are minimum and maximum allowed values, set the <code>aria-valuemin</code> and <code>aria-valuemax</code> properties.</p>

<pre><code>&lt;div role="spinbutton" aria-labelledby="price-label"
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;
&lt;span id="price-label"&gt;Price per paperclip: $&lt;/span&gt;&lt;span id="price"&gt;0.50&lt;/span&gt;
&lt;/div&gt;</code></pre>

<p>The spin button example above can be made using the native HTML <code>&lt;input type="number"></code> element.</p>

<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>

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