From 4a8b0f3b65af3c8aa31a6ca9f454516d422ed431 Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam.kudrna@lmc.eu>
Date: Tue, 27 Feb 2024 17:33:38 +0100
Subject: [PATCH] fixup! fixup! Feat(web): Introduce the `Toast` component
 #DS-1112

---
 .../web/src/scss/components/Toast/README.md   | 31 ++++++++++++-------
 .../web/src/scss/components/Toast/index.html  |  2 +-
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/packages/web/src/scss/components/Toast/README.md b/packages/web/src/scss/components/Toast/README.md
index 9c06f53567..6f023ae777 100644
--- a/packages/web/src/scss/components/Toast/README.md
+++ b/packages/web/src/scss/components/Toast/README.md
@@ -9,11 +9,11 @@ Toast is a composition of a few subcomponents:
 
 ## Toast
 
-The Toast component is a container for the ToastBar component. It is responsible for positioning the
-[ToastBar](#toastbar) component, even when there are [multiple of them](#toast-queue).
+The Toast component is a container responsible for positioning the [ToastBar](#toastbar) component. It is capable of
+handling even multiple toast messages at once, stacking them in a [queue](#toast-queue).
 
 ```html
-<div class="Toast" aria-live="polite">
+<div class="Toast" role="log">
   <div class="Toast__queue">
     <!-- ToastBar components go here -->
   </div>
@@ -22,13 +22,14 @@ The Toast component is a container for the ToastBar component. It is responsible
 
 ### Accessibility
 
-The wrapping Toast container has the [`aria-live="polite"`][mdn-aria-live] attribute set, which will announce any
-**dynamic changes** inside the container as they happen. In order for this to work, the Toast component **must be
-present in the DOM** on the initial page load, even when empty.
+The wrapping Toast container has the [`role="log"`][mdn-role-log] attribute set (which results in an implicit
+[`aria-live`][mdn-aria-live] value of `polite`). Assistive technologies then announce any **dynamic changes** inside the
+container as they happen. In order for this to work, the Toast component **must be present in the DOM** on the initial
+page load, even when empty.
 
-👉 Unless you are absolutely sure that your toast messages are critical to interrupt the user, you should keep the
-`polite` value of the `aria-live` attribute. When set to `assertive`, assistive technologies immediately notify the
-user, potentially clearing the speech queue of previous updates.
+👉 Unless you are absolutely sure that your toast messages are critical to interrupt the user, you should not change the
+(implicit) `polite` value of the [`aria-live`][mdn-aria-live] attribute. When set to `assertive`, assistive technologies
+immediately notify the user, potentially clearing the speech queue of previous updates.
 
 ### Alignment
 
@@ -56,7 +57,7 @@ middle of the screen.
 Example:
 
 ```html
-<div class="Toast Toast--bottom Toast--right" aria-live="polite">
+<div class="Toast Toast--bottom Toast--right" role="log">
   <div class="Toast__queue">
     <!-- ToastBar components go here -->
   </div>
@@ -72,7 +73,7 @@ modifiers to change the alignment of the Toast component starting on a specific
 Example:
 
 ```html
-<div class="Toast Toast--bottom Toast--center Toast--tablet--right" aria-live="polite">
+<div class="Toast Toast--bottom Toast--center Toast--tablet--right" role="log">
   <div class="Toast__queue">
     <!-- ToastBar components go here -->
   </div>
@@ -158,6 +159,10 @@ An action link can be added to the ToastBar component:
 </div>
 ```
 
+👉 **Do not put any important actions** like "Undo" in the ToastBar component (unless there are other means to perform
+said action), as it is very hard (if not impossible) to reach for users with assistive technologies. Read more about
+[Toast accessibility](#scott-o-hara-toast) at Scott O'Hara's blog.
+
 ### Colors
 
 The ToastBar component is available in all [emotion colors][dictionary-color], plus the `inverted` variant (default).
@@ -203,7 +208,7 @@ To make the ToastBar dismissible, add the `ToastBar--dismissible` modifier class
 
 ```html
 <!-- Toast: start -->
-<div class="Toast Toast--bottom Toast--center" aria-live="polite">
+<div class="Toast Toast--bottom Toast--center" role="log">
   <div class="Toast__queue">
     <!-- ToastBar: start -->
     <div id="my-dismissible-toast" class="ToastBar ToastBar--inverted ToastBar--dismissible">
@@ -235,6 +240,8 @@ To make the ToastBar dismissible, add the `ToastBar--dismissible` modifier class
 <!-- Toast: end -->
 ```
 
+[mdn-role-log]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/log_role
 [mdn-aria-live]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live
 [dictionary-alignment]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#alignment
 [dictionary-color]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#color
+[scott-o-hara-toast]: https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html
diff --git a/packages/web/src/scss/components/Toast/index.html b/packages/web/src/scss/components/Toast/index.html
index f44e3bd9cd..3b70f4fd12 100644
--- a/packages/web/src/scss/components/Toast/index.html
+++ b/packages/web/src/scss/components/Toast/index.html
@@ -72,7 +72,7 @@ <h2 class="docs-Heading">Alignment</h2>
     </form>
     <!-- Toast and visual keyboard demo: end -->
 
-    <div id="toast-example" class="Toast Toast--bottom Toast--center" aria-live="polite">
+    <div id="toast-example" class="Toast Toast--bottom Toast--center" role="log">
       <div class="Toast__queue">
 
         <div id="my-dismissible-toast" class="ToastBar ToastBar--success ToastBar--dismissible">