[WNMGDS-2428] Add Dropdown a11y testing docs (#2605)

* Work Dan's new a11y testing docs into the dropdown page

And also style the `kbd` element

* More succinct key names and just as clear IMO

* Comment out this item because it's not something we can implement right now

* Fix broken form guidelines links

* Add periods at end of bullet points for consistency

packages/docs/content/components/autocomplete.mdx

@@ -67,7 +67,7 @@ The `<Autocomplete>` component also makes use of a text field, which can be cust
 - Don't use placeholder text in autocomplete fields. Try to write a descriptive label that identifies what the user is searching for. People who have cognitive or visual disabilities have additional problems with placeholder text.
 - The length of the text field provides a hint to users as to how much text to write. Do not ask users to write paragraphs of text in this component; use a `textarea` instead.
 
-**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/forms/)**
+**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/Forms/forms/)**
 
 ### Accessibility
 

packages/docs/content/components/checkbox.mdx

@@ -85,7 +85,7 @@ This component also makes use of form field styles, which can be customized by t
 - Avoid using negative language in labels as they can be counterintuitive. For example, “I want to receive a promotional email” instead of “I don’t want to receive promotional email.”
 - Use caution if you decide to set a default value. Setting a default value can discourage users from making conscious decisions, seem pushy, or alienate users who don’t fit into your assumptions. In addition, you'll never know if the user explicitly chose that option or just didn't notice the question. If you're unsure, leave nothing selected by default.
 
-**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/forms/)**
+**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/Forms/forms/)**
 
 ### Checked children and the expose within pattern
 
@@ -115,7 +115,7 @@ This component also makes use of form field styles, which can be customized by t
 
 ## Learn more
 
-- [Form Guidelines](/patterns/forms/)
+- [Form Guidelines](/patterns/Forms/forms/)
 - [GOV.UK Checkbox/Radio buttons discussion](https://paper.dropbox.com/doc/Radio-buttons-oIwWoxwBKClt5IXvDbnpF)
 - ["We've updated the radios and checkboxes on GOV.UK"](https://designnotes.blog.gov.uk/2016/11/30/weve-updated-the-radios-and-checkboxes-on-gov-uk/)
 - [Four steps for choosing form elements on the Web (PDF)](http://www.formsthatwork.com/files/Articles/dropdown.pdf)

packages/docs/content/components/dropdown.mdx

@@ -48,18 +48,64 @@ This component also makes use of some text input styles, which can be customized
 
 ### Usage
 
+- **Always use a label.** Make sure your dropdown has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the dropdown read “Select a state” by default).
 - **Make sure to test.** Test dropdowns thoroughly with members of your target audience. Several usability experts suggest they should be the “UI of last resort.” Many users find them confusing and difficult to use.
-- **Avoid dependent options.** Avoid making options in one dropdown menu change based on the input to another. Users often don’t understand how selecting an item in one impacts another.
 - **Use a good default.** When most users will (or should) pick a particular option, make it the selected default. **If a good default is not an option**, use a descriptive placeholder like `- Select a state -` as the selected default.
-- **Avoid auto-submission.** Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.
-
-**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/forms/)**
-
-### Accessibility
-
-- **Customize accessibly.** If you customize the dropdown, ensure it continues to meet the the [accessibility requirements that apply to all form controls](https://designsystem.digital.gov/components/form-controls/).
-- **Always use a label.** Make sure your dropdown has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the dropdown read “Select a state” by default).
-- **Avoid auto-submission.** Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.
+- **Avoid using dropdown to change context.** Don't automatically change content on the page or navigate when a user selects a different value. [According to WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/on-input), you should warn users if changing a form control changes context.
+- **Avoid dependent options.** Avoid making options in one dropdown menu change based on the input to another. Users often don’t understand how selecting an item in one impacts another.
+- **Order alphabetically.** Present the options in alphabetical order as the default ordering when possible.
+
+**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/Forms/forms/)**
+
+### Accessibility testing
+
+#### General observations
+
+- The dropdown list should be closed by default.
+- When the dropdown list is displayed, `aria-expanded` is set to `true` and, conversely, set to `false` when the listbox is closed.
+- The dropdown button contains `aria-haspopup="listbox"`, while the listbox contains a `role="listbox"`.
+- The dropdown button contains an `aria-controls` attribute which maps to an `id` on the listbox.
+- Selected option text that is longer than the dropdown button will be truncated, but the full text of that option will be displayed on multiple lines in the dropdown list.
+
+#### Keyboard Testing
+
+- When the Dropdown is closed and has focus
+    - Users can open the listbox by pressing <kbd>Space</kbd>, <kbd>Enter</kbd>, <kbd>Down</kbd>, <kbd>Up</kbd>, <kbd>Alt</kbd> + <kbd>Up</kbd> or <kbd>Alt</kbd> + <kbd>Down</kbd>. When the listbox opens it highlights the current option
+    - If a user begins typing then the listbox will open and will highlight the first option that matches the typed character.
+    - If the same character is typed in succession, visual focus cycles among the options starting with that character.
+- When the Dropdown is open
+    - <kbd>Escape</kbd> key closes the options, sets visual focus on the combobox, and retains the current value.
+    - <kbd>Up</kbd> and <kbd>Down</kbd> keys should cycle through options.
+    - <kbd>Enter</kbd> key selects the currently focused option and closes the menu.
+    - <kbd>Space</kbd> key selects the currently focused option and closes the menu.
+    - If the same character is typed in succession, visual focus cycles among the options starting with that character.
+    - <kbd>Home</kbd> key moves visual focus to the first option.
+    - <kbd>End</kbd> key moves visual focus to the last option.
+
+#### Screen reader testing
+
+- When I navigate to the Dropdown
+    - If hints or errors are present, they are read.
+- When the listbox is displayed
+    - I use the arrow keys to select an option and I hear the selected option is changed.
+    - I select an option with the Enter or Space key and hear the selected option.
+
+<!-- [We need to implement this] I use the escape key and I hear it collapse and focus moves to the select -->
+
+#### Mobile screen reader testing
+- I can swipe to focus on the component.
+- I can hear the purpose of the element.
+- It identifies itself as a combobox.
+- I hear hints or errors are read.
+- I hear it indicate which option is selected.
+
+#### Pointer device testing
+- I select anywhere inside the the dropdown button to display or hide the listbox.
+- I select an option by clicking anywhere inside the option list.
+- I select an option and the `aria-selected` attribute is added to the currently selected option.
+- If using a mouse, a hover state (highlighted state) is visible over each non-selected list options as I drag the mouse over them.
+- I select an option and that option is displayed in the dropdown component and the listbox is hidden.
+- I select anywhere outside the component to close the listbox when it is displaying.
 
 ### Related patterns
 
@@ -68,7 +114,7 @@ This component also makes use of some text input styles, which can be customized
 
 ## Learn more
 
-- [Form Guidelines]/guidelines/forms/)
+- [Form Guidelines](/patterns/Forms/forms/)
 - [Asking for a date of birth](https://designnotes.blog.gov.uk/2013/12/05/asking-for-a-date-of-birth/)
 - [Four steps for choosing form elements on the Web (PDF)](http://www.formsthatwork.com/files/Articles/dropdown.pdf)
 - [Dropdowns: Design Guidelines](https://www.nngroup.com/articles/drop-down-menus/)

packages/docs/content/components/form-label.mdx

@@ -75,7 +75,7 @@ The following CSS variables can be overridden to customize Form components:
 
 ## Learn More
 
-- [Form Guidelines](/patterns/forms/)
+- [Form Guidelines](/patterns/Forms/forms/)
 
 ## Component maturity
 

packages/docs/content/components/radio.mdx

@@ -84,7 +84,7 @@ This component also makes use of form field styles, which can be customized by t
 - Avoid using negative language in labels as they can be counterintuitive. For example, “I want to receive a promotional email” instead of “I don’t want to receive promotional email.”
 - Use caution if you decide to set a default value. Setting a default value can discourage users from making conscious decisions, seem pushy, or alienate users who don’t fit into your assumptions. In addition, you'll never know if the user explicitly chose that option or just didn't notice the question. If you're unsure, leave nothing selected by default.
 
-**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/forms/)**
+**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/Forms/forms/)**
 
 ### Checked children and the expose within pattern
 
@@ -114,7 +114,7 @@ This component also makes use of form field styles, which can be customized by t
 
 ## Learn more
 
-- [Form Guidelines](/patterns/forms/)
+- [Form Guidelines](/patterns/Forms/forms/)
 - [GOV.UK Checkbox/Radio buttons discussion](https://paper.dropbox.com/doc/Radio-buttons-oIwWoxwBKClt5IXvDbnpF)
 - ["We've updated the radios and checkboxes on GOV.UK"](https://designnotes.blog.gov.uk/2016/11/30/weve-updated-the-radios-and-checkboxes-on-gov-uk/)
 - [Four steps for choosing form elements on the Web (PDF)](http://www.formsthatwork.com/files/Articles/dropdown.pdf)

packages/docs/content/components/text-field/text-field.mdx

@@ -66,7 +66,7 @@ This component also makes use of form field styles, which can be customized by t
 - Text fields are among the easiest type of input for desktop users but are more difficult for mobile users.
 - Only show error messages or styling after a user has interacted with a particular field.
 
-**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/forms/)**
+**[View the "Forms" guidelines for additional guidance and best practices.](/patterns/Forms/forms/)**
 
 ### Accessibility
 
@@ -80,7 +80,7 @@ This component also makes use of form field styles, which can be customized by t
 
 ## Learn more
 
-- [Form Guidelines](/patterns/forms/)
+- [Form Guidelines](/patterns/Forms/forms/)
 - ["Placeholders in Form Fields Are Harmful"](https://www.nngroup.com/articles/form-design-placeholders/)
 - [Asking for a date of birth](https://designnotes.blog.gov.uk/2013/12/05/asking-for-a-date-of-birth/)
 - [GOV.UK text boxes discussion](https://paper.dropbox.com/doc/Text-boxes-8NLlgz9tjR8OzTz2N9wE3)

packages/docs/src/styles/components/syntaxHighlighting.scss

@@ -22,11 +22,24 @@ a code {
   text-decoration: underline;
 }
 
-.ds-c-alert code {
+.ds-c-alert code,
+kbd {
   // Semi-transparent so it matches the color of the alert better
   background-color: #c4c4c44f;
 }
 
+kbd {
+  border: 1px solid #b4b4b44f;
+  border-radius: 3px;
+  box-shadow: 0 1px 1px rgba(0, 0, 0, 0.2), 0 2px 0 0 rgba(255, 255, 255, 0.7) inset;
+  color: var(--color-black);
+  display: inline-block;
+  font-size: 0.85em;
+  line-height: 1;
+  padding: 2px 4px;
+  white-space: nowrap;
+}
+
 /**
  * a11y-light theme for JavaScript, CSS, and HTML
  * Based on the okaidia theme: https://github.com/PrismJS/prism/blob/gh-pages/themes/prism-okaidia.css