Skip to content

Commit

Permalink
Editorial revisions to roles, states, and props documentation for cla…
Browse files Browse the repository at this point in the history 
…rity and consistency
  • Loading branch information
@mcking65
mcking65 committed Oct 3, 2021
1 parent 4790872 commit d18cc06
Showing 1 changed file with 66 additions and 89 deletions.
155 changes: 66 additions & 89 deletions examples/switch/switch-button.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ <h1>Switch Example Using HTML Button</h1>
This example illustrates implementing the <a href="../../#switch">switch design pattern</a> with an HTML <code>button</code> as a switch element and using an <code>SVG</code> element to provide graphical rendering of switch states.
It also demonstrates using the <code>group</code> role to present multiple switches in a labeled group.
</p>
<!-- Remove links to examples that are not yet merged. -->
<!-- Remove links to examples that are not yet merged.
<p>Similar examples include: </p>
<ul>
<li><a href="switch.html">Switch example using the <code>div</code> element.</a></li>
Expand Down Expand Up @@ -81,39 +81,31 @@ <h3 id="id-group-label" >Environmental Controls</h3>
<section>
<h2>Accessibility Features</h2>
<ul>
<li>To help assistive technology users understand that the <q>Environmental Controls</q> are a group of two switches, the switches are wrapped in a <code>group</code> labeled by the heading that labels the set of switches.</li>
<li>
To help assistive technology users understand that the environmental control options are made of a group of two switches, the switches are wrapped in a <code>group</code> labeled by the heading that labels the notification options.
To make understanding the state of the switch easier for users with visual or cognitive disabilities, a text equivalent of the state (<q>on</q> or <q>off</q>) is displayed adjacent to the graphical state indicator.
CSS attribute selectors ensure the label displayed is synchronized with the value of the <code>input</code>.<br/>
<strong>NOTE:</strong> To prevent redundant announcement of the state by screen readers, the text indicators of state are hidden from assistive technologies with <code>aria-hidden</code>.
</li>
<li>
Uses CSS <code>:hover</code> and <code>:focus</code> pseudo-class for styling visual keyboard focus and hover. The focus styling makes the relationship between the label and the switch perceivable to the user by creating a border around both the switch and the label and also changing the background color.
<li>Spacing, stroke widths, and fill are important to ensure the graphical states will be visible and discernible to people with visual impairments, including when browser or operating system high contrast settings are enabled:
<ul>
<li>
The focus indicator encompasses both the switch and label to make it easier to perceive when the switch has focus.
</li>
<li>
The hover indicator is the same as focus indicator to make it easier to perceive that clicking either the label or switch will activate the switch.
</li>
<li>
The cursor is changed to a pointer when hovering over the switch to help people with visual impairments identify it as an interactive element.
</li>
<li>To make the graphical representation of the state of a switch readily perceivable, two pixel stroke width is used for the switch state container and a solid color is used to fill the rectangles indicating the on and off states.</li>
<li>To ensure users can perceive the difference between the container and the rectangles used to indicate the state of the switch, there are two pixels of space between the container border and the rectangles.</li>
</ul>
</li>
<li>
A visual text label (<q>on</q> or <q>off</q>) of the state is rendered adjacent to the graphical state indicator to make understanding the state easier for users with visual or cognitive disabilities.<br/>
NOTE: These labels are hidden from assistive technologies with <code>aria-hidden</code> to prevent screen readers from redundantly announcing the state, and CSS attribute selectors ensure the label display is synchronized with the value of the <code>aria-checked</code>.
</li>
<li>Spacing, stroke widths and fill are important to ensure the graphical states will be visible and discernible to people with visual impairments, including when browser or operating system high contrast settings are enabled:
<li>To enhance perceivability when operating the switches, visual keyboard focus and hover are styled using the CSS <code>:hover</code> pseudo-class and <code>onfocus</code> and <code>onblur</code> event handlers:
<ul>
<li>Two pixel stroke width is used for the switch state container and a solid color is used for to fill the rectangles indicating the on and off states for the user to perceive the graphical state of the switch.</li>
<li>Two pixels of space is used between the container border and the rectangles to make sure the user can perceive the difference between the container and the rectangles used to indicate the state of the switch.</li>
<li>To make it easier to perceive focus and the relationship between a label and its associated switch, focus creates a border around both the switch and the label and also changes the background color.</li>
<li>To make it easier to perceive that clicking either the label or switch will activate the switch, the hover indicator is the same as the focus indicator.</li>
<li>To help people with visual impairments identify the switch as an interactive element, the cursor is changed to a pointer when hovering over the switch.</li>
</ul>
</li>
<li>
To ensure the SVG graphics have sufficient contrast with the background when high contrast settings invert colors, the CSS <code>currentColor</code> value for the <code>stroke</code> and <code>fill</code> properties is used to synchronize the colors with text content.
If specific colors were used to specify the <code>stroke</code> and <code>fill</code> properties, the color of these elements would remain the same in high contrast mode, which could lead to insufficient contrast between them and their background or even make them invisible if their color were to match the high contrast mode background.
The <code>fill-opacity</code> of the container <code>rect</code> is set to zero for the background color of the page to provide the contrasting color to the <code>stroke</code> and <code>fill</code> colors.
<br/>NOTE: The SVG elements need to set the CSS <code>forced-color-adjust</code> property to <code>auto</code> for some browsers to support the <code>currentColor</code> value.
</li>
</li>
</ul>
</section>

Expand Down Expand Up @@ -159,77 +151,63 @@ <h2 id="rps_label">Role, Property, State, and Tabindex Attributes</h2>
</tr>
</thead>
<tbody>
<tr data-test-id="h3">
<th scope="row"></th>
<td></td>
<td><code>h3</code></td>
<td>
<ul>
<li>Provides a grouping label for the group of switches.</li>
</ul>
</td>
</tr>
<tr data-test-id="group-role">
<th scope="row"><code>group</code></th>
<td></td>
<td><code>div</code></td>
<td>
<ul>
<li>Identifies the <code>div</code> element as a <code>group</code> container for the switches.</li>
</ul>
</td>
</tr>
<tr data-test-id="group-aria-labelledby">
<th scope="row"></th>
<td><code>aria-labelledby</code></td>
<td><code>div</code></td>
<td>
<tr data-test-id="switch-role">
<th scope="row"><code>switch</code></th>
<td></td>
<td><code>button</code></td>
<td>Identifies the <code>button</code> element as a <code>switch</code>.</td>
</tr>
<tr data-test-id="switch-aria-checked">
<td></td>
<th scope="row"><code>aria-checked="false"</code></th>
<td><code>button</code></td>
<td>
<ul>
<li>The <code>aria-labelledby</code> attribute references the <code>id</code> attribute of the <code>h3</code> element to define the accessible name for the group of switches.</li>
<li>Indicates the <code>switch</code> is off.</li>
<li>CSS attribute selectors (e.g. <code>[aria-checked="false"]</code>) are used to synchronize the visual states with the value of the <code>aria-checked</code> attribute.</li>
</ul>
</td>
</tr>
<tr data-test-id="switch-role">
<th scope="row"><code>switch</code></th>
<td></td>
<td><code>button</code></td>
<td>
The <code>role=&quot;switch&quot;</code> attribute identified the <code>button</code> element as an ARIA <code>switch</code>.
</td>
</tr>
<tr data-test-id="switch-aria-checked">
<td></td>
<th scope="row"><code>aria-checked=&quot;false&quot;</code></th>
<td><code>button</code></td>
<td>
<ul>
<li>Identifies the <code>switch</code> button as off.</li>
<li>CSS attribute selectors (e.g. <code>[aria-checked=&quot;false&quot;]</code>) are used to synchronize the visual states with the value of the <code>aria-checked</code> attribute.</li>
</ul>
</td>
</tr>
<tr data-test-id="switch-aria-checked">
<td></td>
<th scope="row"><code>aria-checked=&quot;true&quot;</code></th>
<td><code>button</code></td>
<td>
<ul>
<li>Identifies the <code>switch</code> as on.</li>
<li>CSS attribute selectors (e.g. <code>[aria-checked=&quot;true&quot;]</code>) are used to synchronize the visual states with the value of the <code>aria-checked</code> attribute.</li>
</ul>
</td>
</tr>
<tr data-test-id="aria-hidden">
<td></td>
<th scope="row"><code>aria-hidden="true"</code></th>
<td><code>span.on</code> and <code>span.off</code></td>
<td>
</td>
</tr>
<tr data-test-id="switch-aria-checked">
<td></td>
<th scope="row"><code>aria-checked="true"</code></th>
<td><code>button</code></td>
<td>
<ul>
<li>Removes the strings <q>on</q> and <q>off</q> that appear to the right of the switch from the accessible name of the switch.</li>
<li>These strings are included only for enhancing visual comprehension of the state; element states are not permitted in accessible names.</li>
<li>Indicates the <code>switch</code> is on.</li>
<li>CSS attribute selectors (e.g. <code>[aria-checked="true"]</code>) are used to synchronize the visual states with the value of the <code>aria-checked</code> attribute.</li>
</ul>
</td>
</tr>
</td>
</tr>
<tr data-test-id="aria-hidden">
<td></td>
<th scope="row"><code>aria-hidden="true"</code></th>
<td><code>span.on</code> and <code>span.off</code></td>
<td>
<ul>
<li>Removes the strings <q>on</q> and <q>off</q> that appear to the right of the switch from the accessible name of the switch.</li>
<li>These strings are included only for enhancing visual comprehension of the state; element states are not permitted in accessible names.</li>
</ul>
</td>
</tr>
<tr data-test-id="h3">
<th scope="row"></th>
<td></td>
<td><code>h3</code></td>
<td>Provides a grouping label for the group of switches.</td>
</tr>
<tr data-test-id="group-role">
<th scope="row"><code>group</code></th>
<td></td>
<td><code>div</code></td>
<td>Identifies the <code>div</code> element as a <code>group</code> container for the switches.</td>
</tr>
<tr data-test-id="group-aria-labelledby">
<th scope="row"></th>
<td><code>aria-labelledby</code></td>
<td><code>div</code></td>
<td>References the <code>h3</code> element to define the accessible name for the group of switches.</td>
</tr>
</tbody>
</table>
</section>
Expand Down Expand Up @@ -266,7 +244,6 @@ <h2 id="sc1_label">HTML Source Code</h2>
</section>
</main>
<nav>
<!-- Update the pattern_ID parameter of this link to refer to the APG design pattern section related to this example. -->
<a href="../../#switch">Switch Design Pattern in WAI-ARIA Authoring Practices 1.2</a>
</nav>
</body>
Expand Down

0 comments on commit d18cc06

Please sign in to comment.