docs(Button): add accessibility section

docs/src/documentation/03-components/01-action/button/03-accessibility.mdx

@@ -0,0 +1,77 @@
+---
+title: Accessibility
+redirect_from:
+  - /components/button/accessibility/
+---
+
+# Accessibility
+
+## Button
+
+The Button component has been designed with accessibility in mind.
+
+The following props provide additional information to screen readers:
+
+| Name           | Type      | Description                                                            |
+| :------------- | :-------- | :--------------------------------------------------------------------- |
+| title          | `string`  | Allows you to specify an `aria-label` attribute of the component.      |
+| ariaLabelledby | `string`  | Allows you to specify an `aria-labelledby` attribute of the component. |
+| ariaControls   | `string`  | Allows you to specify an `aria-controls` attribute of the component.   |
+| ariaExpanded   | `boolean` | Allows you to specify an `aria-expanded` attribute of the component.   |
+| ariaCurrent    | `string`  | Allows you to specify an `aria-current` attribute of the component.    |
+
+While these props are optional, we recommend including them in a correct usage to ensure proper functionality with assistive technologies.
+
+- Use `title` when you need to add extra information to screen readers or there is no `children` presented to be used as label.
+
+- Prop `ariaLabelledby` references the id(s) of element(s) that label(s) the Button, separated by a space. The elements with those ids can be hidden, so that their text is only announced by screen readers to describe the button.
+
+- Use `ariaControls` prop to establish a connection between a Button and an element it controls. The prop accepts a unique `id` of an element.
+
+- The `ariaExpanded` prop is useful to indicate if a related control is expanded or collapsed. This attribute is commonly used in combination with `ariaControls`.
+
+- Use `ariaCurrent` prop to indicate that the Button represents the current item within a set of related Buttons. This prop helps assistive technologies convey the current state of the Button to users.
+
+- Use `disabled` prop to indicate users that button is inactive and they can't interact with it. When `disabled` prop is set to `true`, the button is ignored by a screen reader and not focusable by Tab key.
+
+Also, the component offers flexibility in terms of the HTML element used for the root node:
+
+- The prop `asComponent` can be used to define the HTML element to be rendered. This prop is optional and if it is not provided, the component will render a default (button) element.
+
+- When `href` prop is defined, the component will render as an `a` element.
+
+- Use `role` and `tabIndex` when you are rendering `Button` to non-actionable HTML element as `div` or `span`. However, this should be done only in edge-cases as it is anti-pattern behavior.
+
+## Example
+
+### Example 1:
+
+```jsx
+<Button title="Open modal window">Open</Button>
+```
+
+In this example, the screen reader will announce the title of the button (`Open modal window`). This is prioritized over text content (`Open`) inside the Button.
+
+### Example 2:
+
+```jsx
+<div>
+  <h2 id="section-title">Section Title</h2>
+  <Button
+    title="Expand section"
+    ariaLabelledby="section-title"
+    ariaControls="section-content"
+    ariaExpanded={true}
+    ariaCurrent="true"
+  >
+    Expand
+  </Button>
+  <div id="section-content">
+    <p>This is the content of the section.</p>
+  </div>
+</div>
+```
+
+In this example, the screen reader will announce the title of the section (`Section Title`) and that the section is expanded - section with respective id (`section-content`) is present.
+
+Note that the `title` prop is **not** announced by screen readers.