Skip to content

chore(HelperText): updated a11y docs to match template #3805

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

Merged
nicolethoen merged 2 commits into from
Dec 13, 2023
Merged

chore(HelperText): updated a11y docs to match template #3805

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
f27593d
chore(HelperText): updated a11y docs to match template
Nov 7, 2023
d0e2b76
Removed interactive content bullet from design guidelines
Dec 1, 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
128 changes: 81 additions & 47 deletions ...mentation-site/patternfly-docs/content/accessibility/helper-text/helper-text.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,50 +3,84 @@ id: Helper text
section: components
---

**Helper text** is text that often accompanies inputs and other form components. It can be static text that provides additional or clarifying information and will never change, or it can be dynamic text that gets rendered or updated based on user interaction or input.

**Keyboard users** should not be able to place focus on any helper text, as it is not an interactive element.

**Screen reader users** should have static helper text announced to them via the `aria-describedby` attribute when focus is placed on a form component, and they should also have dynamic helper text announced to them via the `aria-live` attribute when the text content gets updated.

## Accessibility application

To ensure helper text is used accessibly, follow these steps when applicable:

- When there is helper text that won't ever update based on user interaction or input, ensure that the helper text is linked to the form component's `aria-describedby` attribute. This can be accomplished by adding an `id` attribute to either the HelperText or HelperTextItem component.
- Link the HelperText component when all of the helper text should be announced to users. Otherwise link the HelperTextItem component(s) if only specific helper text should be announced.

```noLive
<TextInput aria-describedby="helper-text" />

<HelperText id="helper-text">
<HelperTextItem>
This will be announced.
</HelperTextItem>
<HelperTextItem>
This will also be announced.
</HelperTextItem>
</HelperText>
```
```noLive
<TextInput aria-describedby="helper-text-item" />

<HelperText>
<HelperTextItem id="helper-text-item">
Only this will be announced.
</HelperTextItem>
<HelperTextItem>
This will will not be announced since it is not linked.
</HelperTextItem>
</HelperText>
```
- Pass in the `isLiveRegion` prop to the HelperText component when you expect or intend for any helper text items to dynamically update in some way. This can include text that only renders in a specific situation, or when the text itself will change.
- Only content within the accessibility tree will be announced when updated. CSS updates and updates to text that is hidden via the `aria-hidden` attribute (such as any helper text icons) will not be announced.

The following props/attributes have been added for you or are customizable in PatternFly:

| React prop/attribute | React component that it should be applied to | Which HTML element it appears on in markup | Reason used |
| -- | -- | -- | -- |
| `aria-describedby` | TextInput or another form component | | Used to pass in one or more `id`'s as a string, allowing assistive technologies to announce the helper text content to users. |
| `id` | HelperText \| HelperTextItem | .pf-v5-c-helper-text \| .pf-v5-c-helper-text__item | Used to pass into a form component's `aria-describedby` prop. |
| `isLiveRegion` | HelperText | .pf-v5-c-helper-text | Creates an `aria-live="polite"` live region, which allows assistive technologies to announce content updates within it. |
import { Checkbox, List, ListItem } from '@patternfly/react-core';

## Accessibility

To implement an accessible PatternFly **helper text**:

- Give the helper text item an `id`, and pass that `id` to the main element's `aria-describedby` attribute. Alternatively if there are multiple helper text items, the helper text component can be given the `id` to be passed to the main element's `aria-describedby`. For example, the following code block includes two valid examples of passing `id` values to a main element:
```noLive
<TextInput aria-describedby="helper-text-1" />
<HelperText>
<HelperTextItem id="helper-text-1">
Some helper text content
</HelperTextItem>
</HelperText>

<TextInput aria-describedby="helper-text-2" />
<HelperText id="helper-text-2" component="ul">
<HelperTextItem component="li">
Some helper text content
</HelperTextItem>
<HelperTextItem component="li">
Some other helper text content
</HelperTextItem>
</HelperText>
```
- Structure the helper text as a `ul` element and each helper text item as a `li` element if there is more than one helper text item.
- Make the helper text component an `aria-live` region if the helper text item(s) have static text and styling, but will dynamically render.
- Ensure there is visually hidden text for assistive technologies such as screen readers that conveys the status type if the helper text item has static text and will always be rendered, but the styling will dynamically update.
- Avoid passing interactive content as helper text.
Copy link
Contributor Author

@thatblindgeye thatblindgeye Nov 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently helper text design guidelines mention that a link to additional info can be provided, so maybe some input from @andrew-ronaldson or @mmenestr would be helpful here. Is that still an intended use case for a helper text? Just wondering whether helper text should include content that has to be navigated to on another page, or if it should only include content that is immediately relevant for a user.

Copy link
Collaborator

@mmenestr mmenestr Nov 16, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm to be honest, I'd say not. I might edit the guidelines to delete that bullet because I don't think it makes sense. It only makes sense to add a link to external information in a popover!

Copy link
Contributor Author

@thatblindgeye thatblindgeye Nov 17, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can remove that bullet from the design guidelines as part of this PR if you'd like?

Copy link
Collaborator

@nicolethoen nicolethoen Nov 30, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@thatblindgeye go for it


## Testing

At a minimum, a helper text should meet the following criteria:

<List isPlain>
<ListItem>
<Checkbox id="helperText-a11y-checkbox-1" label={<span>Each helper text item has an <code className="ws-code">id</code> attribute, whose value is also passed to the main element's <code className="ws-code">aria-describedby</code> attribute.</span>} description="This allows a user navigating via assistive technologies such as a screen reader to have the helper text content announced to them without having to move focus from the main element." />
</ListItem>
<ListItem>
<Checkbox id="helperText-a11y-checkbox-2" label={<span>If there are multiple helper text items, the helper text component is structured as a <code className="ws-code">ul</code> element and the helper text items are structured as <code className="ws-code">li</code> elements.</span>} description="This lets users known how many helper text items there are within a single helper text component when navigating via assistive technologies such as a screen reader." />
</ListItem>
<ListItem>
<Checkbox id="helperText-a11y-checkbox-3" label="If the helper text item(s) are intended to have static text and styling, but be dynamically rendered, the helper text component is made into a live region." description={<span>The <code className="ws-code">aria-live</code> value should be "polite" when doing so. This will announce to users of assistive technologies when new helper text has rendered, keeping them informed of any remaining criteria or issues that need to be addressed.</span>} />
</ListItem>
<ListItem>
<Checkbox id="helperText-a11y-checkbox-4" label="If the helper text item(s) are intended to have static text and always be visible, but have dynamic styling, ensure there is visually hidden text within the helper text item that conveys its status type." description={<span>This is best achieved by using our <code className="ws-code">pf-v5-screen-reader</code> class.</span>} />
</ListItem>
<ListItem>
<Checkbox id="helperText-a11y-checkbox-5" label="There is no interactive content in any helper text items." />
</ListItem>
</List>

## React customization

The following React props have been provided for more fine-tuned control over accessibility.

| Prop | Applied to | Reason |
|---|---|---|
| `aria-label="[text that labels a helper text list]"` | `HelperText` | Adds an accessible name to the helper text component. Should only be passed when the `component` prop has a value of `"ul"`, especially when there are multiple helper text components on a page. Doing so will help differentiate the lists for users navigating via rotor menus. |
| `component="ul"` | `HelperText` | Sets the wrapper element of the helper text component to an unordered list. **Required** when the helper text component is intended or expected to include multiple helper text items. |
| `id` | `HelperText` | Sets the `id` attribute of the helper text component, which can be passed to the main element's `aria-describedby` attribute when there are multiple helper text items that should all be announced. |
| `isLiveRegion` | `HelperText` | Makes the helper text component a live region with a value of `"polite"`. **Required** when helper text item(s) are intended or expected to have static text, but dynamically render. |
| `component="li"` | `HelperTextItem` | Sets the wrapper element of the helper text item to a list item. **Required** when `HelperText` has `component="ul"` passed in. |
| `id` | `HelperTextItem` | Sets the `id` attribute of the helper text item, which should be passed to the main element's `aria-describedby` attribute. |
| `screenReaderText="[text that conveys status type]"` | `HelperTextItem` | Renders visually hidden text when the `isDynamic` prop is also passed in. Typically this should convey the status type of the helper text item, and will render immediately after the item text. |
| `variant="[default, indeterminate, warning, error, or success]"` | `HelperTextItem` | Sets the text styling and icon. This prop should only be passed in when the helper text item should visually convey some sort of status. |

## 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-label="[text that labels a helper text list]"` | `ul.pf-v5-c-helper-text` | Adds an accessible name to the helper text component. Should be passed when there are multiple helper text components on a page. Doing so will help differentiate the lists for users navigating via rotor menus. |
| `aria-live="polite"` | `.pf-v5-c-helper-text` | Makes the helper text component a live region. **Required** when helper text item(s) are intended or expected to have static text, but dynamically render. |
| `id` | `.pf-v5-c-helper-text` | Sets the `id` attribute of the helper text component, which can be passed to the main element's `aria-describedby` attribute when there are multiple helper text items that should all be announced. |
| `role="list"` | `ul.pf-v5-c-helper-text` | Indicates that the helper text component is a list element. **Required**.<br/><br/>This role is redundant since `.pf-v5-c-helper-text` can be a `<ul>` element, but it is required for assistive technologies to announce the list properly. |
| `id` | `.pf-v5-c-helper-text__item` | Sets the `id` attribute of the helper text item, which should be passed to the main element's `aria-describedby` attribute if the `.pf-v5-c-helper-text` element is not given an `id` instead. |
| `aria-hidden="true"` | `.pf-v5-c-helper-text__item-icon > i` | Removes the helper text item icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. **Required**. |
| `.pf-v5-screen-reader` | `.pf-v5-c-helper-text__item.pf-m-dynamic > span` | Renders visually hidden text that is accessible only to assistive technologies such as a screen reader. **Required** if the helper text item is intended or expected to contain static text and always be visible, but have dynamic styling. Typically this should convey the status type of the helper text item. |

1 change: 0 additions & 1 deletion ...patternfly-docs/content/design-guidelines/components/helper-text/helper-text.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ For information regarding other forms of on-screen help, see [popovers](https://
* Should appear on 1 line (if possible) and be visible to the user
* Should consist of clear, simple language
* Can be written in complete sentences or as a statement
* Include hyperlinks to additional information if necessary
* Use helper text for information critical to a user completing a task, such as password requirements, character requirements, invalid text alerts, etc.

## Accessibility
Expand Down