Merge pull request #217 from wpaccessibility/157-group-form-fields

Author: GaryJones

assets/images/fieldset-radio-buttons.png

@@ -76,7 +76,7 @@ There are 3 levels of accessibility:
 
 TODO: add content about version
 
-TODO: add info about different principle/ guideline/succes criteria/technique.
+TODO: add info about different principle/ guideline/Success Criteria/technique.
 
 Most European Union and many other countries use the accessibility standard WCAG 2.1 AA or equivalent for their government websites. Some countries require compliance with these guidelines for commercial websites, so the accessibility team uses these guidelines to improve WordPress core. [Overview of government accessibility laws and policies](Web Accessibility Laws & Policies) from the Web Accessibility Initiative.
 

docs/start/wcag-intro/index.md

@@ -81,7 +81,7 @@ The accessibility tree of Firefox shows the following relevant information: The
 ![Screenshot accessible name link in FireFox]({{site.baseurl}}/assets/images/accessible-name-link.png)
 
 
-## WCAG Succes Criteria
+## WCAG Success Criteria
 
 Giving interactive elements a well-defined, accessible name is necessary to meet the WCAG success criteria:
 

docs/topics/code/accessible-name/index.md

@@ -44,74 +44,42 @@ It's possible to add multiple descriptions to one form field. You can combine th
         autocomplete="name" />
 ```
 
-## Connect the description of a fieldset to the fieldset element
-
-Radio buttons, checkboxes, and other groups of related fields (like addresses) can be grouped in fieldsets. The question or the subject will be the `legend`. Place the description below the legend just above the first label/form field. The description is linked to the fieldset element with `aria-describedby`.
-
-## Example
-
-![Screenshot of a fieldset, with a legend and 2 radio buttons]({{site.baseurl}}/assets/images/fieldset-description.png)
-
-IN HTML, simplified
-
-```html
-<fieldset aria-describedby="description-log-in">
-  <legend>Do you want to log in?</legend>
-  <p id="description-log-in">
-      When you log in, your details are already filled in, and we can help you faster.
-  </p>
-    <input
-      id="log-in-yes"
-      type="radio"
-      name="log-in"
-      value="yes"
-    />
-    <label for="og-in-yes">Yes</label>
-
-    <input
-      id="log-in-no"
-      type="radio"
-      name="log-in"
-      value="no"
-    />
-    <label for="log-in-no">No</label>
-
-</fieldset>
-```
+{: .info }
+For the documentation about descriptions in fieldsets read [Description with a fieldset]({{site.baseurl}}/docs/topics/forms/fieldsets/fieldset-descriptions/).
 
 ## Examples
 
-{: .do }
-Connect a description to the form field, using aria-describedby.
+{: .dont }
+No connection between a form field and its description.
 
 ```html
+<!-- do not copy, this is incorrect -->
 <label for="new-password">New password</label>
-<p id="description-new-password">
+<p>
     Choose a password of at least 8 characters long.
 </p>
 <input
   id="new-password"
   type="password"
   name="new-password"
-  aria-describedby="description-new-password"
   autocomplete="new-password"
 />
 ```
 
-{: .dont }
-No connection between a form field and its description.
+{: .do }
+Connection between a form field and its description.
 
 ```html
-<!-- do not copy, this is incorrect -->
 <label for="new-password">New password</label>
-<p>
+<p id="new-password-description">
     Choose a password of at least 8 characters long.
 </p>
 <input
   id="new-password"
   type="password"
   name="new-password"
   autocomplete="new-password"
+  aria-describedby="new-password-description"
 />
 ```
 

docs/topics/forms/descriptions/connect-description.md

@@ -20,11 +20,13 @@ In this [demo video](https://www.youtube.com/watch?v=6brKmJfDtNQ), VoiceOver in
 
 What are the options for adding information and explanations to a form and its input fields? Follow the [description decision tree]({{site.baseurl}}/docs/topics/forms/descriptions/).
 
-## Related WCAG Success Criteria
+
+## WCAG Success Criteria
 
  - [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/quickref/#info-and-relationships).
  - [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/quickref/#labels-or-instructions).
 
+
 ## Resources
 
 - NL Design System [Guidelines for web forms (Dutch content)](https://nldesignsystem.nl/richtlijnen/formulieren/).

docs/topics/forms/descriptions/content-description.md

@@ -44,7 +44,7 @@ Rich text in this context means: additional structure or interactive functionali
 **Yes**: Consider a multistep form, where the information is placed directly above the form for each step.  
 **No**: Rewrite the description so that it only contains plain text. This ensures that all users can read the information.
 
-## Related WCAG Success Criteria
+## WCAG Success Criteria
 
 - [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/quickref/#info-and-relationships).
 - [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/quickref/#labels-or-instructions).

docs/topics/forms/descriptions/decision-tree-description.md

@@ -0,0 +1,76 @@
+---
+title: Fieldset description
+layout: default
+parent: Group form fields
+nav_order: 3
+description: Connect the description of a fieldset to the fieldset element
+---
+
+# Description with a fieldset
+
+Radio buttons, checkboxes, and other groups of related fields (like addresses) can be grouped in fieldsets. The question or the subject will be the `legend`. Place the description below the legend just above the first label/form field. The description is linked to the fieldset element with `aria-describedby`.
+
+## Example
+
+![Screenshot of a fieldset, with a legend and 2 radio buttons]({{site.baseurl}}/assets/images/fieldset-description.png)
+
+In HTML, simplified
+
+```html
+<fieldset aria-describedby="description-log-in">
+  <legend>Do you want to log in?</legend>
+  <p id="description-log-in">
+      When you log in, your details are already filled in, and we can help you faster.
+  </p>
+    <input
+      id="log-in-yes"
+      type="radio"
+      name="log-in"
+      value="yes"
+    />
+    <label for="log-in-yes">Yes</label>
+
+    <input
+      id="log-in-no"
+      type="radio"
+      name="log-in"
+      value="no"
+    />
+    <label for="log-in-no">No</label>
+
+</fieldset>
+```
+
+## Examples
+
+{: .do }
+Connect a description to the form field, using aria-describedby.
+
+```html
+<label for="new-password">New password</label>
+<p id="description-new-password">
+    Choose a password of at least 8 characters long.
+</p>
+<input
+  id="new-password"
+  type="password"
+  name="new-password"
+  aria-describedby="description-new-password"
+  autocomplete="new-password"
+/>
+```
+
+## WCAG Success Criteria for descriptions
+
+A description is optional, but it can help users to understand better what they need to fill out.
+Then a description with a fieldset is necessary to meet the WCAG success criterion [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/quickref/#labels-or-instructions) (Level AA).
+
+## Related pages in this documentation
+
+- [Group form fields]({{site.baseurl}}docs/topics/forms/fieldsets/).
+- [Fieldset legend]({{site.baseurl}}/docs/topics/forms/fieldsets/legend/).
+
+## Resources
+
+- MDN: [ARIA: aria-describedby attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby).
+- NL Design System [Guidelines for web forms (Dutch content)](https://nldesignsystem.nl/richtlijnen/formulieren/).

docs/topics/forms/fieldsets.md

@@ -0,0 +1,76 @@
+---
+title: Group form fields
+layout: default
+parent: Web forms
+nav_order: 5
+description: Use fieldset and legend to group form fields.
+---
+
+# Fieldset and legend to group form fields
+
+Group form fields that belong together inside a `<fieldset>` with a descriptive `<legend>`. The advantage to this is that the form fields are grouped together both visually and semantically, making the design match the code.
+
+The `fieldset` and `legend` elements are the native HTML way to group fields. When a screen reader enters a fieldset, the `legend` of that group will be announced. This is a helpful way of grouping related fields together, such as differentiating between an order address and a shipping address; but is critical when grouping radio buttons and checkboxes.
+
+
+<img src="{{site.baseurl}}/assets/images/fieldset-radio-buttons.png" alt="Screenshot of grouped radio buttons that let you select the best color">
+
+
+```html
+<fieldset>
+    
+    <legend>Which is the best color?</legend>
+
+    <input name="colorOption" type="radio" id="purple" value="purple" />
+    <label for="purple">Purple</label>
+    
+    <input name="colorOption" type="radio" id="aubergine" value="aubergine" />
+    <label for="aubergine">Aubergine</label>
+    
+    <input name="colorOption" type="radio" id="magenta" value="magenta" />
+    <label for="magenta">Magenta</label>
+    
+    <input name="colorOption" type="radio" id="all" value="all" />
+    <label for="all">All of the above</label>
+
+</fieldset>
+```
+
+WCAG requires that the structure and relationships are programmatically determinable, and fieldset/legend is one way to meet that. The same can be achieved by using `role="group"` and `aria-labelledby`. But always keep the [first rule of ARIA use](https://www.w3.org/TR/using-aria/#rule1) in mind:
+
+> If you can use a native HTML element or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.
+
+## Example using ARIA (not preferred)
+
+```html
+<div role="group" aria-labelledby="dummy-legend">
+    
+    <h2 id="dummy-legend">Which is the best color?</h2>
+
+    <input name="colorOption" type="radio" id="purple" value="purple" />
+    <label for="purple">Purple</label>
+    
+    <input name="colorOption" type="radio" id="aubergine" value="aubergine" />
+    <label for="aubergine">Aubergine</label>
+    
+    <input name="colorOption" type="radio" id="magenta" value="magenta" />
+    <label for="magenta">Magenta</label>
+    
+    <input name="colorOption" type="radio" id="all" value="all" />
+    <label for="all">All of the above</label>
+
+</div>
+```
+
+## WCAG Success Criteria for naming grouped form fields
+
+Naming grouped form fields is necessary to meet the WCAG success criteria:
+
+- [1.3.1 Info and relationships](https://www.w3.org/WAI/WCAG22/quickref/#info-and-relationships) (Level A).
+- [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG22/quickref/#labels-or-instructions) (Level AA).
+
+## Resources
+
+- W3C: [Grouping Controls](https://www.w3.org/WAI/tutorials/forms/grouping/)
+- NL Design System: [Guidelines for web forms (Dutch content)](https://nldesignsystem.nl/richtlijnen/formulieren/).
+- MDN: [The Field Set element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/fieldset).