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 index 3892c4851d..e0a984cd64 100644 --- 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 Hello World! @@ -34,8 +36,12 @@ renders:
Hello World!
``` -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:
Hello World!
``` +### 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 Hello World! diff --git a/packages/orbit-components/src/Heading/README.md b/packages/orbit-components/src/Heading/README.md index 769feb92a5..0f24783e60 100644 --- a/packages/orbit-components/src/Heading/README.md +++ b/packages/orbit-components/src/Heading/README.md @@ -16,24 +16,24 @@ After adding import to your project you can use it simply like: The table below contains all types of props available in the Heading component. -| Name | Type | Default | Description | -| :-------------- | :------------------------- | :--------- | :--------------------------------------------------------------------------------------------------------- | -| as | [`enum`](#enum) | `"div"` | The element used for the root node. | -| role | `"heading"` | | The role attribute of the element. Can only be defined if `as="div"`. If defined, `level` must be defined. | -| level | `number` | | The level of the Heading. Required if `role` is defined as `"heading"`. | -| children | `React.Node` | | The content of the Heading. | -| dataTest | `string` | | Optional prop for testing purposes. | -| align | [`enum`](#enum) | `left` | `text-align` of `Heading` component. | -| dataA11ySection | `string` | | ID for a `` component. | -| id | `string` | | Adds `id` HTML attribute to an element. Expects a unique ID. | -| inverted | `boolean` | | The `true`, the Heading color will be white. | -| spaceAfter | `enum` | | Additional `margin-bottom` after component. | -| **type** | [`enum`](#enum) | `"title1"` | The size type of Heading. | -| mediumMobile | [`Object`](#media-queries) | | Object for setting up properties for the mediumMobile viewport. [See Media queries](#media-queries) | -| largeMobile | [`Object`](#media-queries) | | Object for setting up properties for the largeMobile viewport. [See Media queries](#media-queries) | -| tablet | [`Object`](#media-queries) | | Object for setting up properties for the tablet viewport. [See Media queries](#media-queries) | -| desktop | [`Object`](#media-queries) | | Object for setting up properties for the desktop viewport. [See Media queries](#media-queries) | -| largeDesktop | [`Object`](#media-queries) | | Object for setting up properties for the largeDesktop viewport. [See Media queries](#media-queries) | +| Name | Type | Default | Description | +| :-------------- | :------------------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------- | +| as | [`enum`](#enum) | `"div"` | Defines the HTML element to be rendered. See Accessibility tab. | +| role | `"heading"` | | The role attribute of the element. Can only be defined if `as="div"`. If defined, `level` must be defined. See Accessibility tab. | +| level | `number` | | The level of the Heading. Required if `role` is defined as `"heading"`. See Accessibility tab. | +| children | `React.Node` | | The content of the Heading. | +| dataTest | `string` | | Optional prop for testing purposes. | +| align | [`enum`](#enum) | `start` | `text-align` of the Heading component. | +| dataA11ySection | `string` | | ID for a SkipNavigation component. See Accessibility tab. | +| id | `string` | | Adds `id` HTML attribute to an element. Expects a unique ID. | +| inverted | `boolean` | | If `true`, the Heading color will be white. | +| spaceAfter | `enum` | | Additional `margin-bottom` after component. | +| type | [`enum`](#enum) | `"title0"` | The size type of the Heading. | +| mediumMobile | [`Object`](#media-queries) | | Object for setting up properties for the mediumMobile viewport. [See Media queries](#media-queries) | +| largeMobile | [`Object`](#media-queries) | | Object for setting up properties for the largeMobile viewport. [See Media queries](#media-queries) | +| tablet | [`Object`](#media-queries) | | Object for setting up properties for the tablet viewport. [See Media queries](#media-queries) | +| desktop | [`Object`](#media-queries) | | Object for setting up properties for the desktop viewport. [See Media queries](#media-queries) | +| largeDesktop | [`Object`](#media-queries) | | Object for setting up properties for the largeDesktop viewport. [See Media queries](#media-queries) | ### enum @@ -52,9 +52,11 @@ The table below contains all types of props available in the Heading component. ### Media Queries To make Heading responsive you can use props `mediumMobile`, `largeMobile`, `tablet`, `desktop` and `largeDesktop`, -which match the [mediaQueries](https://github.com/kiwicom/orbit/tree/master/packages/orbit-components/src/utils/mediaQuery) functions and contain the following properties: +which match +the [mediaQueries](https://github.com/kiwicom/orbit/tree/master/packages/orbit-components/src/utils/mediaQuery) +functions and contain the following properties: | Name | Type | Default | Description | | :--------- | :-------------- | :--------- | :------------------------------------------ | -| **type** | [`enum`](#enum) | `"title1"` | The size type of Heading. | +| type | [`enum`](#enum) | `"title0"` | The size type of Heading. | | spaceAfter | `enum` | | Additional `margin-bottom` after component. |