Merge pull request #9 from isabela-pf/keyboard-fixes

Keyboard navigation documentation fixes

workshop-resources/keyboard-navigation/README.md

@@ -1,21 +1,24 @@
-# Keyboard navigation Workshops
+# Keyboard navigation workshops
 
 Learn how to surf the web with a keyboard and contribute feedback for keyboard navigation fixes! 
 
-Keyboard navigation review workshops gather community to learn and practice expected keyboard navigation behavior. Participants also learn foundational tests they can perform and how to describe and present these issues constructively. This can be done confidently for any web interface, and could be adapted to desktop apps. At the end, everyone's work gets wrapped up to a neat for contribution back to the main project.
+Keyboard navigation review workshops gather community to learn and practice expected keyboard navigation behavior. Participants also learn foundational tests they can perform and how to describe and present these issues constructively. This can be done confidently for any web interface, and could be adapted to desktop apps. At the end, everyone's work gets wrapped up by the host for contribution back to the main project.
 
 ## Resources
 
 In this directory, you'll find the
 - [agenda template](agenda-template.md)
-- [keyboard navigation review template](review-template.md)
+- [keyboard navigation review template (for review by state or area)](review-template-by-state.md)
+- [keyboard navigation review template (for review by test)](review-template-by-test.md)
+- [getting started with keyboard navigation](getting-started.md)
 
 ## Past events
 
 Listed from oldest to newest
 
-| Year | Project | Working PR | Contributing PR | Status | Other info | 
+| Year | Project | Working location | Contributing location | Status | Other info | 
 |------|---------|------------|-----------------|--------|------------|
+| 2022 | Jupyter Notebook 7 | [isabela-pf/a11y-events #10](https://github.com/isabela-pf/a11y-events/pull/10) | [jupyter/notebook #6595](https://github.com/jupyter/notebook/issues/6595) | Contributed |  |
 |  |  |  |  |  |  |
 
 ## Roll the credits

workshop-resources/keyboard-navigation/getting-started.md

@@ -0,0 +1,45 @@
+# Getting started with keyboard navigation
+
+## What to press to navigate with a keyboard
+
+- Tab: go to the next focusable element
+- Shift + Tab: go to the previous focusable element
+- Enter or Space: activate interactive area (like buttons) or confirm a selection
+- Arrow keys: navigate within a focusable element (like selecting items within a menu)
+
+For more specific controls, review [Keyboard Testing - WebAIM](https://webaim.org/techniques/keyboard/#testing).
+
+### Reference:
+[Browsing with a keyboard - Tetralogical blog](https://tetralogical.com/blog/2021/10/26/browsing-with-a-keyboard/)
+
+## Common terms
+
+### Assistive technology
+
+Any technology that enables disabled users to fully interact with interfaces by providing interaction support beyond those offered by mainstream technology. Common examples include screen magnifiers, screen readers, alternative keyboards, or alternative pointing devices. These may be used in combination.
+
+For more in-depth and comprehensive defining, refer to [WCAG 2.2's definition of assistive technology](https://www.w3.org/TR/WCAG22/#dfn-assistive-technologies).
+
+### Keyboard focus
+
+It may also be called focus. When navigating with a keyboard, this is the point on a page where the user is currently navigated. This area can be described as "having focus."
+
+If you use a mouse, it might be helpful to imagine this as your mouse pointer. Your mouse pointer must move the the area you want to interact with before you can interact with it. This is also true of keyboard focus, though keyboard focus may also be important for non-interactive areas like if you used the mouse pointer to follow along as you read a paragraph.
+
+Keyboard focus may also be used to broadly group other qualities required for an accessible focus state. Someone might say an element is "missing focus" and mean that there is no visual [focus indicator](https://www.w3.org/TR/WCAG22/#dfn-focus-indicator) to tell them where keyboard focus currently is. 
+
+### Skip link
+
+An informal term shortened from "skip navigation link." It is a prompt that appears at the top of a page (usually invisible until the user presses the `Tab` key) that allows users to skip a page's navigation and move focus directly to the page's main content. This can help save time for users who are familiar with or do not need to know the page's navigation.
+
+For more discussion on skip links, refer to [WebAIM's Skip Navigation Link article](https://webaim.org/techniques/skipnav/).
+
+### Tab
+
+In this situation, tab refers to either the `Tab` key on a keyboard or the action of using the `Tab` key to navigate an interface. 
+
+For example, the review template asks reviewers to "press Tab" in reference to the keyboard key. This is the noun example. The host is also likely to tell reviewers to "tab through" an area to check for any skipped content. This is the verb example.
+
+### Tab trap
+
+An informal term used to describe when keyboard focus can be moved to a point in the interface but cannot be moved away from that point, "trapping" the tab navigation in one spot. It may also be called a keyboard trap.

workshop-resources/keyboard-navigation/review-template-by-state.md

@@ -0,0 +1,226 @@
+# Collaborative keyboard navigation review
+
+Please add your findings as [GitHub suggestions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) so you are credited in the commit history!
+
+## Keyboard navigation accessibility review of [tool name]
+
+Reviewed via based on [this link we'll all be working off of]().
+
+- Review date:
+- Operating system:
+- Browser: 
+- Keyboard language(s) used:
+- Any other details (ie. dependencies, github repo, etc.):
+
+### Authors and contents
+
+States/areas reviewed
+- State 1 (author(s))
+- State 2 (author(s))
+- State 3 (author(s))
+- State 4 (author(s))
+
+## Review
+
+For this review, participants select an area or state of the interface they would like to review and complete as many of the following tests as they want in the given time.
+
+### General notes
+
+This is the place for anything a reviewer thinks is important that doesn't belong below. This could be something out of scope of the review, something that will impact all other tests, or the like.
+
+Notes:
+
+### Entire interface
+
+These tests apply throughout the interface and are not reliant on testing in a single area or state.
+
+#### Skip links
+
+When using keyboard navigation, there is a link to switch keyboard focus directly to the tool's main content and skip header navigation or repeated content. ([WCAG 2.2 Bypass Blocks](https://www.w3.org/TR/WCAG22/#bypass-blocks))
+
+1. From the top of the page, press the Tab key. If you have already been interacting with the page, reviewer may need to reload page and then press Tab.
+2. Once focus is on the skip link, press Space or Enter to activate it.  
+
+Is there a skip link?
+Result:
+
+Is the skip link prompt visible?
+Result:
+
+What does the skip link prompt skip?
+Result:
+
+Where does the skip link prompt move user focus to?
+Result:
+
+Does the skip link behavior meet reviewer expectations?
+Result:
+
+Other notes or recommendations:
+
+#### Keyboard shortcuts
+
+Keyboard shortcuts--key combinations that initiate an action-- may not inhibit keyboard navigation. Keyboard shortcuts also need to be configurable. ([WCAG 2.2 Character key shortcuts](https://www.w3.org/TR/WCAG22/#character-key-shortcuts))
+
+[List of shortcuts for this tool]().
+
+1. Search for where keyboard shortcut settings may be edited.
+2. Review list of keyboard shortcuts.
+3. Choose a shortcut and answer the prompts.
+4. Repeat as needed.
+
+Can shortcuts be turned off?
+Result:
+
+Can shortcuts be configured (remapped to different keys than the default)?
+Result:
+
+Do any shortcuts conflict with browser or operating system controls?
+Result:
+
+Other notes or recommendations:
+
+##### Shortcut name
+
+Repeat this section as needed for each shortcut the reviewer evaluates.
+
+Shortcut keys:
+
+How many keys are needed?
+Result: 
+
+How close together are the keys?
+Result:
+
+Does the shortcut only activate when focus is on the related part of the interface?
+Result:
+
+Other notes or recommendations:
+
+### Area or state
+
+Description of the area or state goes here. It may be useful to link to documentation or tutorials to help participants be confident they are working where they intend to.
+
+#### Content order
+
+When accessed via keyboard, the content order is logical. ([WCAG 2.2 Focus order](https://www.w3.org/TR/WCAG22/#focus-order))
+
+1. From the top of the page, press the Tab key repeatedly until reviewer reaches the end of content.
+2. Reviewers will know it is the end because if they press Tab once more their keyboard focus will return to the browser.
+3. If the reviewer cannot make it to the end of content, please take note of where the focus gets stuck.
+
+Does the content order follow reviewer expectations based on reading the content?
+Result:
+
+Does the content order make sense for interacting with the content?
+Result:
+
+Are any major content areas missed when navigating via keyboard?
+Result:
+
+Are any interactive content areas missed when navigating via keyboard?
+Result:
+
+Other notes or recommendations:
+
+#### Areas to navigate
+
+All areas of the tool can be accessed using keyboard navigation. ([WCAG 2.2 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard))
+
+1. Navigate via the Tab key major content areas
+2. Use the arrow keys to navigate within major content areas.
+
+| Area | Able to navigate to the area (yes/no/not applicable) | Able to navigate fully within the area (yes/no/not applicable) | Able to navigate out of the area (yes/no/not applicable) |
+|---|---|---|---|
+| Navigation 1 | a | b | c |
+| Navigation 2 | d | e | f |
+| Aside/related content | g | h | i |
+| Main area | j | k | l |
+| Main area section | m | n | o |
+| Footer | p | q | r |
+
+Other notes by area:
+
+#### Keyboard/tab traps
+
+When navigating via keyboard, there are no areas where keyboard focus can enter but not exit. The focus never gets "trapped." ([WCAG 2.2 No keyboard trap](https://www.w3.org/TR/WCAG22/#no-keyboard-trap))
+
+1. From the top of the page, press the Tab key repeatedly until reviewer reaches the end of content.
+2. Reviewers will know it is the end because if they press Tab once more their keyboard focus will return to the browser.
+3. If the reviewer cannot make it to the end of content, please take note of where the focus gets stuck. If the reviewer can make it to all content, please note.
+4. Optional: complete steps 1–3 over any areas that may have been missed by the content order. Using the mouse to move focus to an area and trying to tab out may be helpful for these cases.
+
+Keyboard/tab traps:
+- tab trap 1
+- tab trap 2
+
+Other notes or recommendations:
+
+#### Interactive Areas
+
+All buttons, links, form fields, or similar interactive areas can be both accessed and activated using only the keyboard. ([WCAG 2.2 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard))
+
+1. Navigate via the Tab key to interactive areas. 
+2. Activate interactive areas using the Enter or Spacebar key.
+
+| Interactive area | Able to navigate to the area (yes/no/not applicable) | Able to input information (yes/no/not applicable) | Able to activate the area (yes/no/not applicable) |
+|---|---|---|---|
+| Button 1| a | b | c |
+| Button 2| d | e | f |
+| Button 3 | g | h | i |
+| Link 1 | j | k | l |
+| Link 2 | m | n | o |
+| Form field 1 | p | q | r |
+| Add table rows as needed! |  |  |  |
+| |  |  |  |
+
+Other notes by area:
+
+#### Focus
+
+There is a visible focus state for all content. It appears by default when navigating via keyboard. ([WCAG 2.2 Focus visible](https://www.w3.org/TR/WCAG22/#focus-visible))
+
+1. From the top of the page, press the Tab key repeatedly until reviewer reaches the end of content. 
+2. If end of content cannot be reached, the reviewer may report on what they could interact with.
+3. If the reviewer is comfortable, they may also use the browser inspector to select an area and toggle focus per area.
+
+Is there visible focus styling? If so, please briefly describe it.
+Result:
+
+Is the focus styling consistent throughout?
+Result:
+
+Are there any areas without visible focus styling?
+Result: 
+
+Was the reviewer ever unclear about where their keyboard focus was during the review? If so, please note where or why.
+Result:
+
+Other notes or recommendations:
+
+#### Mixed input
+
+It is possible to complete tasks while switching between input mechanisms, for example using a keyboard and mouse and touch screen. ([WCAG 2.2 Concurrent input mechanisms](https://www.w3.org/TR/WCAG22/#concurrent-input-mechanisms))
+
+1. Locate an interactive area.
+2. Complete the interaction using keyboard controls.
+3. Complete the interaction using the mouse.
+4. Complete the interaction using touch controls.
+5. If the task has multiple steps, the reviewer can try using a different interaction for each step.
+6. Repeat as needed across interactive areas.
+
+##### Task name + region
+
+Repeat this section as needed for each task or region the reviewer evaluates.
+
+Does the task have multiple steps? If yes, please list them.
+Result:
+
+Can the task be completed with only keyboard controls?
+Result:
+
+Can the task be completed with only mouse controls?
+Result:
+
+Can the task be completed with only touch screen controls?
+Result:

workshop-resources/keyboard-navigation/review-template.md → workshop-resources/keyboard-navigation/review-template-by-test.md

@@ -12,22 +12,27 @@ Reviewed via based on [this link we'll all be working off of]().
 - Keyboard language(s) used:
 - Any other details (ie. dependencies, github repo, etc.):
 
-### Authors
+### Authors and contents
+
+- Content order: (add author(s))
+- Areas to navigate: (add author(s))
+- Keyboard/tab traps: (add author(s))
+- Skip links: (add author(s))
+- Interactive Areas: (add author(s))
+- Focus: (add author(s))
+- Mixed input: (add author(s))
+- Keyboard shortcuts: (add author(s))
+- Additional authors: (add author(s))
 
-Participants may add their name below if they would like to be listed publicly as a part of the review.
+## Review
 
-1.
-2.
-3.
-4.
-5. 
-6.
-7.
-8.
-9.
-10. 
+For this review, participants select a test they would like to complete and apply it to as many areas or states of the interface as they want in the given time.
 
-## Review
+### General notes
+
+This is the place for anything a reviewer thinks is important that doesn't belong below. This could be something out of scope of the review, something that will impact all other tests, or the like.
+
+Notes:
 
 ### Content order
 
@@ -73,7 +78,10 @@ Other notes by area:
 
 When navigating via keyboard, there are no areas where keyboard focus can enter but not exit. The focus never gets "trapped." ([WCAG 2.2 No keyboard trap](https://www.w3.org/TR/WCAG22/#no-keyboard-trap))
 
-From the above section (Areas to navigate), please list all areas where the reviewer could not navigate out of using the keyboard. Notes are welcome!
+1. From the top of the page, press the Tab key repeatedly until reviewer reaches the end of content.
+2. Reviewers will know it is the end because if they press Tab once more their keyboard focus will return to the browser.
+3. If the reviewer cannot make it to the end of content, please take note of where the focus gets stuck. If the reviewer can make it to all content, please note.
+4. Optional: complete steps 1–3 over any areas that may have been missed by the content order. Using the mouse to move focus to an area and trying to tab out may be helpful for these cases.
 
 Keyboard/tab traps:
 - tab trap 1
@@ -160,6 +168,8 @@ It is possible to complete tasks while switching between input mechanisms, for e
 
 #### Task name + region
 
+Repeat this section as needed for each task or region the reviewer evaluates.
+
 Does the task have multiple steps? If yes, please list them.
 Result:
 
@@ -196,6 +206,8 @@ Other notes or recommendations:
 
 #### Shortcut name
 
+Repeat this section as needed for each shortcut the reviewer evaluates.
+
 Shortcut keys:
 
 How many keys are needed?