From 6d555a6050f012622291dd99a118375f046ebcfe Mon Sep 17 00:00:00 2001
From: Sarka Chwastkova <chwastkova.s@gmail.com>
Date: Fri, 15 Nov 2024 17:54:06 +0100
Subject: [PATCH] docs: add accessibility props to Tooltip

---
 docs/src/__examples__/Tooltip/INDICATION.tsx  | 20 +++--
 .../04-overlay/tooltip/03-accessibility.mdx   | 84 +++++++++++++++++++
 2 files changed, 99 insertions(+), 5 deletions(-)
 create mode 100644 docs/src/documentation/03-components/04-overlay/tooltip/03-accessibility.mdx

diff --git a/docs/src/__examples__/Tooltip/INDICATION.tsx b/docs/src/__examples__/Tooltip/INDICATION.tsx
index 0b3f1f3b0f..a7216e37f8 100644
--- a/docs/src/__examples__/Tooltip/INDICATION.tsx
+++ b/docs/src/__examples__/Tooltip/INDICATION.tsx
@@ -25,8 +25,10 @@ export default {
                 <Text>An open source design system for your next travel project.</Text>
               </Stack>
             }
+            aria-label="Orbit design system"
+            aria-labelledby="orbit-success"
           >
-            <Text>Orbit</Text>
+            <Text id="orbit-app">Orbit</Text>
           </Tooltip>{" "}
           a try.
         </Text>
@@ -41,15 +43,21 @@ export default {
                 <Text>An open source design system for your next travel project.</Text>
               </Stack>
             }
+            aria-label="Orbit design system"
+            aria-labelledby="orbit-success"
           >
-            <Text>Orbit </Text>
+            <Text id="orbit-success">Orbit </Text>
           </Tooltip>
           a try.
         </Alert>
         <Alert icon={<Visa />} type="warning">
           You
-          <Tooltip content={<Text>Check with your embassy.</Text>}>
-            <Text>may need a visa </Text>
+          <Tooltip
+            content={<Text>Check with your embassy.</Text>}
+            aria-label="You may need a visa"
+            aria-labelledby="orbit-warning"
+          >
+            <Text id="orbit-warning">may need a visa </Text>
           </Tooltip>
           for your trip.
         </Alert>
@@ -65,8 +73,10 @@ export default {
                 <Text>An open source design system for your next travel project.</Text>
               </Stack>
             }
+            aria-label="Orbit design system"
+            aria-labelledby="orbit"
           >
-            <Text>Orbit</Text>
+            <Text id="orbit">Orbit</Text>
           </Tooltip>
         </Text>
       </Stack>
diff --git a/docs/src/documentation/03-components/04-overlay/tooltip/03-accessibility.mdx b/docs/src/documentation/03-components/04-overlay/tooltip/03-accessibility.mdx
new file mode 100644
index 0000000000..0efd126920
--- /dev/null
+++ b/docs/src/documentation/03-components/04-overlay/tooltip/03-accessibility.mdx
@@ -0,0 +1,84 @@
+---
+title: Accessibility
+redirect_from:
+  - /components/tooltip/accessibility/
+---
+
+# Accessibility
+
+## Tooltip
+
+The Tooltip component has been designed with accessibility in mind.
+
+It can be used with keyboard navigation, and it includes the following properties that allow to improve the experience for users of assistive technologies:
+
+| Name            | Type     | Description                                                                               |
+| :-------------- | :------- | :---------------------------------------------------------------------------------------- |
+| aria-label      | `string` | Adds `aria-label` attribute to the rendered tooltip element. Announced by screen readers. |
+| aria-labelledby | `string` | Id(s) of elements that announce the component to screen readers.                          |
+
+Mentioned props are optional, but highly recommended to use to ensure the best accessibility experience for all users.
+
+The `aria-label` prop can be used to provide a label for the tooltip that is announced by screen readers.
+
+The `aria-labelledby` prop can reference multiple ids, separated by a space. Value of the attribute is not announced by screen reader, content of connected
+element does.
+
+The conjugation of these properties allows to provide a content of tooltip component to users of assistive technologies.
+
+For example, the following code snippet shows how to use these properties:
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet</p>
+    </div>
+  }
+  aria-label="Tooltip label"
+  aria-labelledby="tooltip-labelledby"
+>
+  <Text id="tooltip-labelledby">Hello world.</Text>
+</Tooltip>
+```
+
+Note that attribute `aria-labelledby` is connected with `id` attribute of the component that is the base for the Tooltip. Without that connection, the `aria-labelledby` attribute is ignored and not read by screen reader.
+
+The content of attribute `aria-labelledby` is prioritized before the content of `aria-label`. In case `aria-labelledby` is not filled in,
+then the content of `aria-label` is read by screen reader.
+
+Be sure to include all relevant information on all of the properties that are announced by screen readers.
+
+### Examples
+
+1. Prop `id` in `<Text>` component is not filled in, content of `aria-label` is read by screen reader. Then the content inside the tooltip is read by screen reader. Content of `aria-labelledby` is ignored.
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet</p>
+    </div>
+  }
+  aria-label="Tooltip label"
+  aria-labelledby="tooltip-labelledby"
+>
+  <Text>Hello world.</Text>
+</Tooltip>
+```
+
+2. Prop `id` in `<Text>` component is filled in, content of this component (`Hello world`) is read by screen reader. Then the content inside the tooltip is read by screen reader. Content of `aria-label` is not read at all.
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet</p>
+    </div>
+  }
+  aria-label="Tooltip label"
+  aria-labelledby="tooltip-labelledby"
+>
+  <Text id="tooltip-labelledby">Hello world.</Text>
+</Tooltip>
+```