diff --git a/docs/src/documentation/03-components/01-action/button/03-accessibility.mdx b/docs/src/documentation/03-components/01-action/button/03-accessibility.mdx new file mode 100644 index 0000000000..842444e043 --- /dev/null +++ b/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 + +``` + +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 +
This is the content of the section.
+