Skip to content

Commit

Permalink
Add form design pattern for required, invalid, instructions, and erro…
Browse files Browse the repository at this point in the history 
…r feedback (pull #721)

For issue #252, initial draft of design pattern for form instructions, error feedback, required, and invalid form controls.
  • Loading branch information
@jongund @mcking65
jongund authored and mcking65 committed Jun 25, 2018
1 parent 4ce958c commit ebce5bd
Showing 1 changed file with 63 additions and 101 deletions.
164 changes: 63 additions & 101 deletions aria-practices.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1091,140 +1091,102 @@ <h4>WAI-ARIA Roles, States, and Properties</h4>
</section>
</section>

<section class="widget" id="feed">
<h3>Feed</h3>
<p>
A <a href="#feed" class="role-reference">feed</a> is a section of a page that automatically loads new sections of content as the user scrolls.
The sections of content in a feed are presented in <a href="#article" class="role-reference">article</a> elements.
So, a feed can be thought of as a dynamic list of articles that often appears to scroll infinitely.
</p>
<p>
The feature that most distinguishes feed from other ARIA patterns that support loading data as users scroll, e.g., a <a href="#grid">grid</a>, is that a feed is a structure, not a widget.
Consequently, assistive technologies with a reading mode, such as screen readers, default to reading mode when interacting with feed content.
However, unlike most other WAI-ARIA structures, a feed establishes an interoperability contract between the web page and assistive technologies.
The contract governs scroll interactions so that assistive technology users can read articles, jump forward and backward by article, and reliably trigger new articles to load while in reading mode.
</p>
<p>
For example, a product page on a shopping site may have a related products section that displays five products at a time.
As the user scrolls, more products are requested and loaded into the DOM.
While a static design might include a next button for loading five more products, a dynamic implementation that automatically loads more data as the user scrolls simplifies the user experience and reduces the inertia associated with viewing more than the first five product suggestions.
But, unfortunately when web pages load content dynamically based on scroll events, it can cause usability and interoperability difficulties for users of assistive technologies.
</p>

<section class="widget" id="disclosure">
<h3>Disclosure (Show/Hide)</h3>
<p>
The feed pattern enables reliable assistive technology reading mode interaction by establishing the following interoperability agreement between the web page and assistive technologies:
A disclosure is a <a href="#button">button</a> that controls visibility of a section of content.
When the controlled content is hidden, it is often styled as a typical push button with a right-pointing arrow or triangle to hint that activating the button will display additional content.
When the content is visible, the arrow or triangle typically points down.
</p>
<ol>
<li>In the context of a feed, the web page code is responsible for:

<section class="notoc">
<h4>Examples</h4>
<ul>
<li><a href="examples/disclosure/disclosure-img-long-description.html">Disclosure (Show/Hide) of Image Description</a></li>
<li><a href="examples/disclosure/disclosure-faq.html">Disclosure (Show/Hide) of Answers to Frequently Asked Questions</a></li>
</ul>
</section>

<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>When the disclosure control has focus:</p>
<ul>
<li><kbd>Enter</kbd>: activates the disclosure control and toggles the visibility of the disclosure content.</li>
<li><kbd>Space</kbd>: activates the disclosure control and toggles the visibility of the disclosure content.</li>
</ul>
</section>

<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The element that shows and hides the content has role <a href="#button" class="role-reference">button</a>.</li>
<li>
Appropriate visual scrolling of the content based on which article contains DOM focus.
When the content is visible, the element with role <code>button</code> has
<a href="#aria-expanded" class="state-reference">aria-expanded</a>
set to <code>true</code>.
When the content area is hidden, it is set to <code>false</code>.
</li>
<li>Loading or removing feed articles based on which article contains DOM focus.</li>
<li>
Optionally, the element with role <code>button</code> has a value specified for
<a href="#aria-controls" class="property-reference">aria-controls</a>
that refers to the element that contains all the content that is shown or hidden.
</li>
</ul>
</li>
<li>In the context of a feed, assistive technologies with a reading mode are responsible for:
<ul>
<li>Indicating which article contains the reading cursor by ensuring the article element or one of its descendants has DOM focus.</li>
<li>providing reading mode keys that move DOM focus to the next and previous articles.</li>
<li>Providing reading mode keys for moving the reading cursor and DOM focus past the end and before the start of the feed.</li>
</ul>
</li>
</ol>
<p>
Thus, implementing the feed pattern allows a screen reader to reliably read and trigger the loading of feed content while staying in its reading mode.
</p>

</section>
</section>

<section class="widget" id="forms">
<h3>Forms: Required, Invalid, Instructions and Error Feedback</h3>
<p>
Another feature of the feed pattern is its ability to facilitate skim reading for assistive technology users.
Web page authors may provide both an accessible name and description for each article.
By identifying the elements inside of an article that provide the title and the primary content, assistive technologies can provide functions that enable users to jump from article to article and efficiently discern which articles may be worthy of more attention.
In addition to form controls and widget having a label to describe their purpose with the form, form controls often have additional information about including whether a control is required, has instructions, has an invalid value and visible error feedback for invalid values. NOTE: In general authors should creaet form that minimize invalid values by preventing the user form entering invalid values.
</p>

<section class="notoc">
<h4>Example</h4>
<p>
<a href="examples/feed/feed.html">Example Implementation of Feed Pattern</a>
</p>
<ul>
<li><a href="examples/popup-error/popup-error-1.html">Pizza ordering form with popup errors and instructions</a></li>
<li><a href="examples/popup-error/popup-error-2.html">Credit card form with popup errors and instructions</a></li>
</ul>
</section>

<section class="notoc">
<h4>Keyboard Interaction</h4>
<p>
The feed pattern is not based on a desktop GUI widget so the <code>feed</code> role is not associated with any well-established keyboard conventions.
Supporting the following, or a similar, interface is recommended.
</p>
<p>When focus is inside the feed:</p>
<p>When focus is inside the form:</p>
<ul>
<li><kbd>Page Down</kbd>: Move focus to next article.</li>
<li><kbd>Page Up</kbd>: Move focus to previous article.</li>
<li><kbd>Control + End</kbd>: Move focus to the first focusable element after the feed.</li>
<li><kbd>Control + Home</kbd>: Move focus to the first focusable element before the feed.</li>
<li><kbd>Tab</kbd>: Move focus to next form control.</li>
<li><kbd>Shift + Tab</kbd>: Move focus to previous form control.</li>
</ul>
<ol class="note">
<li>Due to the lack of convention, providing easily discoverable keyboard interface documentation is especially important.</li>
<li>
In some cases, a feed may contain a nested feed.
For example, an article in a social media feed may contain a feed of comments on that article.
To navigate the nested feed, users first move focus inside the nested feed.
Options for supporting nested feed navigation include:
<ul>
<li>
Users move focus into the nested feed from the content of the containing article with <kbd>Tab</kbd>.
This may be slow if the article contains a significant number of links, buttons, or other widgets.
</li>
<li>Provide a key for moving focus from the elements in the containing article to the first item in the nested feed, e.g., <kbd>Alt + Page Down</kbd>.</li>
<li>To continue reading the outer feed, <kbd>Control + End</kbd> moves focus to the next article in the outer feed.</li>
</ul>
</li>
<li>In the rare circumstance that a feed article contains a widget that uses the above suggested keys, the feed navigation key will operate the contained widget, and the user needs to move focus to an element that does not utilize the feed navigation keys in order to navigate the feed.</li>
</ol>
</section>

<section class="notoc">
<h4>WAI-ARIA Roles, States, and Properties</h4>
<ul>
<li>The element that contains the set of feed articles has role <a href="#feed" class="role-reference">feed</a>.</li>
<li>
If the feed has a visible title, the <code>feed</code> element has <a href="#aria-labelledby" class="property-reference">aria-labelledby</a> referring to the element containing the title.
Otherwise, the <code>feed</code> element has a label specified with <a href="#aria-label" class="property-reference">aria-label</a>.
</li>
<li>
Each unit of content in a feed is contained in an element with role <a href="#article" class="role-reference">article</a>.
All content inside the feed is contained in an <code>article</code> element.
</li>
<li>
Each <code>article</code> element has
<a href="#aria-labelledby" class="property-reference">aria-labelledby</a>
referring to elements inside the article that can serve as a distinguishing label.
</li>
<li>
It is optional but strongly recommended for each <code>article</code> element to have
<a href="#aria-describedby" class="property-reference">aria-describedby</a>
referring to one or more elements inside the article that serve as the primary content of the article.
<em>Required:</em> HTML form controls that are required should use the HTML5 <code>required</code> attribute. For custom widgets that are <em>required</em> use <a href="#aria-required" class="property-reference">aria-required=<q>true</q></a> property.
</li>
<li>
Each <code>article</code> element has
<a href="#aria-posinset" class="property-reference">aria-posinset</a>
set to a value that represents its position in the feed.
<em>Instructions:</em> If a form control or widget has visible instructions use the <a href="#aria-describedby" class="property-reference">aria-describedby</a> property to refer to the element containing the instructions.
</li>
<li>
Each <code>article</code> element has
<a href="#aria-setsize" class="property-reference">aria-setsize</a>
set to a value that represents either the total number of articles that have been loaded or the total number in the feed,
depending on which value is deemed more helpful to users.
If the total number in the feed is undetermined, it can be represented by a <code>aria-setsize</code> value of <code>-1</code>.
<em>Invalid Value:</em> If a form control or widget has an invalid value use <a href="#aria-invalid" class="property-reference">aria-invalid=<q>true</q></a> property identify the invalid value to assistive technology.
</li>
<li>
When <code>article</code> elements are being added to or removed from the <code>feed</code> container,
and if the operation requires multiple DOM operations,
the <code>feed</code> element has
<a href="#aria-busy" class="state-reference">aria-busy</a>
set to <code>true</code> during the update operation.
Note that it is extremely important that <code>aria-busy</code> is set to <code>false</code> when the operation is complete or the changes may not become visible to some assistive technology users.
</li>
<em>Error Feedback:</em>
<ul>
<li>If a form control or widget has <em>visible error feedback</em> use the <a href="#aria-errormessage" class="property-reference">aria-errormessage</a> property to refer to the element containing the error feedback.
</li>
<li>
If a form control or widget has <em>visible error feedback</em> use the <a href="#aria-errormessage" class="role-reference">status</a> role on the container element to have the error information automatically spoken when the error information appears
</li>
</ul>
</li>
</ul>
</section>
</section>


<section class="widget" id="grid">
<h3>Grids : Interactive Tabular Data and Layout Containers</h3>

Expand Down

0 comments on commit ebce5bd

Please sign in to comment.