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

Update PageLayout docs around <main> usage #3323

Merged
merged 4 commits into from
May 25, 2023
Merged

Update PageLayout docs around <main> usage #3323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6a5ac56
Update `PageLayout` docs around `<main>` usage
TylerJDev May 24, 2023
dd20a82
Update generated/components.json
TylerJDev May 24, 2023
e9fd8c4
Fix links
TylerJDev May 25, 2023
987524c
Merge branch 'tylerjdev/update-pagelayout-docs-main' of https://githu…
TylerJDev May 25, 2023
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
50 changes: 39 additions & 11 deletions docs/content/PageLayout.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -241,14 +241,14 @@ navigation container is used for.

### With `aria-label`

Using `aria-label` along with `PageLayout.Header`, `PageLayout.Content`, or `PageLayout.Footer` creates a unique label for that landmark role that can make it easier to navigate between sections of content on a page.
Using `aria-label` along with `PageLayout.Header` or `PageLayout.Footer` creates a unique label for that landmark role that can make it easier to navigate between sections of content on a page.

```jsx live
<PageLayout>
<PageLayout.Header aria-label="header">
<Placeholder label="Header" height={64} />
</PageLayout.Header>
<PageLayout.Content aria-label="content">
<PageLayout.Content>
<Placeholder label="Content" height={240} />
</PageLayout.Content>
<PageLayout.Pane>
Expand All @@ -262,15 +262,15 @@ Using `aria-label` along with `PageLayout.Header`, `PageLayout.Content`, or `Pag

### With `aria-labelledby`

Using `aria-labelledby` along with `PageLayout.Header`, `PageLayout.Content`, or `PageLayout.Footer` creates a unique label for each landmark role by using the given `id` to associate the landmark with the content with the corresponding `id`. This is helpful when you have a visible item that visually communicates the type of content which you would like to associate to the landmark itself.
Using `aria-labelledby` along with `PageLayout.Header` or `PageLayout.Footer` creates a unique label for each landmark role by using the given `id` to associate the landmark with the content with the corresponding `id`. This is helpful when you have a visible item that visually communicates the type of content which you would like to associate to the landmark itself.

```jsx live
<PageLayout>
<PageLayout.Header aria-labelledby="header-label">
<Placeholder id="header-label" label="Header" height={64} />
</PageLayout.Header>
<PageLayout.Content aria-labelledby="main-label">
<Placeholder id="main-label" label="Content" height={240} />
<PageLayout.Content>
<Placeholder label="Content" height={240} />
</PageLayout.Content>
<PageLayout.Pane>
<Placeholder label="Pane" height={120} />
Expand Down Expand Up @@ -300,15 +300,35 @@ Using `aria-labelledby` along with `PageLayout.Header`, `PageLayout.Content`, or
</PageLayout>
```

### With `<main>` landmark

```jsx live
<PageLayout>
<PageLayout.Header>
<Placeholder label="Header" height={64} />
</PageLayout.Header>
<PageLayout.Content>
<main>
<Placeholder label="Content" height={240} />
</main>
</PageLayout.Content>
<PageLayout.Pane resizable>
<Placeholder label="Pane" height={120} />
</PageLayout.Pane>
<PageLayout.Footer>
<Placeholder label="Footer" height={64} />
</PageLayout.Footer>
</PageLayout>
```

## Accessibility

The `PageLayout` component uses [landmark roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) for `PageLayout.Header`, `PageLayout.Content`, and `PageLayout.Footer` in order to make it easier for screen reader users to navigate between sections of the page.
The `PageLayout` component uses [landmark roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) for `PageLayout.Header` and `PageLayout.Footer` in order to make it easier for screen reader users to navigate between sections of the page.

| Component | Landmark role |
| :------------------- | :------------------------------------------------------------------------------------------------------ |
| `PageLayout.Header` | [`banner`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) |
| `PageLayout.Content` | [`main`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/main_role) |
| `PageLayout.Footer` | [`contentinfo`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) |
| Component | Landmark role |
| :------------------ | :------------------------------------------------------------------------------------------------------ |
| `PageLayout.Header` | [`banner`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/banner_role) |
| `PageLayout.Footer` | [`contentinfo`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/contentinfo_role) |

Each component may be labeled through either `aria-label` or `aria-labelledby` in order to provide a unique label for the landmark. This can be helpful when there are multiple landmarks of the same type on the page.

Expand All @@ -318,6 +338,14 @@ Each component may be labeled through either `aria-label` or `aria-labelledby` i
- [WCAG, ARIA11 Technique](https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA11)
- [MDN, Landmark roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role)

### `PageLayout.Content`

The `PageLayout.Content` component does not provide a default `<main>` landmark role.
If you want to utilize a `<main>` landmark with this component, you may supply one directly [as a child of `PageLayout.Content`](#with-main-landmark).
When using `<main>` ensure that no other `<main>` landmark exists on the page, as there should only be one per page.

- [`main` usage](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/main.html)

### `PageLayout.Pane`

The `PageLayout.Pane` component does not provide a default landmark role as the
Expand Down
12 changes: 0 additions & 12 deletions generated/components.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2730,18 +2730,6 @@
{
"name": "PageLayout.Content",
"props": [
{
"name": "aria-label",
"type": "string | undefined",
"defaultValue": "",
"description": "A unique label for the rendered main landmark"
},
{
"name": "aria-labelledby",
"type": "string | undefined",
"defaultValue": "",
"description": "An id to an element which uniquely labels the rendered main landmark"
},
{
"name": "width",
"type": "| 'full' | 'medium' | 'large' | 'xlarge'",
Expand Down
12 changes: 0 additions & 12 deletions src/PageLayout/PageLayout.docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,18 +84,6 @@
{
"name": "PageLayout.Content",
"props": [
{
"name": "aria-label",
"type": "string | undefined",
"defaultValue": "",
"description": "A unique label for the rendered main landmark"
},
{
"name": "aria-labelledby",
"type": "string | undefined",
"defaultValue": "",
"description": "An id to an element which uniquely labels the rendered main landmark"
},
{
"name": "width",
"type": "| 'full' | 'medium' | 'large' | 'xlarge'",
Expand Down