From e1904b2174d085e5ce274c40706f225d73efe6fe Mon Sep 17 00:00:00 2001 From: Tyler Jones Date: Thu, 25 May 2023 14:27:08 -0400 Subject: [PATCH] Update `PageLayout` docs around `
` usage (#3323) * Update `PageLayout` docs around `
` usage * Update generated/components.json * Fix links --------- Co-authored-by: TylerJDev --- docs/content/PageLayout.mdx | 50 ++++++++++++++++++++++------- generated/components.json | 12 ------- src/PageLayout/PageLayout.docs.json | 12 ------- 3 files changed, 39 insertions(+), 35 deletions(-) diff --git a/docs/content/PageLayout.mdx b/docs/content/PageLayout.mdx index 7b4458b38f..db4f810b99 100644 --- a/docs/content/PageLayout.mdx +++ b/docs/content/PageLayout.mdx @@ -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 - + @@ -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 - - + + @@ -300,15 +300,35 @@ Using `aria-labelledby` along with `PageLayout.Header`, `PageLayout.Content`, or ``` +### With `
` landmark + +```jsx live + + + + + +
+ +
+ + + + + + + + +``` + ## 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. @@ -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 `
` landmark role. +If you want to utilize a `
` landmark with this component, you may supply one directly [as a child of `PageLayout.Content`](#with-main-landmark). +When using `
` ensure that no other `
` 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 diff --git a/generated/components.json b/generated/components.json index 038c99aca5..6c43f4396c 100644 --- a/generated/components.json +++ b/generated/components.json @@ -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'", diff --git a/src/PageLayout/PageLayout.docs.json b/src/PageLayout/PageLayout.docs.json index dfa273638c..ce713bf46c 100644 --- a/src/PageLayout/PageLayout.docs.json +++ b/src/PageLayout/PageLayout.docs.json @@ -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'",