Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Heading docs adjustments #4622

Merged
merged 2 commits into from
Feb 17, 2025
Merged

Heading docs adjustments #4622

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d85cef1
chore(Heading): fix the documentation
domihustinova Feb 13, 2025
3e8e95a
docs: adjust the accessibility tab docs for Heading component
domihustinova Feb 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 18 additions & 10 deletions docs/src/documentation/03-components/09-text/heading/03-accessibility.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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
Expand All @@ -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>
Expand Down
42 changes: 22 additions & 20 deletions packages/orbit-components/src/Heading/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<SkipNavigation>` 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

Expand All @@ -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. |
Loading