From 9a6054c2af56093b0cefa08bdf2c6600fc08fb85 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Fri, 6 Sep 2019 11:50:16 -0500 Subject: [PATCH 1/2] Create accessibility.md --- docs/guides/accessibility.md | 100 +++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/guides/accessibility.md diff --git a/docs/guides/accessibility.md b/docs/guides/accessibility.md new file mode 100644 index 000000000000..a49591595649 --- /dev/null +++ b/docs/guides/accessibility.md @@ -0,0 +1,100 @@ +# Automated Verification Testing (AVT) stage 1 + +AVT1 testing is done with a browser extension developed by IBM called the Dynamic Assessment Plugin (DAP). It's a great first step to locking down and ensuring inclusivity and accessibility in your websites and components. + +## Installing DAP🔧 + +1. Grab the plugin while connected to IBM's W3 [from here](https://ibm.biz/BdYkWF). + + _Be Warned: Make sure you only download the latest plugin from the specific link above which should be version >1.7. The IBM DAP plugin available to the public in the Chrome extension marketplace is unmaintained and will not support the latest rulesets._ + +2. At the top left of [this page](https://ibm.biz/BdYkML) is a button that will copy to your clipboard the Authentication Token you'll need to access IBM's rulesets. Click it. +3. With the plugin installed and your token copied head into DAP's options found inside the plugin dropdown menu and paste the token into the Authentication form and hit apply. +4. Now that DAP's authenticated the Supported Rulesets section in the options menu of the plugin should be populated. Typically you're going to want the latest ruleset unless someone has told you otherwise. +5. Hit the apply button at the bottom of the page. + +## Using DAP👷 + +Let's DAP! It's pretty straight forward, but there are a few gotchas. For consistency's sake we'll use DAP on the [Dynamic Assessment Plug-in Homepage](https://ibm.biz/BdYkM9). + +Head over to the page and hit `cmd-option-c` to open up your dev tools. DAP is tucked away inside a drop down menu inside a panel. From the default Elements panel hit the >> icon below the X on the far right. You should see `DAP`. Click that to fire up DAP for this page. + +_Be Warned: You can only run DAP with internal IBM rulesets if you're connected to W3. On an IBM campus this isn't a problem, but if you're abroad fire up the Cisco AnyConnect Secure Mobility Client._ + +Hit the play button and wait for the scan to finish. **We've got violations!**. At the time of writing there are 7 Violations, 9 Potential Violations, and 2 Manual Checks. There's also multiple "frames", but if you're testing single components or a group of components in a Storybook environment you can ignore those✋. + +On the main frame (the one open by default) there's a detailed list of all violation types. Clicking into each violation type gives you more nested dropdowns -- one for each violation found on the page of that specific type. Each violation's dropdown gives you two further options: + +1. A description of the general violation with a ? icon that when clicked will take you to further documentation detailing the violation and most helpfully how to fix it. +2. A description of this particular instance of a violation (say for instance an image with no alt attribute). And a crossed out eyeball you can click to ignore this violation which is helpful when printing reports for posterity's sake. + +## Running an AVT1 Audit📋 + +Whenever any new UI code is introduced or existing code is changed or updated we should run DAP on the new code so we can make sure it meets or exceeds IBM's accessibility standards. + +DAP is always evolving its rulesets but unfortunately it can report false positives when testing exclusively on a component. Typically we're not auditing a webpage or a website as a whole, but a single component in isolation -- sadly this was not DAP's intended purpose and so it throws a lot of false positive violations that you'll first need to sift through and ignore if we're going to be keeping and recording this audit. If you're just testing while you develop or before you push a PR, feel free to just disregard them. + +If the component fails or has a violation an issue should be made so that someone can fix the problem. Feel free to include in the issue any relevant information you think would helpful, but make sure to at least include these points: + +1. The environment where the failure happened. The browser make and version as well as the ruleset and operating system. +2. A description of the failure (copy an pasted from DAP's logs is fine). +3. A screenshot of the particular offending code. +4. Steps to reproduce the violation for anyone who may want to tackle the issue but may not have read this guide. + +If running DAP produces no violations (that's awesome🎉) we still want to record and keep proof that DAP was run so we can make sure we're staying on top of accessibility testing for each component as they change and get updated per each release. To do that: + +1. Click the hamburger menu in the top right of the DAP panel and select Download Report. +2. In the modal select JSON and five your report a helpful name in this format `componentname_subtype.html` and then download. + + _Be warned: Occasionally clicking the Download Report button won't work. This can be a serious pain if the dev has already gone through and ignored false positives. I've had a 100% success rate with Download Report if after I open the DAP panel in my dev tools I then reload the page with the panel open. 😞 -- D.A._ + +3. [Follow this link](https://ibm.biz/BdYkMA) and select the folder that corresponds with the ruleset the component was tested against and drop the JSON file in there. + +# Automated Verification Testing stage 2 + +["Keyboard accessibility is one of the most important aspects of web accessibility."](https://webaim.org/techniques/keyboard/) and it's the focus of part 1 of our AVT2 testing! + +Here's what we're looking for during our AVT2 audit. Therea are two main parts: + +## Keyboard accessibility testing⌨️ + +1. All functionality should be available from a keyboard without exception. +2. Keyboard navigation uses standardized keystrokes: + + - TAB to move forward through the various focusable elements. + - SHIFT+TAB to move backward through previous focusable elements. + - ENTER or SPACE to activate, select, or otherwise interact with focusable elements. + - Escape to close popups, toasts, or modals and return focus to main page content. + + _Any variance on these standardized keystrokes should be outlined clearly to the user beforehand_ + +3. If an element can receive keyboard focus it should reflect that in it's styling with a focused state. +4. If you can move focus to an element with the keyboard you should be able to move focus away from that element with a keyboard. +5. Navigating through the pages tabbable elements makes sense in terms of their order. +6. Long or burdensome lists, links, or navigation should provide a "skip to main content" link. + +### How to test + +Essentially open the component or web page you're auditing. Then make a note of all the elements on the page that are interactible with a mouse in any way. Finally moving through the list above attempt to interact with those elements using only your keyboard in the manner described. Integrating this test throughout each stage of development will save you the pain of retro-fitting a component with the necessary keyboard functionality. + +## Screen Magnifier testing🔎 + +(Credit to Frederick Creemers [excellent article](https://dev.to/_bigblind/how-to-make-your-website-accessible-to-people-who-use-a-screen-magnifier) talking about his experience as a visually impaired screen magnification user on the web.) + +A user with a screen magnifier views web content on a component by component basis through a 2x, 4x, or 8x (etc) zoomed in box. Two things become very important when using a screen magnifier -- context and component permanence. We can dig into those points further: + +1. Tooltips, toasts and popups should be shown to the user adjacent to where they were triggered. + + It is a common pattern on the web to have the user perform a task and have that task's confirmation displayed elsewhere in the user interface (like a toast assuring the user their work was saved, or a small number in the top corner indicating something's in your shopping cart). This can leave screen magnifier users wondering if their actions had any result at all. Instead keep confirmation, dialogues, tooltips and toasts adjacent to the actions that triggered them. + +2. Tooltips or any word bubble type notifications or information areas should not depend on a mouse hover. + + Depending on hover as a mouse action to trigger a dialogue or tooltip isn't accessible. Commonly a screen magnifier shows a zoomed in view of the page relative to the cursor position. This means that unless then tooltip or dialogue is quite small the user can't trigger the component _and_ scroll it's content into view. + +3. Don't obscure content on mouse hover + + Obscuring all or some of the page on mouse hover with an overlay or blur is a problem for user of screen magnifiers. Maintain required contrast ration and instead signal to your users with some other visual dinstinction. + +### How to test + +Keyboard accessibility is generally more familiar to developers than magnification tools, but Take this opportunity to familiarize yourself with macOS Zoom Windows Magnifier, or your OS's native low vision accessibility tools as they are relied on by millions of people with temporary or permanent vision impairment every day. From 483c55072783d6504fee0cf0db2cd054d1463426 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Fri, 6 Sep 2019 12:10:41 -0500 Subject: [PATCH 2/2] docs(accessibility): update structure and format --- docs/guides/accessibility.md | 281 ++++++++++++++++++++++++++--------- 1 file changed, 209 insertions(+), 72 deletions(-) diff --git a/docs/guides/accessibility.md b/docs/guides/accessibility.md index a49591595649..8f6537ec66c1 100644 --- a/docs/guides/accessibility.md +++ b/docs/guides/accessibility.md @@ -1,100 +1,237 @@ -# Automated Verification Testing (AVT) stage 1 - -AVT1 testing is done with a browser extension developed by IBM called the Dynamic Assessment Plugin (DAP). It's a great first step to locking down and ensuring inclusivity and accessibility in your websites and components. - -## Installing DAP🔧 - -1. Grab the plugin while connected to IBM's W3 [from here](https://ibm.biz/BdYkWF). - - _Be Warned: Make sure you only download the latest plugin from the specific link above which should be version >1.7. The IBM DAP plugin available to the public in the Chrome extension marketplace is unmaintained and will not support the latest rulesets._ - -2. At the top left of [this page](https://ibm.biz/BdYkML) is a button that will copy to your clipboard the Authentication Token you'll need to access IBM's rulesets. Click it. -3. With the plugin installed and your token copied head into DAP's options found inside the plugin dropdown menu and paste the token into the Authentication form and hit apply. -4. Now that DAP's authenticated the Supported Rulesets section in the options menu of the plugin should be populated. Typically you're going to want the latest ruleset unless someone has told you otherwise. +# Accessibility + + + + +## Table of Contents + +- [Getting started](#getting-started) + - [Installing DAP🔧](#installing-dap) +- [AVT1](#avt1) + - [Running an AVT1 Audit📋](#running-an-avt1-audit) +- [AVT2](#avt2) + - [Keyboard accessibility testing⌨️](#keyboard-accessibility-testing) + - [How to test](#how-to-test) + - [Screen Magnifier testing🔎](#screen-magnifier-testing) + - [How to test](#how-to-test-1) +- [FAQ](#faq) + - [Using DAP👷](#using-dap) + + + + +## Getting started + +> IBM firmly believes that web and software experiences should be accessible for +> everyone, regardless of abilities or impairments. Carbon is committed to +> following and complying with best practices when it comes to accessibility. +> +> _[Carbon Design System - Accessibility](https://www.carbondesignsystem.com/guidelines/accessibility/overview)_ + +Accessibility Verification Testing (AVT) at IBM is broken up into three stages: + +- **AVT1:** automated checks using tooling like DAP +- **AVT2:** manual checks that cannot be automated through tooling +- **AVT3:** manual checks to verify screen reader support + +_For full information about each stage, we recommend checking out +[IBM Accessibility's guided tour](https://ibm.biz/BdzgUf) (Internal only link)._ + +This guide will talk through the tools and techniques we use on Carbon for each +of the phases above. Before we get started, let's make sure you have the right +tools 🛠. + +### Installing DAP🔧 + +1. Grab the plugin while connected to IBM's W3 + [from here](https://ibm.biz/BdYkWF). + + _Be Warned: Make sure you only download the latest plugin from the specific + link above which should be version >1.7. The IBM DAP plugin available to the + public in the Chrome extension marketplace is unmaintained and will not + support the latest rulesets._ + +2. At the top left of [this page](https://ibm.biz/BdYkML) is a button that will + copy to your clipboard the Authentication Token you'll need to access IBM's + rulesets. Click it. +3. With the plugin installed and your token copied head into DAP's options found + inside the plugin dropdown menu and paste the token into the Authentication + form and hit apply. +4. Now that DAP's authenticated the Supported Rulesets section in the options + menu of the plugin should be populated. Typically you're going to want the + latest ruleset unless someone has told you otherwise. 5. Hit the apply button at the bottom of the page. -## Using DAP👷 - -Let's DAP! It's pretty straight forward, but there are a few gotchas. For consistency's sake we'll use DAP on the [Dynamic Assessment Plug-in Homepage](https://ibm.biz/BdYkM9). +## AVT1 -Head over to the page and hit `cmd-option-c` to open up your dev tools. DAP is tucked away inside a drop down menu inside a panel. From the default Elements panel hit the >> icon below the X on the far right. You should see `DAP`. Click that to fire up DAP for this page. +AVT1 testing is done with a browser extension developed by IBM called the +Dynamic Assessment Plugin (DAP). It's a great first step to locking down and +ensuring inclusivity and accessibility in your websites and components. -_Be Warned: You can only run DAP with internal IBM rulesets if you're connected to W3. On an IBM campus this isn't a problem, but if you're abroad fire up the Cisco AnyConnect Secure Mobility Client._ +### Running an AVT1 Audit📋 -Hit the play button and wait for the scan to finish. **We've got violations!**. At the time of writing there are 7 Violations, 9 Potential Violations, and 2 Manual Checks. There's also multiple "frames", but if you're testing single components or a group of components in a Storybook environment you can ignore those✋. +Whenever any new UI code is introduced or existing code is changed or updated we +should run DAP on the new code so we can make sure it meets or exceeds IBM's +accessibility standards. -On the main frame (the one open by default) there's a detailed list of all violation types. Clicking into each violation type gives you more nested dropdowns -- one for each violation found on the page of that specific type. Each violation's dropdown gives you two further options: +DAP is always evolving its rulesets but unfortunately it can report false +positives when testing exclusively on a component. Typically we're not auditing +a webpage or a website as a whole, but a single component in isolation -- sadly +this was not DAP's intended purpose and so it throws a lot of false positive +violations that you'll first need to sift through and ignore if we're going to +be keeping and recording this audit. If you're just testing while you develop or +before you push a PR, feel free to just disregard them. -1. A description of the general violation with a ? icon that when clicked will take you to further documentation detailing the violation and most helpfully how to fix it. -2. A description of this particular instance of a violation (say for instance an image with no alt attribute). And a crossed out eyeball you can click to ignore this violation which is helpful when printing reports for posterity's sake. +If the component fails or has a violation an issue should be made so that +someone can fix the problem. Feel free to include in the issue any relevant +information you think would helpful, but make sure to at least include these +points: -## Running an AVT1 Audit📋 - -Whenever any new UI code is introduced or existing code is changed or updated we should run DAP on the new code so we can make sure it meets or exceeds IBM's accessibility standards. - -DAP is always evolving its rulesets but unfortunately it can report false positives when testing exclusively on a component. Typically we're not auditing a webpage or a website as a whole, but a single component in isolation -- sadly this was not DAP's intended purpose and so it throws a lot of false positive violations that you'll first need to sift through and ignore if we're going to be keeping and recording this audit. If you're just testing while you develop or before you push a PR, feel free to just disregard them. - -If the component fails or has a violation an issue should be made so that someone can fix the problem. Feel free to include in the issue any relevant information you think would helpful, but make sure to at least include these points: - -1. The environment where the failure happened. The browser make and version as well as the ruleset and operating system. +1. The environment where the failure happened. The browser make and version as + well as the ruleset and operating system. 2. A description of the failure (copy an pasted from DAP's logs is fine). 3. A screenshot of the particular offending code. -4. Steps to reproduce the violation for anyone who may want to tackle the issue but may not have read this guide. +4. Steps to reproduce the violation for anyone who may want to tackle the issue + but may not have read this guide. -If running DAP produces no violations (that's awesome🎉) we still want to record and keep proof that DAP was run so we can make sure we're staying on top of accessibility testing for each component as they change and get updated per each release. To do that: +If running DAP produces no violations (that's awesome🎉) we still want to record +and keep proof that DAP was run so we can make sure we're staying on top of +accessibility testing for each component as they change and get updated per each +release. To do that: -1. Click the hamburger menu in the top right of the DAP panel and select Download Report. -2. In the modal select JSON and five your report a helpful name in this format `componentname_subtype.html` and then download. +1. Click the hamburger menu in the top right of the DAP panel and select + Download Report. +2. In the modal select JSON and five your report a helpful name in this format + `componentname_subtype.html` and then download. - _Be warned: Occasionally clicking the Download Report button won't work. This can be a serious pain if the dev has already gone through and ignored false positives. I've had a 100% success rate with Download Report if after I open the DAP panel in my dev tools I then reload the page with the panel open. 😞 -- D.A._ + _Be warned: Occasionally clicking the Download Report button won't work. This + can be a serious pain if the dev has already gone through and ignored false + positives. I've had a 100% success rate with Download Report if after I open + the DAP panel in my dev tools I then reload the page with the panel open. 😞 + -- D.A._ -3. [Follow this link](https://ibm.biz/BdYkMA) and select the folder that corresponds with the ruleset the component was tested against and drop the JSON file in there. +3. [Follow this link](https://ibm.biz/BdYkMA) and select the folder that + corresponds with the ruleset the component was tested against and drop the + JSON file in there. -# Automated Verification Testing stage 2 +## AVT2 -["Keyboard accessibility is one of the most important aspects of web accessibility."](https://webaim.org/techniques/keyboard/) and it's the focus of part 1 of our AVT2 testing! +["Keyboard accessibility is one of the most important aspects of web accessibility."](https://webaim.org/techniques/keyboard/) +and it's the focus of part 1 of our AVT2 testing! Here's what we're looking for during our AVT2 audit. Therea are two main parts: -## Keyboard accessibility testing⌨️ +### Keyboard accessibility testing⌨️ 1. All functionality should be available from a keyboard without exception. 2. Keyboard navigation uses standardized keystrokes: - TAB to move forward through the various focusable elements. - SHIFT+TAB to move backward through previous focusable elements. - - ENTER or SPACE to activate, select, or otherwise interact with focusable elements. - - Escape to close popups, toasts, or modals and return focus to main page content. - - _Any variance on these standardized keystrokes should be outlined clearly to the user beforehand_ - -3. If an element can receive keyboard focus it should reflect that in it's styling with a focused state. -4. If you can move focus to an element with the keyboard you should be able to move focus away from that element with a keyboard. -5. Navigating through the pages tabbable elements makes sense in terms of their order. -6. Long or burdensome lists, links, or navigation should provide a "skip to main content" link. - -### How to test - -Essentially open the component or web page you're auditing. Then make a note of all the elements on the page that are interactible with a mouse in any way. Finally moving through the list above attempt to interact with those elements using only your keyboard in the manner described. Integrating this test throughout each stage of development will save you the pain of retro-fitting a component with the necessary keyboard functionality. - -## Screen Magnifier testing🔎 - -(Credit to Frederick Creemers [excellent article](https://dev.to/_bigblind/how-to-make-your-website-accessible-to-people-who-use-a-screen-magnifier) talking about his experience as a visually impaired screen magnification user on the web.) - -A user with a screen magnifier views web content on a component by component basis through a 2x, 4x, or 8x (etc) zoomed in box. Two things become very important when using a screen magnifier -- context and component permanence. We can dig into those points further: - -1. Tooltips, toasts and popups should be shown to the user adjacent to where they were triggered. - - It is a common pattern on the web to have the user perform a task and have that task's confirmation displayed elsewhere in the user interface (like a toast assuring the user their work was saved, or a small number in the top corner indicating something's in your shopping cart). This can leave screen magnifier users wondering if their actions had any result at all. Instead keep confirmation, dialogues, tooltips and toasts adjacent to the actions that triggered them. - -2. Tooltips or any word bubble type notifications or information areas should not depend on a mouse hover. - - Depending on hover as a mouse action to trigger a dialogue or tooltip isn't accessible. Commonly a screen magnifier shows a zoomed in view of the page relative to the cursor position. This means that unless then tooltip or dialogue is quite small the user can't trigger the component _and_ scroll it's content into view. + - ENTER or SPACE to activate, select, or otherwise interact with focusable + elements. + - Escape to close popups, toasts, or modals and return focus to main page + content. + + _Any variance on these standardized keystrokes should be outlined clearly + to the user beforehand_ + +3. If an element can receive keyboard focus it should reflect that in it's + styling with a focused state. +4. If you can move focus to an element with the keyboard you should be able to + move focus away from that element with a keyboard. +5. Navigating through the pages tabbable elements makes sense in terms of their + order. +6. Long or burdensome lists, links, or navigation should provide a "skip to main + content" link. + +#### How to test + +Essentially open the component or web page you're auditing. Then make a note of +all the elements on the page that are interactible with a mouse in any way. +Finally moving through the list above attempt to interact with those elements +using only your keyboard in the manner described. Integrating this test +throughout each stage of development will save you the pain of retro-fitting a +component with the necessary keyboard functionality. + +### Screen Magnifier testing🔎 + +(Credit to Frederick Creemers +[excellent article](https://dev.to/_bigblind/how-to-make-your-website-accessible-to-people-who-use-a-screen-magnifier) +talking about his experience as a visually impaired screen magnification user on +the web.) + +A user with a screen magnifier views web content on a component by component +basis through a 2x, 4x, or 8x (etc) zoomed in box. Two things become very +important when using a screen magnifier -- context and component permanence. We +can dig into those points further: + +1. Tooltips, toasts and popups should be shown to the user adjacent to where + they were triggered. + + It is a common pattern on the web to have the user perform a task and have + that task's confirmation displayed elsewhere in the user interface (like a + toast assuring the user their work was saved, or a small number in the top + corner indicating something's in your shopping cart). This can leave screen + magnifier users wondering if their actions had any result at all. Instead + keep confirmation, dialogues, tooltips and toasts adjacent to the actions + that triggered them. + +2. Tooltips or any word bubble type notifications or information areas should + not depend on a mouse hover. + + Depending on hover as a mouse action to trigger a dialogue or tooltip isn't + accessible. Commonly a screen magnifier shows a zoomed in view of the page + relative to the cursor position. This means that unless then tooltip or + dialogue is quite small the user can't trigger the component _and_ scroll + it's content into view. 3. Don't obscure content on mouse hover - Obscuring all or some of the page on mouse hover with an overlay or blur is a problem for user of screen magnifiers. Maintain required contrast ration and instead signal to your users with some other visual dinstinction. - -### How to test - -Keyboard accessibility is generally more familiar to developers than magnification tools, but Take this opportunity to familiarize yourself with macOS Zoom Windows Magnifier, or your OS's native low vision accessibility tools as they are relied on by millions of people with temporary or permanent vision impairment every day. + Obscuring all or some of the page on mouse hover with an overlay or blur is a + problem for user of screen magnifiers. Maintain required contrast ration and + instead signal to your users with some other visual dinstinction. + +#### How to test + +Keyboard accessibility is generally more familiar to developers than +magnification tools, but Take this opportunity to familiarize yourself with +macOS Zoom Windows Magnifier, or your OS's native low vision accessibility tools +as they are relied on by millions of people with temporary or permanent vision +impairment every day. + +## FAQ + +##### Using DAP👷 + +Let's DAP! It's pretty straight forward, but there are a few gotchas. For +consistency's sake we'll use DAP on the +[Dynamic Assessment Plug-in Homepage](https://ibm.biz/BdYkM9). + +Head over to the page and hit `cmd-option-c` to open up your dev tools. DAP is +tucked away inside a drop down menu inside a panel. From the default Elements +panel hit the >> icon below the X on the far right. You should see `DAP`. Click +that to fire up DAP for this page. + +_Be Warned: You can only run DAP with internal IBM rulesets if you're connected +to W3. On an IBM campus this isn't a problem, but if you're abroad fire up the +Cisco AnyConnect Secure Mobility Client._ + +Hit the play button and wait for the scan to finish. **We've got violations!**. +At the time of writing there are 7 Violations, 9 Potential Violations, and 2 +Manual Checks. There's also multiple "frames", but if you're testing single +components or a group of components in a Storybook environment you can ignore +those✋. + +On the main frame (the one open by default) there's a detailed list of all +violation types. Clicking into each violation type gives you more nested +dropdowns -- one for each violation found on the page of that specific type. +Each violation's dropdown gives you two further options: + +1. A description of the general violation with a ? icon that when clicked will + take you to further documentation detailing the violation and most helpfully + how to fix it. +2. A description of this particular instance of a violation (say for instance + an image with no alt attribute). And a crossed out eyeball you can click to + ignore this violation which is helpful when printing reports for posterity's + sake.