Skip to content

Commit

Permalink
Make Benefits consistently a top-level section with h2 in source files (
Browse files Browse the repository at this point in the history 
#3939)

Fixes #3924.

Also addresses the Label in Name instance in #3922.

The diff will be much easier to compare with whitespace ignored
(`?w=1`).

This amends all instances of the Benefits section in Understanding pages
to be a top-level section with a level-2 heading.

I've tested this with both the XSLT and Eleventy build processes to
confirm this doesn't actually change any content, since both build
processes already ensure Benefits is a top-level section with level-2
heading. The one exception is the removal of the redundant first
Benefits section in Understanding 2.5.3 Label in Name, which only
meaningfully affects the XSLT process, as the Eleventy process already
worked around that issue.

Note: I don't know what `identify-changes.html` is supposed to be, but I
updated it regardless; it seems to only contain template boilerplate and
is not linked from anywhere.

Co-authored-by: Mike Gower <mikegower@gmail.com>
  • Loading branch information
@kfranqueiro @mbgower
kfranqueiro and mbgower authored Aug 27, 2024
1 parent 70b32b2 commit 1906ca8
Show file tree
Hide file tree
Showing 13 changed files with 88 additions and 110 deletions.
29 changes: 14 additions & 15 deletions understanding/21/animation-from-interactions.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,20 @@ <h2>Intent</h2>

<p class="note">The impact of animation on people with vestibular disorders can be quite severe. Triggered reactions include nausea, migraine headaches, and potentially needing bed rest to recover.</p>

<p><strong>How can a website reduce the chances of triggering a vestibular disorder?</strong> Choose any one of the following solutions. Avoid using unnecessary animation. Provide a control for users to turn off non-essential animations from user interaction. Take advantage of the reduce motion feature in the user agent or operating system.</p>

<p><strong>What about movement caused by a user scrolling a page?</strong> Moving new content into the viewport is essential for scrolling. The user controls the essential scrolling movement so it is allowed. Only add non-essential animation to the scrolling interaction in a responsible way. Always give users the ability to turn off unnecessary movement.</p>

<section id="benefits">
<h3>Benefits</h3>
<ul>
<li><strong>Vestibular Disorder</strong>
<ul>
<li>People with vestibular disorders need control over movement triggered by interactions. Non-essential movement can trigger vestibular disorder reactions. Vestibular (inner ear) disorder reactions include distraction, dizziness, headaches and nausea.</li>
<li>Persona Quote: "Stop that extra movement! You are making me so dizzy I cannot concentrate. Now I have to turn off my computer and go lie down."</li>
</ul>
</li>
</ul>
</section>
<p><strong>How can a website reduce the chances of triggering a vestibular disorder?</strong> Choose any one of the following solutions. Avoid using unnecessary animation. Provide a control for users to turn off non-essential animations from user interaction. Take advantage of the reduce motion feature in the user agent or operating system.</p>

<p><strong>What about movement caused by a user scrolling a page?</strong> Moving new content into the viewport is essential for scrolling. The user controls the essential scrolling movement so it is allowed. Only add non-essential animation to the scrolling interaction in a responsible way. Always give users the ability to turn off unnecessary movement.</p>
</section>
<section id="benefits">
<h2>Benefits</h2>
<ul>
<li><strong>Vestibular Disorder</strong>
<ul>
<li>People with vestibular disorders need control over movement triggered by interactions. Non-essential movement can trigger vestibular disorder reactions. Vestibular (inner ear) disorder reactions include distraction, dizziness, headaches and nausea.</li>
<li>Persona Quote: "Stop that extra movement! You are making me so dizzy I cannot concentrate. Now I have to turn off my computer and go lie down."</li>
</ul>
</li>
</ul>
</section>
<section id="examples">
<h2>Examples</h2>
Expand Down
42 changes: 20 additions & 22 deletions understanding/21/character-key-shortcuts.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,28 +19,26 @@ <h2>In brief</h2>

<section id="intent">
<h2>Intent</h2>
<p>The intent of this Success Criterion is to reduce accidental activation of keyboard shortcuts. Character key shortcuts work well for many keyboard users. However, they can be inappropriate and frustrating for speech input users whose dictation is interpreted as strings of letters, and for keyboard users who are prone to accidentally hit keys. To rectify this issue, authors need to allow users to turn off or reconfigure shortcuts that are made up of only character keys.</p>
<div class="note">
<p>Even though this Success Criterion refers to <q>character keys</q>, note that it's not relevant whether a shortcut can be activated using a single physical key on a keyboard, or if it requires a combination of keys to be pressed. For instance, on most full-size US and UK keyboard, the <kbd>?</kbd> (question mark) symbol is accessed using <kbd><kbd>Shift</kbd>+<kbd>/</kbd></kbd> (forward slash key next to the right-hand <kbd>Shift</kbd> key). On a UK keyboard, in Windows, the <kbd>é</kbd> (lowercase "e" with an acute accent) requires the use of <kbd><kbd>AltGr</kbd>+<kbd>e</kbd></kbd>. The specific key combination required for certain characters will also vary depending on the user's keyboard layout. However, shortcuts that use these characters still fall under the requirements of this Success Criterion. What matters is that a shortcut relies on a printable character (letters, punctuation, numbers, symbol characters), and not the number of physical keyboard keys that users need to press to trigger it.</p>
</div>
<div class="note">
<p>The Success Criterion also applies to situations where a shortcut is based on a <em>sequence</em> of character keys – for example, pressing <kbd>G</kbd> and then <kbd>A</kbd> in quick succession to trigger an action. While the individual character key presses don't immediately trigger the action, overall these types of shortcuts still rely on a series of <em>character keys</em>.</p>
</div>
<p>This success criterion doesn't affect components such as listboxes and drop-down menus. Although these components contain values (words) that may be selected by one or more character keys, the shortcuts are only active when the components have focus. Other components such as menus may be accessed or opened with a single non-character shortcut (e.g., <kbd>Alt</kbd> or <kbd><kbd>Alt</kbd>+<kbd>F</kbd></kbd>) before pressing a single character key to select an item. This makes the full path to invoking a menu a two-step shortcut that includes a non-printable key. <a href="https://www.w3.org/TR/html5/single-page.html#the-accesskey-attribute">Accesskeys</a> are also not affected because they are generally (depending on the user agent) activated using modifier keys.</p>
<h3>Background on the mechanics of speech input</h3>
<p>Speech Input users generally work in a single mode where they can use a mix of dictation and speech commands. This works well because the user knows to pause before and after commands, and commands are usually at least two words long. So, for instance, a user might say a bit of dictation, such as "the small boat", then pause, and say a command to delete that dictation, such as "Delete Line". In contrast, if the user were to say the two phrases together without a pause, the whole phrase would come out as dictation (i.e., "the small boat delete line"). Although speech input programs often include modes that listen only for dictation or only for commands, most speech users use the all-encompassing mode all the time because it is a much more efficient workflow. It could decrease command efficiency significantly if users were to change to command mode and back before and after issuing each command.</p>
<p>Speech users can also speak most keyboard commands (e.g., "press Control Foxtrot") without any problems. If the website or app is keyboard enabled, the speech user can also write a native speech macro that calls the keyboard command, such as "This Print" to carry out <kbd><kbd>Ctrl</kbd>+<kbd>P</kbd></kbd>.</p>
<p>Single-key shortcuts are the exception. While using single letter keys as controls might be appropriate and efficient for many keyboard users, single-key shortcuts are disastrous for speech users. The reason for this is that when only a single key is used to trip a command, a spoken word can become a barrage of single-key commands if the cursor focus happens to be in the wrong place.</p>
<p>For example, a speech-input user named Kim has her cursor focus in the main window of a web mail application that uses common keyboard shortcuts to navigate (<kbd>k</kbd>), archive (<kbd>y</kbd>) and mute messages (<kbd>m</kbd>). A coworker named Mike enters her office and says "Hey Kim" and her microphone picks that up. The Y of "hey" archives the current message. K in "Kim" moves down one conversation and M mutes a message or thread. And, if Kim looks up and says "Hey Mike" without remembering to turn off the microphone, the same three things happen in a different sequence.</p>
<p>A user interacting with a webpage or web app that doesn't use single-character shortcuts doesn't have this problem. Inadvertent strings of characters from the speech application are not interpreted as shortcuts if a modifier key is required. A speech user filling in a text input form may find that a phrase that is accidentally picked up by the speech microphone results in stray text being entered into the field, but that is easily seen and undone. The Resources section of this page contains links to videos demonstrating these types of issues.</p>
<section id="benefits">
<h3>Benefits</h3>
<ul>
<li>Speech users will be able to turn off single-key shortcuts so they can avoid accidentally firing batches of them at once. This will allow speech users to make full use of programs that offer single-key shortcuts to keyboard users.</li>
<li>Keyboard-only users who have dexterity challenges can also be prone to accidentally hitting keys. Those users would be able to avoid problematic single character shortcuts by turning them off or modifying them to include at least one non-character key.</li>
<li>Allowing <em>all</em> shortcut keys to be remapped can help users with some cognitive disabilities, since the same shortcuts can be assigned to perform the same actions across different applications.</li>
</ul>
</section>

<p>The intent of this Success Criterion is to reduce accidental activation of keyboard shortcuts. Character key shortcuts work well for many keyboard users, but are inappropriate and frustrating for speech input users &#8212; whose means of input is strings of letters &#8212; and for keyboard users who are prone to accidentally hit keys.
To rectify this issue, authors need to allow users to turn off or reconfigure shortcuts that are made up of only character keys.
</p>
<p>Note that this success criterion doesn't affect components such as listboxes and drop-down menus. Although these components contain values (words) that may be selected by one or more character keys, the shortcuts are only active when the components have focus. Other components such as menus may be accessed or opened with a single non-character shortcut (e.g., Alt or Alt+F) before pressing a single character key to select an item. This makes the full path to invoking a menu a two-step shortcut that includes a non-printable key. <a href="https://www.w3.org/TR/html5/single-page.html#the-accesskey-attribute">Accesskeys</a> are also not affected because they include modifier keys.</p>
<h3>Background on the mechanics of speech input:</h3>
<p>Speech Input users generally work in a single mode where they can use a mix of dictation and speech commands. This works well because the user knows to pause before and after commands, and commands are usually at least two words long. So, for instance, a user might say a bit of dictation, such as "the small boat", then pause, and say a command to delete that dictation, such as "Delete Line". In contrast, if the user were to say the two phrases together without a pause, the whole phrase would come out as dictation (i.e., "the small boat delete line"). Although speech input programs often include modes that listen only for dictation or only for commands, most speech users use the all-encompassing mode all the time because it is a much more efficient workflow. It could decrease command efficiency significantly if users were to change to command mode and back before and after issuing each command.</p>
<p>Speech users can also speak most keyboard commands (e.g., "press Control Foxtrot") without any problems. If the website or app is keyboard enabled, the speech user can also write a native speech macro that calls the keyboard command, such as "This Print" to carry out Ctrl+P.</p>
<p>Single-key shortcuts are the exception. While using single letter keys as controls might be appropriate and efficient for many keyboard users, single-key shortcuts are disastrous for speech users. The reason for this is that when only a single key is used to trip a command, a spoken word can become a barrage of single-key commands if the cursor focus happens to be in the wrong place.</p>
<p>For example, a speech-input user named Kim has her cursor focus in the main window of a web mail application that uses common keyboard shortcuts to navigate ("k"), archive ("y") and mute messages ("m"). A coworker named Mike enters her office and says "Hey Kim" and her microphone picks that up. The Y of "hey" archives the current message. K in "Kim" moves down one conversation and M mutes a message or thread. And, if Kim looks up and says "Hey Mike" without remembering to turn off the microphone, the same three things happen in a different sequence.</p>
<p>A user interacting with a webpage or web app that doesn't use single-character shortcuts doesn't have this problem. Inadvertent strings of characters from the speech application are not interpreted as shortcuts if a modifier key is required. A speech user filling in a text input form may find that a phrase that is accidentally picked up by the speech microphone results in stray text being entered into the field, but that is easily seen and undone. The Resources section of this page contains links to videos demonstrating these types of issues.</p>
</section>
<section id="benefits">
<h2>Benefits</h2>
<ul>
<li>Speech users will be able to turn off single-key shortcuts so they can avoid accidentally firing batches of them at once. This will allow speech users to make full use of programs that offer single-key shortcuts to keyboard users.</li>
<li>Keyboard-only users who have dexterity challenges can also be prone to accidentally hitting keys. Those users would be able to avoid problematic single character shortcuts by turning them off or modifying them to include at least one non-character key.</li>
<li>Allowing <em>all</em> shortcut keys to be remapped can help users with some cognitive disabilities, since the same shortcuts can be assigned to perform the same actions across different applications.</li>
</ul>

</section>
<section id="examples">
<h2>Examples</h2>
Expand Down
2 changes: 1 addition & 1 deletion understanding/21/concurrent-input-mechanisms.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ <h2>Intent</h2>
<p>Note: A touch-typing web application, which teaches users how to touch-type on a keyboard and/or measures their proficiency and speed, would be an example of an essential limitation to a particular input mechanism. </p>
</section>
<section id="benefits">
<h3>Benefits</h3>
<h2>Benefits</h2>
<ul>
<li>Users can interact with web content with whichever input mechanism is preferred and available to them.</li>
<li>Users may switch between input mechanisms when they desire or the circumstances require it.</li>
Expand Down
16 changes: 8 additions & 8 deletions understanding/21/identify-changes.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ <h1>Understanding {Shortname}</h1>
<section id="intent">
<h2>Intent</h2>
<p class="instructions">This section contains the main explanatory content of the Understanding. It explains why the Guideline or Success Criterion exists and, at a high level, how to meet it.</p>
<section id="benefits">
<h3>Benefits</h3>
<p class="instructions">This explains how following the success criterion benefits particular types of users with disabilities.</p>
<ul>
<li>Benefit</li>
</ul>
</section>
</section>
<section id="benefits">
<h2>Benefits</h2>
<p class="instructions">This explains how following the success criterion benefits particular types of users with disabilities.</p>
<ul>
<li>Benefit</li>
</ul>
</section>
<section id="examples">
<h2>Examples</h2>
Expand Down Expand Up @@ -74,4 +74,4 @@ <h2>Failure</h2>
</section>
</section>
</body>
</html>
</html>
13 changes: 0 additions & 13 deletions understanding/21/label-in-name.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,19 +90,6 @@ <h4>Text in parentheses</h4>
<p>It is important to mention parenthetical text in labels in the context of accessible name versus description. In common usage, text in parentheses is considered secondary but relevant to meaning. Users of speech recognition would not typically announce text in parentheses as part of the input name. For that reason, parenthetical text may be optionally considered a description and left out of the accessible name.</p>
<p>However, where parenthetical information provides important context, such as indication of a required field or limitations on what is allowed for input, this information must be provided programmatically in some other way to the user if that information is not included as part of the accessible name. For example, "Name (required)" and "Date (YYYY-MM-DD)" could accept "Name" and "Date" as the accessible names. However, in order to pass 1.3.1 Info &amp; Relationships, authors would need to programmatically surface both the required state and the limit on the allowed data formatting (in this example, eight integers fitting the YYYY-MM-DD pattern). The "required" state could be surfaced through the HTML <code>required</code> attribute or by using <code>aria-required="true"</code>. The allowed data formatting could be surfaced by being referenced using the <code>aria-describedby</code>) attribute.</p>
</section>


<section id="benefits">
<h2>Benefits</h2>

<ul>
<li>headings and instructions</li>
<li>group labels for sets of components (i.e., used with <code>legend</code>/<code>fieldset</code> or with role of <code>group</code> or <code>radiogroup</code>)</li>
</ul>
<p>Such textual information may constitute part of the component's <em>description</em>. So from both a programmatic viewpoint, and from the conservative tactic of only considering a label to be "adjacent text," neither headings, instructions, nor group 'labels' should normally be considered <strong>labels</strong> for the purpose of this Success Criterion.</p>
<p>It is important to note that the specification allows authors to override the name calculated through native semantics. Both <code>aria-label</code> and <code>aria-labelledby</code> take precedence in the name calculation, overriding the visible text as the accessible name even when the visible text label is programmatically associated with the control. For this reason, when a visible label already exists, <code>aria-label</code> should be avoided or used carefully, and <code>aria-labelledby</code> should be used as a supplement with care.</p>
<p>Finally, <code>aria-describedby</code> is not included in the Accessible Name computation (instead it is part of the Accessible Description computation). By convention, text associated with a control through <code>aria-describedby</code> is announced immediately after the accessible name by screen readers. Therefore, the context of headings, instructions, and group labels can be provided through the accessible description to assist users of screen readers without affecting the experience of those who navigate using speech recognition software.</p>
</section>
</section>

<section id="benefits">
Expand Down
Loading

0 comments on commit 1906ca8

Please sign in to comment.