Switch Role: Draft Guideance

aria-practices.html

@@ -2558,6 +2558,75 @@ <h4>WAI-ARIA Roles, States, and Properties</h4>
       </section>
     </section>
 
+    <section class="widget" id="switch">
+      <h3>Switch</h3>
+      <p>
+        A <a href="#switch" class="role-reference">switch</a> is an input widget that allows users to choose one of two values: <q>on</q> or <q>off</q>.
+        Switches are similar to <a href="#checkbox">checkboxes</a> and <a href="#button">toggle buttons</a>, which can also serve as binary inputs.
+        One difference, however, is that switches can only be used for binary input while checkboxes and toggle buttons allow implementations the option of supporting a third middle state.
+        Checkboxes can be <q>checked</q> or <q>not checked</q> and can optionally also allow for a <q>partially checked</q> state.
+        Toggle buttons can be <q>pressed</q> or <q>not pressed</q> and can optionally allow for a <q>partially pressed</q> state.
+      </p>
+      <p>
+        Since switch, checkbox, and toggle button all offer binary input, they are often functionally interchangeable.
+        Choose the role that best matches both the visual design and semantics of the user interface.
+        For instance, there are some circumstances where the semantics of <q>on or off</q> would be easier for assistive technology users to understand than the semantics of <q>checked or unchecked</q>, and vice versa.
+        Consider a widget for turning lights on or off.
+        In this case, screen reader output of <q>Lights switch on</q> is more user friendly than <q>Lights checkbox checked</q>. 
+        However, if the same input were in a group of inputs labeled <q>Which of the following must be included in your pre-takeoff procedures?</q>, <q>Lights checkbox checked</q> would make more sense.
+      </p>
+      <p>
+        <strong>Important:</strong> it is critical the label on a switch does not change when its state changes.
+      </p>
+
+      <section class="notoc">
+        <h4>Examples</h4>
+        <ul>
+          <li>To be added.</li>
+          <!--  
+          <li>
+            <a href="examples/switch/switch.html">Switch using <code>div</code> element Example</a>: Demonstrates switches used for turning on/off notifications.</li>
+          <li><a href="examples/switch/switch-button.html">Switch using <code>button</code> element Example</a>: Demonstrates switches used for turning on/off lights.</li>
+          <li><a href="examples/switch/switch-checkbox.html">Switch using <code>input[type=&quot;checkbox&quot;]</code> element Example</a>: Demonstrates switches used for turning on/off accessibility preferences.
+          </li>
+          -->
+        </ul>
+      </section>
+
+      <section class="notoc">
+        <h4>Keyboard Interaction</h4>
+        <ul>
+          <li><kbd>Space</kbd>: When focus is on the switch, changes the state of the switch.</li>
+          <li><kbd>Enter</kbd> (Optional): When focus is on the switch, changes the state of the switch.</li>
+        </ul>
+      </section>
+
+      <section class="notoc">
+        <h4>WAI-ARIA Roles, States, and Properties</h4>
+        <ul>
+          <li>The switch has role <a href="#switch" class="role-reference">switch</a>.</li>
+          <li>
+            The switch has an accessible label provided by one of the following:
+            <ul>
+              <li>Visible text content contained within the element with role <code>switch</code>.</li>
+              <li>A visible label referenced by the value of <a href="#aria-labelledby" class="property-reference" >aria-labelledby</a> set on the element with role <code>switch</code>.</li>
+              <li><a href="#aria-label" class="property-reference">aria-label</a> set on the element with role <code>switch</code>.</li>
+            </ul>
+          </li>
+          <li>When <code>on</code>, the switch element has state <a href="#aria-checked" class="state-reference" >aria-checked</a> set to <code>true</code>.</li>
+          <li>When <code>off</code>, the switch element has state <a href="#aria-checked" class="state-reference" >aria-checked</a> set to <code>false</code>.</li>
+          <li>If the switch element is an HTML <code>input[type="checkbox"]</code>, it uses the HTML <code>checked</code> attribute instead of the <code>aria-checked</code> property.</li>
+          <li>If a set of switches is presented as a logical group with a visible label, either:
+            <ul>
+              <li>The switches are included in an element with role <a href="#group" class="role-reference" >group</a> that has the property <a href="#aria-labelledby" class="property-reference" >aria-labelledby</a> set to the ID of the element containing the group label.</li>
+              <li>The set is contained in an HTML <code>fieldset</code> and the label for the set is contained in an HTML <code>legend</code> element.</li>
+            </ul>
+          </li>
+          <li>If the presentation includes additional descriptive static text relevant to a switch or switch group, the switch or switch group has the property <a href="#aria-describedby" class="property-reference">aria-describedby</a> set to the ID of the element containing the description.</li>
+        </ul>
+      </section>
+    </section>
+
     <section class="widget" id="table">
       <h3>Table</h3>
       <p>