Move to monorepo (combined PR's)

config/tokens.json

@@ -818,6 +818,10 @@
         "value": "{color.green-800}",
         "type": "color",
         "description": "Focus state (keyboard navigation)"
+      },
+      "bg-white": {
+        "value": "{color.white}",
+        "type": "color"
       }
     },
     "manage--color": {
@@ -920,6 +924,10 @@
       "input-default": {
         "value": "{borderWidth.xs}",
         "type": "borderWidth"
+      },
+      "input-active": {
+        "value": "{borderWidth.sm}",
+        "type": "borderWidth"
       }
     },
     "text-label-md": {
@@ -1076,6 +1084,11 @@
   },
   "$themes": [],
   "$metadata": {
-    "tokenSetOrder": ["global", "org", "me", "at"]
+    "tokenSetOrder": [
+      "global",
+      "org",
+      "me",
+      "at"
+    ]
   }
-}
+}

src/about_the_design_system.stories.mdx

@@ -4,19 +4,21 @@ import { Meta } from '@storybook/addon-docs'
 
 # About the Design System
 
-## Goal
+## Purpose
 
-We want to break down things in order to have a modular system that enables us to
+With the design system we mainly want to break down _things_ in order to have a modular system that enables us to
 
-- **reuse** things (save time) and
+- **reuse** things (design and develop faster) and
 - keep things **consistent** (improve UX and maintainability).
 
+We also want to provide clear and comprehensive guides for designers, copy writers, developers and testers to facilitate better collaboration and communication.
+
 ## Structure
 
-A design system is more than a “component inventory”. Our design system consists of the following parts:
+The design system is more than a “component inventory”. Our design system consists of the following parts:
 
-- Guides: 🚧 **TBD Add short description**
-- Tokens: 🚧 **TBD Add short description**
-- Elements: 🚧 **TBD Add short description**
-- Components: 🚧 **TBD Add short description**
+- Guides: Guidelines, principles, and best practices for designers, copy writers, developers and testers
+- Tokens: Variables that define the visual attributes of the design system
+- Elements: Bare HTML elements with defined visual properties
+- Components: Specific self-contained UI components
 - 🚧 **TBD Will there be more? Hooks? Lib?**

src/guides/accessibility_guide.stories.mdx

@@ -13,12 +13,33 @@ import { Meta } from '@storybook/addon-docs'
 
 ### What is web accessibility?
 
-- „Web accessibility means that websites, tools, and technologies are designed and developed so that **people with disabilities can use them**.” [[1]](https://www.w3.org/WAI/fundamentals/accessibility-intro/#what)
+- „Web accessibility means that websites, tools, and technologies are designed and developed so that **people with disabilities** can use them.” [[1]](https://www.w3.org/WAI/fundamentals/accessibility-intro/#what)
 - Web accessibility involves a wide range of disabilities including **auditory**, **cognitive**, **neurological**, **physical**, **speech** and **visual**.
+- Web accessibility is one aspect of **inclusive design**. Inclusive design describes methodologies to build products that can be accessed and used by as many people as possible. It may address disabilities, age, economic situation, geographic location, language, race, and more.
+- Inclusive design – and thus also accessibility – is one aspect of **usability**. Usability is defined by the “extend to which a product can be used by specified users to achieve specified goals effectively, efficiently and with satisfaction in a specified context.” It depends on the specified users which role accessibility and inclusivity play.
 
-### Web Content Accessibility Guidelines (WCAG)
+### How do people with disabilties use the web?
+
+- People with disabilities might use high-tech assistive technologies to extend their capabilities, e.g.
+  - keyboards (instead of pointing devices),
+  - screen readers,
+  - braille displays,
+  - voice recognition software,
+  - switch controls and
+  - screen magnifiers.
+- People with disabilities might adjust operating system and browser settings, e.g.
+  - dark mode,
+  - high-contrast mode and
+  - font size.
+
+**Further information:**
+
+- [List of videos](https://tetralogical.com/blog/2021/12/24/browsing-with-assistive-technology-videos/) that provide good insight into browsing with existive technologies
+
+#### Web Content Accessibility Guidelines (WCAG)
 
 - The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) are an internationally agreed upon standard established to help developing accessible web content.
+- The latest stable version is WCAG 2.1. WCAG 2.2 is a working draft published in August 2020. WCAG 3 (Silver) is under development.
 - The guidelines are organized by four main principles (POUR):
   - **Perceivable** – Information and user interface components must be presentable to users in ways they can perceive.
   - **Operable** – User interface components and navigation must be operable.
@@ -29,13 +50,30 @@ import { Meta } from '@storybook/addon-docs'
   - **A (Basic)** – If this isn't met, assistive technology may not be able to read, understand, or fully operate the page or view.
   - **AA (Ideal)** – Required for multiple government and public body websites.
   - **AAA (Specialized support)** – This is typically reserved for parts of websites and web apps that serve a specialized audience.
+- Achieving Level AAA is usually not possible, but aiming to satisfy at least some of the criteria in this level is an attainable goal.
+- WCAG doesn't tackle _all_ possible accessibility barriers. So even if we technically satisfy all of them, we might still have usability and accessibility issues.
 
-<br />
+> Accessibility is about making things work for people. It's not passing an assessment or ticking a box to say you meet a standard. It's about people and their needs just like any other part of user centred design. Do legal compliance as the absolute minimum, but always go further! — Craig Abbott, Head of Accessibility at DWP Digital
+
+**Further information:**
 
 <a href="https://intopia.digital/wp-content/uploads/2019/10/2019-WCAG2.1-Map-Intopia-plus-reading-order.pdf">
   <img src="a11y_map_intopia.png" alt="Intopia WCAG2.1 map" width="50%" />
 </a>
 
+#### Specifications and guidelines (from a German perspective)
+
+- In Germany IT accessibility is regulated by several specifications and guidelines.
+- The EU norm **EN 301 549** with the title ”Accessibility requirements for ICT products and services” refers to **WCAG 2.1.** — it introduces some additional criteria though.
+- The EU directive **(EU) 2016/2102** obliges all **public bodies** in the EU to be accessible according to EN 301 54. The **Barrierefreie Informationstechnik-Verordnung** (BITV) implements this regulation in Germany.
+- The **European Accessibility Act** (EAA) and the therefrom derived Barrierefreiheitsstärkungsgesetz also obliges the private sector to offer accessible products. Specific products (e.g. ATMs, websites of passenger transport services) placed on the market after 28 June 2025 have to be accessible.
+
+<br />
+
+- **Further information:**
+- [Overview of specifications and guidelines in Germany (German only)](https://www.cio.bund.de/Webs/CIO/DE/digitaler-wandel/it-barrierefreiheit/vorgaben-und-richtlinien/vorgaben-und-richtlinien-node.html)
+- [Overview of EN 301 549 (German only)](https://www.barrierefreiheit-dienstekonsolidierung.bund.de/Webs/PB/DE/gesetze-und-richtlinien/en301549/en301549-node.html)
+
 ### Best practices
 
 General remark: Use these best practices thoughtfully. Always keep in mind that accessibility is not only about following rules, but about the best way to serve the needs of users.
@@ -49,7 +87,7 @@ General remark: Use these best practices thoughtfully. Always keep in mind that
 
 - All information-bearing elements must at least have a contrast of 4.5:1 (to background)
 - Exceptions are UI controls (e.g. check in checkbox) color fills, text bigger than 18px (bold). They only need 3:1.
-- Disabled and decorative elements don’t need to reach a contrast ratio: but even better is they do!
+- Disabled and decorative elements don't need to reach a contrast ratio: but even better is they do!
 - Design color independently. That means, an interface needs to be understood in gray scale as well.
 
 #### Interaction
@@ -71,12 +109,12 @@ Everything that can be swiped or dragged, needs also being able to be clicked/ta
 #### Content
 
 - Each link that links to a unique url should have a unique and out of context understandable link text.
-- All CTAs should include the main keyword and action verb within the first 1-3 words of the text/label (that’s all our brain focuses on and reads before making a decision).
-- Every link is a promise: make it precise and transparent where it’ll lead.
+- All CTAs should include the main keyword and action verb within the first 1-3 words of the text/label (that's all our brain focuses on and reads before making a decision).
+- Every link is a promise: make it precise and transparent where it'll lead.
 
 **Tip:** To avoid “show/read more links” link the headline of the content.
 
-- Show hints and error messages right after the label (otherwise the user won’t know what to look out for before filling in the input).
+- Show hints and error messages right after the label (otherwise the user won't know what to look out for before filling in the input).
   Never show important text below a CTA for the same reason.
 - Make sure sighted and people with visual deficiency as well as cognitive disabilities (or tired and stressed people) can also skip through a page by using concise and comprehensive link/heading/button copy.
 - Make sure all information-bearing icons, graphics and illustrations have an ALT text.
@@ -170,12 +208,13 @@ and based on that decide which approach is most appropriate.
 
 #### Mainly for developers
 
-- [Introduction to some main accessibility topics](https://web.dev/accessible/) by _Google’s web.dev_
-- _Mozilla’s_ [guide to accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
-- _Google’s_ [guide to accessibility](https://developers.google.com/web/fundamentals/accessibility)
+- [Introduction to some main accessibility topics](https://web.dev/accessible/) by _Google's web.dev_
+- _Mozilla's_ [guide to accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
+- _Google's_ [guide to accessibility](https://developers.google.com/web/fundamentals/accessibility)
 - [An extensive list of accessible components including links to further information](https://www.smashingmagazine.com/2021/03/complete-guide-accessible-front-end-components/) by _Smashing Magazine_
 - [Interactive video course](https://www.udacity.com/course/web-accessibility--ud891) by _Udacity_
 - [Playlist of short _YouTube_ tutorials](https://www.youtube.com/playlist?list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g)
+- [WAI-ARIA Cheatsheet](https://lab.abhinayrathore.com/aria-cheatsheet/)
 
 <br />
 
@@ -205,14 +244,14 @@ _In a later expansion stage_
 ### 3. Refinement
 
 - Use [checklist](https://not-checklist.intopia.digital/) to make sure the planned implementation considers a11y.
-- 🚧 Define a11yAC’s
+- 🚧 Define a11yAC's
 
 ### 4. Implementation
 
 #### 4.1 Development & Automated testing
 
 - Use [linter](https://www.npmjs.com/package/eslint-plugin-jsx-a11y) and [logging to the browser's console](https://www.npmjs.com/package/@axe-core/react) to catch and fix a11y issues early.
-- Read a11yAC’s (and eventually have a look at the [checklist](https://not-checklist.intopia.digital/) again) to know what to code and how to test.
+- Read a11yAC's (and eventually have a look at the [checklist](https://not-checklist.intopia.digital/) again) to know what to code and how to test.
 - Follow coding standards to avoid minor recurring a11y problems.
 
 _In a later expansion stage_
@@ -222,7 +261,7 @@ _In a later expansion stage_
 
 #### 4.2 Manual testing
 
-- Read a11yAC’s to know what to test and how.
+- Read a11yAC's to know what to test and how.
 - Follow [manual testing guidelines](?path=/story/guides-testing-guide--page)
 
 ### 5. Measurement
@@ -249,4 +288,4 @@ _In a later expansion stage_
 _In a later expansion stage_
 
 - Build accessible design system.
-- Derive a11yAC templates from a11yAC’s.
+- Derive a11yAC templates from a11yAC's.

src/guides/testing_guide.stories.mdx

@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/addon-docs'
 
-<Meta title="Guides/Testing guide" />
+<Meta title="Guides/Manual testing guide" />
 
 # Manual testing guide
 
@@ -9,9 +9,88 @@ import { Meta } from '@storybook/addon-docs'
 ## Testing accessibility
 
 - Test with a **pointing device** (e.g. a computer mouse) and **touch device** to ensure interactive elements work.
+- Test responsiveness and touch usability on **mobile** devices.
 - **Zoom** in and out (ctrl +/-) and change the font size in your browser settings to ensure content is accessible outside your standard view.
-- Test with **only a keyboard** to ensure all content is accessible without using a pointing or touch device. ([Intro to keyboard testing](https://webaim.org/techniques/keyboard/))
-- Test with a **screen reader** to ensure all content is accessible and coherent when read aloud. ([Intro to using a screen reader](https://tetralogical.com/blog/2021/09/29/browsing-with-a-desktop-screen-reader/))
+- Test with **only a keyboard** (learn how below) to ensure all content is accessible without using a pointing or touch device.
+- Test with **screen readers** (learn how below) to ensure all content is accessible and coherent when read aloud.
 - If content changed / has been added: Read through the **content** to ensure everything is understandable.
-- If design changed / new: Emulate **color vision deficiencies** to ensure content is distinguishable.
-- Test responsiveness and touch usability on **mobile** devices ([Intro to mobile accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/Mobile)).
+- If design changed / is new: Emulate **color vision deficiencies** (learn how below) to ensure content is distinguishable.
+
+### How to test with only a keyboard
+
+- Browser keyboard navigation has to be enabled manually on MacOS: https://www.a11yproject.com/posts/macos-browser-keyboard-navigation/
+- [Intro to keyboard testing](https://webaim.org/techniques/keyboard/)
+- [Browsing with a keyboard](https://tetralogical.com/blog/2021/10/26/browsing-with-a-keyboard/)
+
+### How to test with screen readers
+
+#### Getting started
+
+- [Browsing with a desktop screen reader](https://tetralogical.com/blog/2021/09/29/browsing-with-a-desktop-screen-reader/)
+- [Browsing with a mobile screen reader](https://tetralogical.com/blog/2021/10/05/browsing-with-a-mobile-screen-reader/)
+- [Introduction to screen reader usage](https://www.accessibility-developer-guide.com/knowledge/screen-readers/)
+
+#### Which browser and screen reader pairings to test
+
+According to a [survey](https://webaim.org/projects/screenreadersurvey9/) conducted by WebAIM, more than 90% of screen reader users reported using a desktop screen reader on Windows.
+
+The most popular **desktop screen readers** are
+
+- **JAWS** (Windows, can run in free demo mode for 40 minutes at a time)
+- **NVDA** (Windows, free) and
+- **VoiceOver** (MacOS, free).
+
+The by far most popular **mobile screen readers** is **VoiceOver on iOS/iPadOS**.
+
+Testing with screen readers work best when they are paired with the browsers they are the most compatible with.
+
+- JAWS works best with Chrome and Firefox. When testing, it should be paired with Chrome.
+- NVDA works best with and should be paired with Firefox.
+- VoiceOver (MacOS and iOS/iPadOS) works best with and should be paired with Safari.
+
+**At betterplace** we test with:
+
+- NVDA (Windows)
+- VoiceOver (iOS/iPadOS)
+
+#### How to test with NVDA (Windows)
+
+As NVDA only runs on Windows, but we use Macs at betterplace, we have to either set up a [virtual machine](https://dequeuniversity.com/mac/windows-screen-readers) or use a service similar to BrowserStack or [AssistivLabs](https://assistivlabs.com/pricing).
+
+- [NVDA Browse Mode](https://www.nvaccess.org/files/nvda/documentation/userGuide.html?#BrowseMode)
+- [NVDA Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)
+
+#### How to test with VoiceOver (iOS/iPadOS)
+
+- [iPhone User Guide](https://support.apple.com/en-lb/guide/iphone/iph3e2e415f/ios)
+- [Summary of screen reader testing on iOS](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/Mobile#ios_voiceover)
+
+#### How to test with other screen readers (optional)
+
+- [JAWS Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts)
+- [VoiceOver (MacOS) User Guide](https://support.apple.com/en-lb/guide/voiceover/welcome/10/mac)
+- [VoiceOver (MacOS) Keyboard Shortcuts](https://dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)
+
+### How to test for color vision deficiencies
+
+#### In Firefox
+
+- Open _Accessibility_ panel.
+- Choose from a selection of different color vision deficiencies in the _Simulate_ drop-down.
+
+<img
+  src="color_vision_deficiencies_settings_firefox.png"
+  alt="Color vision deficiencies settings in Firefox"
+  width="50%"
+/>
+
+#### In Chrome
+
+- Open the _Rendering_ panel (either use the command menu and type _rendering_ or use the three-dot menu in the top-right corner of the screen and go to _More Tools_ to find it).
+- Choose from a selection of different color vision deficiencies in the _Emulate vision deficiencies_ drop-down.
+
+<img
+  src="color_vision_deficiencies_settings_chrome.png"
+  alt="Color vision deficiencies settings in Chrome"
+  width="50%"
+/>