From c4e98a41d86dd1ab6222e56d744ca6cce3ccf318 Mon Sep 17 00:00:00 2001
From: Daniel Sil <daniel.sil@kiwi.com>
Date: Thu, 14 Nov 2024 12:38:56 +0100
Subject: [PATCH] docs: add accessibility docs to Heading component

---
 docs/src/__examples__/Heading/DEFAULT.tsx     |  8 ++-
 .../09-text/heading/03-accessibility.mdx      | 68 +++++++++++++++++++
 2 files changed, 74 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx

diff --git a/docs/src/__examples__/Heading/DEFAULT.tsx b/docs/src/__examples__/Heading/DEFAULT.tsx
index 7475340972..c9c4fb7e0e 100644
--- a/docs/src/__examples__/Heading/DEFAULT.tsx
+++ b/docs/src/__examples__/Heading/DEFAULT.tsx
@@ -2,7 +2,11 @@ import React from "react";
 import { Heading } from "@kiwicom/orbit-components";
 
 export default {
-  Example: () => <Heading>Orbit components</Heading>,
+  Example: () => (
+    <Heading role="heading" level={1}>
+      Orbit components
+    </Heading>
+  ),
   exampleKnobs: [
     {
       component: "Heading",
@@ -26,7 +30,7 @@ export default {
             "title5",
             "title6",
           ],
-          defaultValue: "div",
+          defaultValue: "title1",
         },
       ],
     },
diff --git a/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx b/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx
new file mode 100644
index 0000000000..3892c4851d
--- /dev/null
+++ b/docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx
@@ -0,0 +1,68 @@
+---
+title: Accessibility
+redirect_from:
+  - /components/heading/accessibility/
+---
+
+# Accessibility
+
+## Heading
+
+The Heading component has been designed with accessibility in mind.
+
+The component offers flexibility in terms of the HTML element used for the root node, the `role` attribute, and the `level` attribute.
+These properties allow for the creation of semantic and accessible headings.
+
+| Name  | Type                                                    | Description                                                                                                                 |
+| :---- | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |
+| as    | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "div"` | Defines the HTML element to be rendered.                                                                                    |
+| role  | `"heading"`                                             | Can only be used if `as="div"`. If defined, sets the role of the element to be "heading".                                   |
+| level | `number`                                                | Can only be used if `as="div"` and "`role="heading`". Defines the `aria-level` of the rendered `div` with the heading role. |
+
+All the props above are optional by default.
+
+If they are not provided, the component will render a `div` element with no role or aria-level defined.
+It is not semantically wrong but won't tell screen readers that the element is a heading. This should be used only for decorative purposes.
+
+```jsx
+<Heading>Hello World!</Heading>
+```
+
+renders:
+
+```html
+<div>Hello World!</div>
+```
+
+If the `as` prop is set to `"div"` (or undefined), the `role` prop is optional, but only accepts one possible value (if not `undefined`): `"heading"`.
+If the `role` prop is set to `"heading"`, the `level` prop must be defined as well. It will tell assistive technologies the level of the heading.
+The `level` prop must be a number between 1 and 6 and cannot be used if the `role` prop is not set to `"heading"`.
+
+```jsx
+<Heading as="div" role="heading" level={1}>
+  Hello World!
+</Heading>
+```
+
+renders:
+
+```html
+<div role="heading" aria-level="1">Hello World!</div>
+```
+
+If the `as` prop is set to `"h1"`, `"h2"`, `"h3"`, `"h4"`, `"h5"`, or `"h6"`, the component will render the corresponding HTML element.
+In that case, the `role` and `level` props are not needed, since assistive technologies will recognize the element as a heading and its correct level automatically.
+
+```jsx
+<Heading as="h1">Hello World!</Heading>
+```
+
+renders:
+
+```html
+<h1>Hello World!</h1>
+```
+
+### Compatibility with SkipNavigation
+
+The `dataA11ySection` prop can be used to link the Heading to a `SkipNavigation` component.