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 -
+
@@ -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 -
+
@@ -72,7 +73,7 @@ modifiers to change the alignment of the Toast component starting on a specific Example: ```html -
+
@@ -158,6 +159,10 @@ An action link can be added to the ToastBar component:
``` +👉 **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 -
+
@@ -235,6 +240,8 @@ To make the ToastBar dismissible, add the `ToastBar--dismissible` modifier class ``` +[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 @@

Alignment

-
+