diff --git a/packages/documentation-site/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/documentation-site/patternfly-docs/content/accessibility/accordion/accordion.md index 3d99ea10c6..ca5d36695b 100644 --- a/packages/documentation-site/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/documentation-site/patternfly-docs/content/accessibility/accordion/accordion.md @@ -98,7 +98,7 @@ The following HTML attributes and PatternFly classes can be used for more fine-t | `aria-expanded="[true or false]"` | `.pf-v5-c-accordion__toggle` | Indicates whether the accordion toggle is expanded (true) or collapsed (false) to assistive technologies. **Required**. | | `aria-label="[text that labels the accordion content]"` | `.pf-v5-c-accordion__expanded-content` | Adds an accessible name to the content of an accordion item. | | `hidden` | `.pf-v5-c-accordion__expanded-content` | Hides the accordion content. **Required** when `aria-expanded="false"` is passed in. | -| `aria-hidden="true"` | `.pf-v5-c-accordion__toggle-icon` | Removes the accordion toggle icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. **Required**. | +| `aria-hidden="true"` | `.pf-v5-c-accordion__toggle-icon > i` | Removes the accordion toggle icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. **Required**. | ## Additional considerations diff --git a/packages/documentation-site/patternfly-docs/content/accessibility/expandable-section/expandable-section.md b/packages/documentation-site/patternfly-docs/content/accessibility/expandable-section/expandable-section.md index 84d07f8392..5e83f1c905 100644 --- a/packages/documentation-site/patternfly-docs/content/accessibility/expandable-section/expandable-section.md +++ b/packages/documentation-site/patternfly-docs/content/accessibility/expandable-section/expandable-section.md @@ -3,20 +3,68 @@ id: Expandable section section: components --- -An **expandable section** is used to support progressive disclosure in a form or page by hiding additional content when you don't want it to be shown by default. -**Keyboard users** should be able to navigate to the expandable section toggle and use **Enter** or **Space** to show or hide the expandable content. -Tab order should also be preserved within the expandable content, so all interactable elements in the expandable content should follow -the expandable section toggle in the tab order. +import { Checkbox, List, ListItem } from '@patternfly/react-core'; -**Screen reader users** should be informed that the expandable section toggle is interactable, and whether the state of its -associated expandable content is expanded or collapsed using the `aria-expanded` attribute. The screen reader user should also be able to access the expanded expandable -content. When the expandable content is detached from the expandable section toggle, the expandable content's `id` should be set as the value of the -expandable section toggle's `aria-controls` attribute. +## Accessibility -The following props/attributes have been added for you and are customizable in PatternFly: +To implement an accessible PatternFly **expandable section**: + +- Ensure the expandable section's toggle text is updated based on its current expanded state. +- Provide unique toggle text for each expandable section if there are multiple on a page. + +## Testing + +At a minimum, an expandable section should meet the following criteria: + + + + + + + Tab navigates to the next toggle or focusable element, and Shift + Tab navigates to the previous toggle or focusable element.} /> + + + Expandable sections can be collapsed or expanded via keyboard by pressing Space or Enter on the toggle.} /> + + + This can be checked with a screen reader, or by checking that the aria-expanded attribute is accurate and updating in the DOM.} /> + + + + + + +## React customization + +The following React props have been provided for more fine-tuned control over accessibility. + +| Prop | Applied to | Reason | +|---|---|---| +| `contentId="[id of the expandable section content]"` | `ExpandableSection` and `ExpandableSectionToggle` | Adds an `id` to the `ExpandableSection`, and links it via the `aria-controls` attribute of the `ExpandableSectionToggle`. **Required** when the `isDetached` prop is passed in, and both components should have the same value passed in. | +| `toggleId="[id of the expandable section toggle]"` | `ExpandableSection` and `ExpandableSectionToggle` | Adds an id to the `ExpandableSectionToggle`, and adds an accessible name based on the toggle's content via the `aria-labelledby` attribute of the `ExpandableSection`. **Required** when the `isDetached` prop is passed, and both components should have the same value passed in. | +| `isExpanded` | `ExpandableSection` | Sets the `aria-expanded` attribute of the expandable section toggle, which notifies users of assistive technologies such as screen readers of the current state of the expandable section content. **Required** when the expandable section is not uncontrolled. | +| `toggleContent="[content for the toggle]"` or `toggleText="[text for the toggle]"` | `ExpandableSection` | The visible content of the expandable section toggle. The value passed into either prop should be based on the expandable section's current expanded state. | +| `toggleTextCollapsed="[text for a collapsed toggle]"` and `toggleTextExpanded="[text for an expanded toggle]"` | `ExpandableSection` | The visible content of the expandable section toggle when the expandable section is collapsed or expanded, respectively. These props can be passed in instead of `toggleContent` or `toggleText`. | +| `children` | `ExpandableSectionToggle` | The visible content of the expandable section toggle. The value passed in should be based on the expandable section's current expanded state. | +| `isExpanded` | `ExpandableSectionToggle` | Sets the `aria-expanded` attribute of the expandable section toggle, which notifies users of assistive technologies such as screen readers of the current state of the expandable section content. **Required** when the expandable section content is expanded, and should always have a boolean value. | + +## HTML/CSS customization + +The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility. + +| Attribute or class | Applied to | Reason | +|---|---|---| +| `aria-controls="[id of the expandable section content]"` | `.pf-v5-c-expandable-section__toggle` | Links the expandable section toggle and content for assistive technologies. **Required** when the expandable section content is rendered in the DOM. | +| `aria-expanded="[true or false]"` | `.pf-v5-c-expandable-section__toggle` | Indicates whether the expandable section is expanded (true) or collapsed (false) to assistive technologies. **Required**. | +| `hidden` | `.pf-v5-c-expandable-section__content` | Hides the expandable section content. **Required** when `aria-expanded="false"` is passed in, except for truncate expansion. | +| `aria-labelledby="[id of the expandable section toggle]"` | `.pf-v5-c-expandable-section__content` | Adds an accessible name to the expandable section content based on the toggle content. **Required**. | +| `role="region"` | `.pf-v5-c-expandable-section__content` | Adds the region role to the expandable section content. **Required**. | +| `aria-hidden="true"` | `.pf-v5-c-expandable-section__toggle-icon > i` | Removes the accordion toggle icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. **Required**. | + +## Further reading + +To read more about accessibility with expandable sections, refer to the following resources: + +- [ARIA Authoring Practices Guide - Disclosure (Show/Hide)](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) -| React component | React prop | Which HTML element it appears on in markup | Explanation | -|-------------------------|-----------------------|------------------------------------------------|-------------------------------------------------------------------------------| -| ExpandableSection | contentId | .pf-v5-c-expandable-section__content | Id of the expandable section, associates this content with its toggle button. | -| ExpandableSectionToggle | contentId | .pf-v5-c-expandable-section__toggle aria-controls | Associates this toggle button with the content that it reveals and hides. |