docs: adjust the accessibility tab docs for Heading component

kiwicom · Feb 17, 2025 · bde53f4 · bde53f4
1 parent 8a214d1
commit bde53f4
Showing 1 changed file with 18 additions and 10 deletions.
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
@@ -13,16 +13,18 @@ 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. |
+| 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`                                                | Must 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.
+### Example 1
+
+If the `as` prop is not provided, the component will render a `div` element.
+In this case, no `role` or `level` are defined by default, and the component will render just a `div` element.
 
 ```jsx
 <Heading>Hello World!</Heading>
@@ -34,8 +36,12 @@ renders:
 <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.
+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.
+
+If the `as` prop is set to `"div"` (or undefined), it's possible to set the `role="heading` to indicate to assistive technologies that this element should be treated and formatted like a heading.
+This is the only accepted value for the `role` prop.
+
+In addition, 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
@@ -50,8 +56,10 @@ renders:
 <div role="heading" aria-level="1">Hello World!</div>
 ```
 
+### Example 2
+
 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.
+In that case, the `role` and `level` props **cannot** be used, since assistive technologies will recognize the element as a heading and its correct level automatically.
 
 ```jsx
 <Heading as="h1">Hello World!</Heading>