From 49b9c600e09c22c60cee287dc9186a723a1e6a26 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 docs to Tooltip component

---
 docs/src/__examples__/Tooltip/INDICATION.tsx  | 20 +++-
 .../04-overlay/tooltip/03-accessibility.mdx   | 96 +++++++++++++++++++
 2 files changed, 111 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..8fab52e940
--- /dev/null
+++ b/docs/src/documentation/03-components/04-overlay/tooltip/03-accessibility.mdx
@@ -0,0 +1,96 @@
+---
+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.                          |
+
+The 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, but is not visible on the screen.
+
+The `aria-labelledby` prop can reference multiple ids, separated by a space. The value of the attribute is not announced by the screen reader, but the content of the referred element(s) is.
+
+#### Examples
+
+1. The following code snippet shows how the simple setup of `aria-label`. The value of `aria-label` is prioritized over the content of children components. The content of children component (`Learn more.`) is not read by screen reader.
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet.</p>
+    </div>
+  }
+  aria-label="More information"
+>
+  <Text>Learn more.</Text>
+</Tooltip>
+```
+
+The screen reader will announce: `More information. Lorem ipsum dolor sit amet.`.
+
+2. In the following code snippet, the attribute `aria-labelled` is ignored as the value of this attribute is not in any component as a value of `id` attribute. The value of `aria-label` is read by a screen reader. Then the content inside the tooltip is read by the screen reader.
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet</p>
+    </div>
+  }
+  aria-label="More information"
+  aria-labelledby="tooltip-labelledby"
+>
+  <Icons.AlertCircle />
+</Tooltip>
+```
+
+The screen reader will announce: `More information. Lorem ipsum dolor sit amet.`.
+
+3. Prop `id` in `<Text>` component is filled in with the same value passed to `aria-labelledby`. The content of that component (`Learn more.`) is read by the screen reader. The value of `aria-labelled` is prioritized over the value of `aria-label`, that is not read at all.
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet</p>
+    </div>
+  }
+  aria-label="More information"
+  aria-labelledby="tooltip-labelledby"
+>
+  <Icons.AlertCircle />
+</Tooltip>
+<Text id="tooltip-labelledby">Learn more.</Text>
+```
+
+The screen reader will announce: `Learn more. Lorem ipsum dolor sit amet.`.
+
+4. There is not `aria-label`, nor `aria-labelledby` attribute. The content of children component is read by screen reader.
+
+```jsx
+<Tooltip
+  content={
+    <div>
+      <p>Lorem ipsum dolor sit amet</p>
+    </div>
+  }
+>
+  <Text>Learn more.</Text>
+</Tooltip>
+```
+
+The screen reader will announce: `Learn more. Lorem ipsum dolor sit amet.`.