Merge branch 'main' into dmundra-patch-1

_guide/semantic-html.md

@@ -1,6 +1,6 @@
 ---
 layout: guide
-title: Semantic HTML
+title: Semantic HTML and accessibility
 description: Basic information on semantic HTML and accessibility.
 excerpt: Basic information on semantic HTML and accessibility.
 sidenav: docs
@@ -12,34 +12,90 @@ roles:
 ---
 
 
-Writing semantic HTML can make your site more accessible. When you switch your browser to "read mode", only the main content will be visible. Read mode hides:
-* the header
-* footer
-* background images,
-* colours
-* animations
-* or functionality like tabs and accordions.
+When a contractor builds a house, they tend to use standard and expected materials that are appropriate for their purpose—i.e. concrete, wood, shingles, etc. Using standard materials helps to ensure the house is built well. If other materials are used instead, the house might require additional work to achieve the same end result. If the Three Little Pigs have taught us anything, unless it's reinforced, a house made of straw can't be expected to withstand strong winds.
 
-Many people switch to read mode to improve their readability. It can also make for more personalization, allowing the user to control how they see the web page.
+This same principle is true when building a website—there are standard building blocks for each section, typically referred to as semantic HTML tags. Using these tags gives the resulting website more structure and context than building with other, generic tags. Semantic HTML tags also provide some default accessibility to the page elements that would otherwise need to be reinforced using additional, custom code.
 
-The `<div>` element main purpose is for styling your page. Read mode will ignore <div> tags, so any text inside not a heading or `<p>` will be ignored. Users using the read mode will not get all the information that they should, and can be confusing.
+## What is semantic HTML?
+When someone says that you should be building using semantic HTML, what does this actually mean?
 
-HTML elements to structure every page:
-* header
-* nav
-* main 
-* article
-* aside
-* footer
+Semantic markup refers to the HTML tags that define the meaning and structure of the content they contain. There are [many semantic tags](https://developer.mozilla.org/en-US/docs/Glossary/Semantics#semantic_elements) but a few common examples are:
+* `<header>`: This represents the header or introduction of the website. This is typically the area that contains the site logo and global navigation.
+* `<main>`: This is for the main body content of the webpage. There should always be only one main section on each page.
+* `<a>`: This tag is sometimes referred to as the anchor element and is used for a link. A link element has an `href` attribute and goes somewhere, to a new page on the website or an external page on another website.
+* `<button>`: This represents a button element. A button element is for an action that does something, such as opening a modal or submitting a form.
+* `<li>`: This tag represents an item in a list. This tag must be contained within a `<ul>` tag (unordered list) or an `<ol>` tag (ordered list) or `<menu>` tag.
 
-Headings
-Use only one H1 per page, which should match the page title.
-Do not skip heading levels.
 
-## Using reader mode in browsers
+There are also other, generic tags such as `<div>` and `<span>` that do not define any meaning and therefore are not considered semantic tags.
 
-* Edge - by adding `read://` to before your url (example `read://https://www.civicactions.com`)
-* Chrome - [download the app](https://chrome.google.com/webstore/detail/reader-mode/llimhhconnjiflfimocjggfjdlmlhblm?hl=en) or [enable the read mode setting](https://www.howtogeek.com/423643/how-to-use-google-chromes-hidden-reader-mode/)
-* Safari - `Ctrl+Shift+R` turns on reading mode on a macbook
-* Firefox - `View->Enter reader view` from top toolbar or to the right of the url is a reader view button
+Here's an example of the same element written with and without semantic tags:
+
+**Example 1 - Generic tags:**
+```
+<div>
+  <div>
+    <span><a href="/">Home</a></span>
+    <span><a href="/about">About Us</a></span>
+    <span><a href="/contact">Contact</a></span>
+  </div>
+</div>
+```
+
+**Example 2 - Semantic tags:**
+```
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/about">About Us</a></li>
+    <li><a href="/contact">Contact</a></li>
+  </ul>
+</nav>
+```
+
+In the first example, using generic tags, without the visual of the website itself, it's hard to clearly understand what the purpose of this code is for. There are 3 links, grouped together but why exactly it's not clear.
+
+In the second example we clearly see semantic tags for a navigation menu (`<nav>`), containing an unordered list (`<ul>`) with 3 links. There still is no visual but from just the implicit meaning of the tags, it's understood that the purpose of this code is to provide a navigational list element for the website.
+
+## Why use semantic HTML?
+Besides providing clear structure and contextual information to your HTML document, semantic tags will also inherit default styles from the user-agent stylesheets. Each browser, or user-agent, provides a basic set of CSS rules that define how semantic HTML elements will visually render. These rules can include underlining links, a larger font-weight for bold text, backgrounds on buttons, etc. By already having basic styles on certain elements, specifying additional CSS is not always needed which can make your work more efficient.
+
+A further benefit of using semantic HTML tags is that along with the default CSS styles, they also provide some basic accessibility functionality, no additional custom code is required, 
+
+## Keyboard functionality
+One of the main benefits of using semantic HTML tags is that by default, they provide the required keyboard functionality needed for accessibility. At a minimum, all interactive elements on a webpage must be available and focusable using the TAB key. They must also respond appropriately to expected keyboard keys. Typically, these keys are ENTER and SPACE, however for certain elements the ARROW keys or ESC key, among others, are expected. Each element has different default behavior and by using the standard semantic tag, you will be getting this default functionality and behavior for free. 
+
+For example, if an element is created using the `<button>` tag, a user will be able to tab to the button and will be able to activate it using both the SPACE and ENTER keys. However, another element styled to visually look like a button but created using a generic `<div>` tag will not have this default keyboard functionality and this interaction will need to be added using additional code, typically JavaScript.
+
+**Example**
+Using the keyboard, try to tab to the two buttons. Notice that only the first, semantic button receives proper keyboard focus.
+
+<button>A semantic button</button>
+
+<div style="background:black; padding: 10px; color:white; display:inline-block;">Generic button</div>
+
+## Landmarks
+People using assistive technology often navigate a webpage by using the landmarks on a page. However, these sections need to first be identified as such in order for this to be possible. The 7 sections that should be identified on each page are:
+* `role="banner"`:  Semantic equivalent is `<header>`
+* `role="navigation"`: Semantic equivalent is `<nav>`
+* `role="search"`: Semantic equivalent is `<search>`
+* `role="main"`: Semantic equivalent is `<main>`
+* `role="complementary"`: Semantic equivalent is `<aside>`
+* `role="form"`: Semantic equivalent is `<form>`
+* `role="contentinfo"`: Semantic equivalent is `<footer>`
+
+Structuring web pages using the equivalent semantic tag rather than the role attribute, means these sections will be identified by default, no landmark role will be forgotten, and the user will be able to clearly understand the structure and layout of the page as well as navigate directly to a particular landmark if they choose.
+
+## Assistive technology
+As with landmarks, assistive technology users, especially those using screen readers, also often use the menus within their software to view a full list of other elements on a page, such as headings, links, buttons or forms. Using that list they can get a sense of the content on the page and can also  jump directly to a particular element if they want.
+
+![Elements link menu in NVDA with the links list selected and showing all links on a web page. There are buttons at the bottom for the user to choose to Activate a link, Move to a link, or Cancel and close out the menu.](/assets/img/NVDA_links_menu.png)
+
+However, only the elements built using semantic HTML tags will be available to these assistive technologies and displayed in these menus. Generic elements, even if they are styled to look like headings, links or buttons, will not be shown in these menus which could cause users to miss important content.
+
+## Resources
+* [List of semantic elements](https://developer.mozilla.org/en-US/docs/Glossary/Semantics#semantic_elements)
+* [Semantic Structure](https://webaim.org/techniques/semanticstructure/)
+* [More information about the div tag](https://www.scottohara.me/blog/2022/01/20/divisive.html)
+* [HTML and landmark roles](https://developer.mozilla.org/en-US/blog/aria-accessibility-html-landmark-roles/)
 

_playbook/AT.md

@@ -1,6 +1,6 @@
 ---
 layout: playbook
-title: Test with assistive technology
+title: Screen reader testing
 description: 
 excerpt: 
 sidenav: docs
@@ -14,21 +14,51 @@ roles:
   - UX designer
 ---
 
-It is good to do some testing with assistive technology (AT), but it takes considerable experience for a sighted user to use a screen reader like a blind user would. Because of the nature of vision related disabilities there is considerable variation even within the blind and low vision community.
+Screen reader users navigate and experience web pages differently than non-screen reader users typically do. While it takes considerable experience to use a screen reader in the same way as the average daily user, incorporating basic screen reader testing into your accessibility test plan can still be quite effective in finding potential issues.
 
-Job Access With Speech (JAWS) is a common screen reader tool that enables people with visual impairments to read digital content, either by text-to-speech or Braille display. However, JAWS is not free. Use of Microsoft's Narrator is increasing, but still trails behind other screen readers. Few governments are using [NonVisual Desktop Access (NVDA)](https://webaim.org/projects/screenreadersurvey7/), even though it is a free, open source solution that is nearly as popular with the blind community. All Apple products come with VoiceOver which is another powerful screen reader. Android comes with the open source TalkBack screen reader.
+There is considerable variation, even within the blind and low vision community, on how screen reader users navigate the web due to the wide range of vision related disabilities and technologies available. Each screen reader also has different default functionality and behaviors and can be customized to the user's preferences. It's recommended to test with multiple screen readers and devices to account for as many of these variations as possible. 
 
-There are a range of other assistive technologies which are available to support other disabilities. We often overlook voice control, with tools like Dragon Naturally Speaking, Windows Speech and Apple's Voice Control. There is a range of disabilities where motion for the user is severely limited and where simple switches need to be employed to navigate the website. Probably the most famous switch user was Stephen Hawking used a handheld switch early in his life, but then moved to a cheek switch when he lost control of his hands. 
+## Common screen readers
 
-Whatever software you choose, it is always good practice to support the latest two major releases of assistive technology to allow for late adopters, and to test with actual blind users. It takes considerable effort for a sighted user to learn to use a screen reader how a blind user does., and simply being able to use one of these assistive technology tools may not be the best way to evaluate if a page is accessible.
+* [JAWS](https://www.freedomscientific.com/products/software/jaws/) (Job Access With Speech)
+  * A very popular screen reader available for PC
+  * Requires a paid license to be run
+  * For testing purposes, JAWS can be run in 40 minute intervals without a license
+* [NVDA](https://www.nvaccess.org/about-nvda/) (Non-Visual Desktop Access)
+  * Another popular option for PC
+  * Free screen reading software that does not require a license
+* VoiceOver
+  * All Apple products come with VoiceOver by default
+  * VoiceOver is typically more popular as a screen reader for mobile rather than desktop
+* TalkBack
+  * All Android devices come with this screen reader by default
+  * Not extremely popular overall, but is the most popular for Android devices
 
-## Checklist
 
-* Ensure your team has access to a desktop screen reader in Windows and Apple as well as a mobile one.
-* Test navigating the website with voice control (speech to text).
-* Ensure that you have access to the latest version of the assistive technology.
+## Basic screen reader tests
 
-## Key questions
+Using at least one of the common screen readers mentioned, complete the basic testing steps.
 
-* Does your team have the deep knowledge that is required to understand how a blind user actually understands the page?
-* Is user testing done with people who are completely blind, partially sighted, and who become blind as adults? Screen reader users have a lot of flexibility.
+1. Read through the web page start to finish.
+   * Is everything read on the page that you expected? Is anything skipped or read in an incorrect order?
+   * Are all elements read in a way that is understandable? 
+2. Tab through the webpage using the keyboard.
+   * Are all the interactive elements on the page available using the keyboard?
+   * Does each element respond to expected keys? WebAim has a good reference for expected keyboard interaction.
+3. Confirm use of landmarks to create the main document structure of the page.
+   * Review the landmarks list to see which landmarks/semantic layout elements are used on the page.
+   * Confirm that any duplicate landmarks or regions have been identified with a unique label.
+4. Fill out and submit all forms.
+   * Are all field labels, instructions and hint text, announced as expected?
+   * Are error messages announced and understood?
+   * Are the invalid fields clearly marked?
+5. Confirm that links and buttons appear in the appropriate list within the screen reader menus and have descriptive, unique text labels.
+6. Review all images and other non-text content to confirm they have meaningful alternative text descriptions.
+
+## Resources
+These resources and guides can help you to become familiar with and learn how to use each screen reader.
+* [JAWS keyboard shortcuts](https://webaim.org/resources/shortcuts/jaws)
+* [NVDA keyboard shortcuts](https://webaim.org/resources/shortcuts/nvda)
+* [VoiceOver keyboard shortcuts](https://webaim.org/articles/voiceover/)
+* [VoiceOver touch device gestures](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/ios)
+* [Getting started with TalkBack](https://support.google.com/accessibility/android/answer/6283677?hl=en)