From 1c070186af40f31f6a24a5846d4ec15c0fed2a18 Mon Sep 17 00:00:00 2001 From: Daniel Koskinen Date: Tue, 26 Sep 2023 16:46:43 +0300 Subject: [PATCH 1/4] Documentation: Add section on accessibility. Adds a section which describes the process for ensuring accessibility within the library. --- .styleguidist/accessibility.md | 82 ++++++++++++++++++++++++++ .styleguidist/introduction.md | 2 +- .styleguidist/styleguidist.sections.js | 6 ++ 3 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 .styleguidist/accessibility.md diff --git a/.styleguidist/accessibility.md b/.styleguidist/accessibility.md new file mode 100644 index 000000000..6c9427637 --- /dev/null +++ b/.styleguidist/accessibility.md @@ -0,0 +1,82 @@ +Our goal is to be WCAG 2.1 compliant at an AA level for all components. Additionally, components are tested in commonly used user agents and with common assistive technology. We also aim to support Windows High Contrast mode. + +Using the Suomi.fi component library does not automatically make your project accessible, but it will hopefully significantly reduce the amount of work you need to do to provice an accessible user experience. It is important to read the documentation for each component carefully. + +## Known issues + +* **MultiSelect** and **SingleSelect**: Options are not read out by VoiceOver on macOS when using Safari. +* **MultiSelect** and **SingleSelect**: The selected state of an option is not read out by JAWS. +* **Breadcrumb**: Line-height does not adjust when only text is resized 200%. +* **Dropdown**: Line-height does not adjust when only text is resized 200%. +* **DateInput**: Disabled dates are not distuinguishable from non-disabled ones in Windows High Contrast mode. +* **Textarea** and **TextInput**: Success/error states are not distinguishable without colour. + +## Our accessibility checklist + +### On the tests + +This checklist reflects the current features of the component library. It is not meant to be a comprehensive WCAG checklist. For example, we do not test for Page Titled (WCAG-criterion 2.4.2), because the component library only includes invividual components, not pages. Similarly, we do not have a test for Captions (WCAG-criterion *2.2) or other media-related criteria, because there is no video content within our components. You should always do your own accessibility testing. A good start is the WebAIM WCAG 2 Checklist. + +### Automated + +* No errors reported by axe Devtools. + +### Visual inspection + +* Text contrast is at least 4.5:1 in each component state +* The contrast of essential non-text information is at least 3:1 with its surrroundings. +* Colour is not used as the only way to convey information. + +### Keyboard and pointer device + +* All functionality can be accessed with keyboard +* Keyboard focus is clearly visible +* The keyboard focus order within a component is logical +* Focusing a component or its sub-component does not cause a change of context. +* Component has no single-character shortcuts. + +### Pointer devices + +* Focusing or hovering a component or its sub-component does not cause a change of context. +* No actions are performed using the pointer down-event, unless it is native functionality defined by the user-agent. + +### Adaptability + +* Text resizing to 200% does not cause loss of information or overlapping content. **Must** support full-page zoom. **Should** support text-only zoom. +* Changing text settings according to WCAG *4.12 does not cause loss of information or overlap. +* Zooming to 400% in a 1280px wide window does not cause horizontal scrolling, loss or overlap of information. +* Content is not limited to a specific device orientation. + +### Code inspection + +* Lists are marked using the correct HTML elements. +* Correct semantic elements are used where appropriate (headings, lists) +* For components with text in a different language than the surrounding text, check that the language can be programmatically evaluated. + +### Windows High Contrast mode + +* Components and their different states are distinguishable when running in Windows High Contrast Mode. +* Keyboard focus is visible when running in Windows High Contrast Mode. + +### Motion + +* If the component has animations, check that they respect the Reduced Motion platform setting. + +### Screen reader tests and support + +Officially supported browser / screen reader combinations: + +| Operating system | Browsers | Screen reader | +| ---------------- | --------------------- | ------------- | +| macOS | Safari, Chrome, Edge | VoiceOver | +| Windows | Chrome, Firefox, Edge | NVDA | +| iOS | Safari | VoiceOver | +| Android | Chrome | TalkBack | + +Additionally, components are tested using Narrator and Edge in Windows, the latest JAWS version and Chrome on Windows, and Orca and Firefox on Linux. + +All content should be available in reading mode, and all interactive functionality available in focus mode. Commands vary in different screen readers, and support for different HTML and ARIA features also varies and can depend both on what the accessibility tree of the browser exposes, as well as the screen reader itself. + +### Other assistive technology + +When appropriate, components are tested using Voice Control on macOS and voice access on Windows. diff --git a/.styleguidist/introduction.md b/.styleguidist/introduction.md index 0005c64af..daf8b180b 100644 --- a/.styleguidist/introduction.md +++ b/.styleguidist/introduction.md @@ -2,7 +2,7 @@ ## ✨ Features -- Accessibility WCAG 2.1 level AA +- Accessibility WCAG 2.1 level AA. Read more on accessibility support. - React-components with TypeScript support - Suomi.fi brand styles - Highly customizable (CSS, CSS-in-JS) diff --git a/.styleguidist/styleguidist.sections.js b/.styleguidist/styleguidist.sections.js index 4dd7c6224..f6817b81d 100644 --- a/.styleguidist/styleguidist.sections.js +++ b/.styleguidist/styleguidist.sections.js @@ -71,6 +71,12 @@ module.exports = { sections: [() => {}], sectiondepth: 0, }, + { + name: 'Accessibility', + content: './.styleguidist/accessibility.md', + sections: [() => {}], + sectiondepth: 0, + }, { name: 'Foundations', content: './.styleguidist/foundations.md', From c86ebed5819331b58aa413687384a7004084a775 Mon Sep 17 00:00:00 2001 From: Daniel Koskinen Date: Tue, 26 Sep 2023 17:13:05 +0300 Subject: [PATCH 2/4] Add table of contents to accessibility documentation --- .styleguidist/accessibility.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.styleguidist/accessibility.md b/.styleguidist/accessibility.md index 6c9427637..4cc408382 100644 --- a/.styleguidist/accessibility.md +++ b/.styleguidist/accessibility.md @@ -2,6 +2,21 @@ Our goal is to be WCAG 2.1 compliant at an AA level for all components. Addition Using the Suomi.fi component library does not automatically make your project accessible, but it will hopefully significantly reduce the amount of work you need to do to provice an accessible user experience. It is important to read the documentation for each component carefully. +* [Known issues](./#/Accessibility?id=known-issues) +* [Our acccessibility checklist](./#/Accessibility?id=our-accessibility-checklist) + * [On the tests](./#/Accessibility?id=on-the-tests) + * [Automated](./#/Accessibility?id=automated) + * [Visual inspection](./#/Accessibility?id=visual-inspection) + * [Keyboard](./#/Accessibility?id=keyboard) + * [Pointer devices](./#/Accessibility?id=pointer-devices) + * [Adaptability](./#/Accessibility?id=adaptability) + * [On the tests](./#/Accessibility?id=on-the-tests) + * [Code inspection](./#/Accessibility?id=code-inspection) + * [Windows High Contrast Mode](./#/Accessibility?id=windows-high-contrast-mode) + * [Motion](./#/Accessibility?id=motion) + * [Screen reader tests and support](./#/Accessibility?id=screen-reader-tests-and-support) + * [Other assistive technology](./#/Accessibility?id=other-assistive-technology) + ## Known issues * **MultiSelect** and **SingleSelect**: Options are not read out by VoiceOver on macOS when using Safari. From 9e4ed61b2902bb1d291fb4431575846c09f9d497 Mon Sep 17 00:00:00 2001 From: Daniel Koskinen Date: Mon, 2 Oct 2023 11:34:11 +0300 Subject: [PATCH 3/4] Accessibility documentation: Remove extra link from table of contents. --- .styleguidist/accessibility.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.styleguidist/accessibility.md b/.styleguidist/accessibility.md index 4cc408382..de0916b97 100644 --- a/.styleguidist/accessibility.md +++ b/.styleguidist/accessibility.md @@ -10,7 +10,6 @@ Using the Suomi.fi component library does not automatically make your project ac * [Keyboard](./#/Accessibility?id=keyboard) * [Pointer devices](./#/Accessibility?id=pointer-devices) * [Adaptability](./#/Accessibility?id=adaptability) - * [On the tests](./#/Accessibility?id=on-the-tests) * [Code inspection](./#/Accessibility?id=code-inspection) * [Windows High Contrast Mode](./#/Accessibility?id=windows-high-contrast-mode) * [Motion](./#/Accessibility?id=motion) From 8aea13c82c8e58a68d9d2bf5ee34c19db5669cdb Mon Sep 17 00:00:00 2001 From: Daniel Koskinen Date: Tue, 3 Oct 2023 09:26:00 +0300 Subject: [PATCH 4/4] Accessibility documentation: Added mention of WCAG 2.2 and improved the summary --- .styleguidist/accessibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.styleguidist/accessibility.md b/.styleguidist/accessibility.md index de0916b97..1f9b8536f 100644 --- a/.styleguidist/accessibility.md +++ b/.styleguidist/accessibility.md @@ -1,4 +1,4 @@ -Our goal is to be WCAG 2.1 compliant at an AA level for all components. Additionally, components are tested in commonly used user agents and with common assistive technology. We also aim to support Windows High Contrast mode. +Our goal is to be WCAG 2.1 (and eventually WCAG 2.2) compliant at an AA level for all components. Additionally, components are tested in commonly used user agents and with common assistive technology. We also aim to support Windows High Contrast mode. Based on our testing, almost all components fulfill these goals, with a few [outstanding issues](./#Accessibility?=known-issues). Using the Suomi.fi component library does not automatically make your project accessible, but it will hopefully significantly reduce the amount of work you need to do to provice an accessible user experience. It is important to read the documentation for each component carefully. @@ -20,10 +20,10 @@ Using the Suomi.fi component library does not automatically make your project ac * **MultiSelect** and **SingleSelect**: Options are not read out by VoiceOver on macOS when using Safari. * **MultiSelect** and **SingleSelect**: The selected state of an option is not read out by JAWS. +* **Textarea** and **TextInput**: Success/error states are not distinguishable without colour. * **Breadcrumb**: Line-height does not adjust when only text is resized 200%. * **Dropdown**: Line-height does not adjust when only text is resized 200%. * **DateInput**: Disabled dates are not distuinguishable from non-disabled ones in Windows High Contrast mode. -* **Textarea** and **TextInput**: Success/error states are not distinguishable without colour. ## Our accessibility checklist