diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-datalist.js b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-datalist.js index defc472bd2..e8e6354dd2 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-datalist.js +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-datalist.js @@ -152,8 +152,10 @@ export class AccessibilityDatalist extends React.Component { isHidden={!this.state.expanded.includes('ex-toggle1')} >

- A mechanism should be available to bypass blocks of content that are repeated on multiple Web pages. - When keyboard-only users interact with your site, they use the tab key to jump from link to link. If you have a lot of links at the first of your page in your header or in a menu, they must tab through those every time they come to a new page just to get to the main content. Providing a skip to main content link allows them to easily bypass this. + A mechanism should be available to bypass blocks of content that are repeated on multiple web pages. +
+
+ When keyboard-only users interact with your site, they use the tab key to jump from link to link. If your UI has many links in your page header or in a menu, they must tab through those every time they come to a new page just to get to the main content. Providing a "skip to main content" link allows them to easily bypass this hassle.

@@ -171,7 +173,7 @@ export class AccessibilityDatalist extends React.Component { , -
Page Titles
+
Page titles
, WCAG 2.4.2 @@ -187,15 +189,18 @@ export class AccessibilityDatalist extends React.Component { id="ex-expand2" isHidden={!this.state.expanded.includes('ex-toggle2')} > -
- Descriptive titles help users find content, orient themselves within it, and navigate through it. Users can more quickly identify the content they need when accurate, descriptive titles appear in site maps or lists of search results. - The title of each web page should: - -
+

+ Use descriptive titles to help users find content, orient themselves within it, and navigate through it. +
+
+ Users can more quickly identify the content they need when accurate, descriptive titles appear in site maps or lists of search results. The title of each web page should: +
+ - Identify the subject of the web page. +
+ - Make sense when read out of context. For example, when read by a screen reader, in a site map, or in a list of search results. +
+ - Be concise. +

@@ -229,8 +234,9 @@ export class AccessibilityDatalist extends React.Component { >

If more than one link has the same label, it should also have the same URL. - Screen reader users can access the list of links that are on a page, which pulls the links out of context. - If you have links with different URLs but the same label, then add additional text to provide context to the screen reader user. +
+
+ Screen reader users can access the list of links that are on a page, which pulls the links out of context. If you have links with different URLs but the same label, then add additional text to provide context to screen reader users.

@@ -264,10 +270,14 @@ export class AccessibilityDatalist extends React.Component { isHidden={!this.state.expanded.includes('ex-toggle4')} >

- Use landmark roles to clearly identify regions that communicate page structure. If more than one landmark role occurs in the page, use aria-label to differentiate the landmark elements - Landmark roles programmatically identify sections of a page. Landmarks help assistive technology (AT) users orient themselves to a page and help them navigate easily to various sections of a page. - Whenever a landmark role is used more than once, provide a name using aria-label or aria-labelledby to provide context for that landmark. (ARIA6, ARIA16) - While toolbar is not a landmark role, the same rule applies to this role. + Use landmark roles to clearly identify regions that communicate page structure. +
+
+ Landmark roles programmatically identify sections of a page. If more than one landmark role occurs in the page, use aria-label to differentiate the landmark elements. + Landmarks help assistive-technology users orient themselves to a page and help them navigate easily to various page sections. Whenever a landmark role is used more than once, provide a name using aria-label or aria-labelledby to provide context for that landmark. ( ARIA6, ARIA16) +
+
+ Note: While toolbar is not a landmark role, the same rule applies.

@@ -301,8 +311,10 @@ export class AccessibilityDatalist extends React.Component { isHidden={!this.state.expanded.includes('ex-toggle5')} >

- Heading text should be descriptive. Correct heading levels should be used to communicate the outline and structure of the page. - A common practice is to use a single h1 for the primary headline or logo on a page, h2s to designate major sections, and h3's in supporting subsections + Heading text should be descriptive. +
+
+ Appropriate heading levels should be used to communicate the outline and structure of the page. For example, a common practice is to use a single h1 for the primary headline or logo on a page, h2s to designate major sections, and h3's for supporting subsections.

@@ -335,7 +347,10 @@ export class AccessibilityDatalist extends React.Component { isHidden={!this.state.expanded.includes('ex-toggle6')} >

- Content should be meaningful, clear, and concise. Use simple language and formatting, as appropriate for the context. + Content should be meaningful, clear, and concise. +
+
+ Use simple language and formatting, as appropriate for the context.

diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-development.md b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-development.md index 8618c9d143..6dc5ed85c9 100644 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-development.md +++ b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-development.md @@ -1,122 +1,156 @@ --- -id: Product development guide +id: Develop for accessibility section: accessibility --- import { AccessibilityDatalist } from './accessibility-datalist.js'; -## General questions to consider +PatternFly provides accessible components, but **we can't guarantee that your products will be accessible**. In order to ensure that your product is accessible, you will need to take additional steps during development, as described in the following guidelines and techniques. -To assess how accessible your applications or products are, consider these questions: -- **Is it discoverable/perceivable by all users?** If you can see or click on it, then it should be discoverable and perceivable by all users. You should determine if you can easily navigate to it by keyboard or by screen reader. -- **Is it interactable?** If you can get to it, it should be easy to actually use once you’ve focused on the element. You should be able to interact with it by keyboard (for example, if it’s a button, can you press **Enter** to initiate the action?). Also use a screen reader to ensure you can initiate the action. -- **Is it understandable?** If the element can be found and interacted with, it should be clear what this action does. If it’s a button, you should determine if it has visible text that would be clear out of context of the page. If it doesn’t have visible text, you should check if it has an aria-label or accessible name. +## Prioritizing accessibility during development +As you develop your product, you should keep accessibility top of mind, by asking yourself a few questions: -## What products should address +- **Can all users discover and perceive elements?**: If you can see or click on an element, then all users should be able to locate and navigate to it. This should include those that use a keyboard or other assistive technology, such as a screen reader. -Keep in mind that while PatternFly provides accessible components, we can't guarantee that your products will be accessible. There are a few items outside the scope of PatternFly, so you should keep these items in mind to ensure accessibility in anything you build: -
+- **Can all users interact with elements?**: It should be easy for users to use an element once it's in focus. They should be able to interact with elements and initiate actions via keyboard (like pressing Enter to initiate a button action) and screen readers. + +- **Can all users understand elements?**: It should be clear what actions elements can perform. For example, buttons should have visible text that would be clear out of context of the page. If not, it should have an `aria-label` or accessible name. +## Development techniques + +These are some of the items outside the scope of PatternFly that you should prioritize to ensure accessibility:
-## Techniques -The [WCAG 2.0 techniques](https://www.w3.org/TR/WCAG20-TECHS/Overview.html#contents) provide examples on how to meet accessibility guidelines. The techniques listed below are adopted as standard within PatternFly for handling specific patterns. +### UI element accessibility techniques +The [WCAG 2.0 techniques](https://www.w3.org/TR/WCAG20-TECHS/Overview.html#contents) provide examples on how to meet accessibility guidelines. The following techniques are standard across PatternFly for specific patterns. -### Labeling with Aria -For sighted users, the context and visual appearance of an element can provide sufficient cues to determine the purpose. But in some situations, this isn’t the case. For example, the X often used in the top-right corner of pop-up divs (light boxes) to indicate the control for closing the div might not be clear to those using assistive technology. +#### Labeling with ARIA -Popover example of close button +For sighted users, the context and visual appearance of an element can help users understand its purpose. But this isn’t always the case. For example, the X, often used in the top-right corner of pop-ups to indicate the control for closing, might not be clear to those using assistive technology: -Aria supplements HTML so that interactions and widgets commonly used in applications can be passed to assistive technologies when there is not otherwise a mechanism natively. - -Only use labels when necessary to make it accessible. If there is visible text, then there doesn’t need to be an aria-label. Aria is meant to add context (through labeling or description) for screen reader users when there isn’t visible text, not override or reiterate what’s already there. If there is visible text, aria might reiterate or override the visible text, so check that your aria is useful. +Popover example of close button -It’s important to understand that aria can only affect the semantics of an element; it has no effect on the behavior of the element. For example, while you can make an element hidden to screen readers with `aria-hidden=”true”`, that does not change the focus behavior for that element. +
+
+ARIA supplements HTML so that common application interactions and features can be passed to assistive technologies when there is not a native mechanism. This is typically done by including an `aria-label` that provides descriptive context to assistive technologies. **Only use labels when they are necessary to make an element accessible.** ARIA is meant to add context when there *isn’t* visible text, not to override or reiterate what’s already there. Make sure that your labels are useful and not redundant. -### Form fields +Note that ARIA can only affect the semantics of an element; it has no effect on its behavior. For example, while you can make an element hidden to screen readers with `aria-hidden=”true”`, that does not hide the element from focus. -Use [explicit linking](https://www.w3.org/TR/WCAG20-TECHS/H44.html) between `label` and form input elements (e.g. `input`, `textarea`, or `select`) when both elements are present. Aside from providing an accessible name to screen readers, this method also increases the clickable area of the form element by making the label clickable, too. ([H44](//www.w3.org/TR/WCAG20-TECHS/H44.html)) +#### Form fields -When a `label` element cannot accompany a form input element, provide the label using using `aria-label` or `aria-labelledby`. ([ARIA14](//www.w3.org/TR/WCAG20-TECHS/ARIA14.html)) In a single-field form, the submit button label can serve as the field label for sighted users ([G167](//www.w3.org/TR/WCAG20-TECHS/general.html#G167)) as well as assistive devices when using `aria-labelledby` +Use [explicit linking](https://www.w3.org/TR/WCAG20-TECHS/H44.html) between `label` and form input elements (such as `input`, `textarea`, or `select`) when both are present. [This "H44" guidelines](//www.w3.org/TR/WCAG20-TECHS/H44.html) provides an accessible name to screen readers and makes the label clickable to increase the overall clickable area of the form element. +When a `label` element cannot accompany a form input element, provide one using using `aria-label` or `aria-labelledby`, as outline by the ["ARIA14" guidelines](//www.w3.org/TR/WCAG20-TECHS/ARIA14.html). -### Icons +In a single-field form, the submit button label can serve as the field label for sighted users, [following the "G167" guidelines](//www.w3.org/TR/WCAG20-TECHS/general.html#G167). For assistive devices, use `aria-labelledby`. -Add `aria-hidden='true' for all icons, either to the icon element or a parent element of the icon. This renders the icon as something that assistive devices can ignore. +#### Icons -When accessibility is concerned, there are two main categories of icons: -- **Decorative icons** are icons that can be removed without affecting the page's information. -- **Semantic icons** are icons that provide information that isn't present on the page. For example, semantic icons can represent status, indicate an alert message type, or replace text as button labels. +To render icons as something that assistive devices can ignore, pass `aria-hidden='true'` to all icons, either to the icon element or a parent element of the icon. -The meaning of a semantic icon must be provided in alternative ways to the user. Additionally, follow these guidelines for semantic icons: +##### **Decorative and semantic icons** -- Add a label for the icon in tooltip text that displays on hover and on focus for focusable elements. +There are 2 main categories of accessible icons: +- **Decorative icons**, which can be removed without affecting the page's information. +- **Semantic icons**, which provide information that isn't present on the page. For example, these can represent status, indicate an alert message type, or replace text as button labels. The meaning of a semantic icon must be provided in alternative ways to the user. Additionally, you should follow these guidelines: + - Add a label for the icon in tooltip text that displays on hover and focus. + - For interactive elements (like `` and ` + ``` - ```html noLive - - ``` +##### **Non-interactive icons** -- For **non-interactive icons**, include .pf-screen-reader text near the icon. Depending on the component, the .pf-screen-reader text might not be a direct sibling to the icon element. +For **non-interactive icons**, include `.pf-v5-screen-reader` text near the icon. Depending on the component, this text might not be a direct sibling to the icon element. - Example: In the alert component, the icon label text is adjacent to the message. This way, when role="alert" is added to .pf-v5-c-alert__body for dynamically displayed alerts, the type of message is announced along with the message text. +For example, in the alert component, the icon label text is adjacent to the message: - ```html noLive + ``` + {
- -
-

- {{#> screen-reader}}Success:{{/screen-reader}} Success alert title -

-
+ +
+

+ {{#> screen-reader}}Success:{{/screen-reader}} Success alert title +

- ``` +
+ } + ``` -### Images -All images should have alt text so that assistive technology can provide an image description. This will help your site’s SEO, too. When an image contains words that are important to understanding the content, the alt text should include those words. This allows the alt text to play the same function on the page as the image. +#### Images + +All images should have alt text so that assistive technology can provide an image description. When an image contains words that are important to understanding the content, the alt text should include those words. This allows the alt text to communicate the same message as the image itself. **Note**: Alt text does not necessarily describe the visual characteristics of the image itself. It just needs to convey the same meaning as the image. -The exception to this practice is when images are primarily for presentation purposes and are not essential pieces of content. To signify that an image should be skipped by a screen reader, set the value of the alt attribute to an empty string, such as **alt=””**. +The exception to this practice is when images are primarily for presentation purposes and are not essential pieces of content. To signify that an image should be skipped by a screen reader, set the value of the alt attribute to an empty string: `alt=””`. + +#### Trapping focus + +The recommended interaction pattern for components like the modal or popover is to trap focus within the component's modal element when it becomes visible. + +For keyboard-only users who use the tab key to navigate the interface, trapped focus means that focus cannot be shifted outside of the modal when using the tab key. Instead, when focus leaves the last focusable item, it should move to the first focusable item of the modal. + +For screen reader users, the other contents on the page should be hidden from the screen reader. -### Trapping focus -The recommended interaction pattern for the modal components like the modal or popover is to trap focus within the modal element of the component when it becomes visible. +Based on the [screen reader / browser combinations](https://www.patternfly.org/accessibility/testing-your-accessibility) we use for testing, we recommend applying `aria-hidden="true"` to the parent wrapping element of the page contents. The modal element of the component must not be a descendent of this element, and should be included as a sibling to this element. -- For keyboard-only users that use the tab key to navigate the interface, this means that focus cannot be shifted outside of the modal when using the tab key. Instead, when focus leaves the last focusable item, it should be placed on the first focusable item of the modal. -- For screen reader users, the other contents on the page should be hidden from the screen reader. +#### Scrollable elements -Based on the [screen reader / browser combinations](https://www.patternfly.org/v4/accessibility/testing-your-accessibility) we use for testing, we recommend applying `aria-hidden="true"` to the parent wrapping element of the page contents. Note that the modal element of the component must not be a descendent of this element with `aria-hidden="true"` and should be included as a sibling to this element. +Any elements with horizontal or vertical scroll need to be accessible via keyboard. -### Scrollable elements -Any elements with horizontal or vertical scroll need to be accessible via keyboard. It may be necessary to ensure every -container with an overflow rule and content which could possibly grow larger than its parent's height to have -`tabindex=0`. This will ensure that parent can capture browser focus and be scrolled using the arrow keys. Some browsers -will automatically make any scrollable element focusable to ensure keyboard accessibility as long as they have a -non-negative tabindex. +Parent elements should be able to capture browser focus and be scrolled using the arrow keys. Some browsers will automatically make scrollable elements focusable to ensure keyboard accessibility, as long as they have a non-negative `tabindex`. It may be necessary to ensure that every container with overflow content which can grow larger than its parent's height to have `tabindex=0`. -Additionally, when adding `tabIndex` in this scenario, add `role='region'` and an `aria-label` that describes the scrollable element -or an `aria-labelledby` pointing to a heading with a descriptive, accessible name. -Some screen reader users navigate page elements via an element list or rotor menu and the default label for these scrollable elements -will be driven by whatever text content exists inside the container. This generated label may not be suitable to describe the regions purpose, and -would likely be better described with a simple `aria-label`. +When `tabIndex` is added, you should either add `role='region'` and an `aria-label` that describes the scrollable element, or an `aria-labelledby` to a descriptive and accessibly named heading. -Example: +Some screen reader users navigate page elements via an element list or rotor menu, and the default label for these scrollable elements will be driven by whatever text content exists inside the container. This generated label may not be suitable to describe the region's purpose, and would likely be better described with a simple `aria-label`. + +For example: ```html noLive

Content

-``` \ No newline at end of file +``` + +## Screen reader considerations + +Just as front-end developers use their browser to see how their changes look, you should use a screen reader to see how your accessibility looks. You can use a screen reader that is available in your operating system, like VoiceOver for Mac, or you could download an open-source screen reader like [NVDA](https://www.nvaccess.org/download/) if you have a PC. + +To test PatternFly, we target the following screen readers: + +- JAWS with Chrome, Windows ([JAWS keyboard shortcuts](//dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts)) +- Voiceover with Safari, Mac ([Voiceover keyboard shortcuts](//dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)) +- NVDA with Firefox, Windows ([NVDA keyboard shortcuts](//dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)) + +Generally, screen readers access the Document Object Model (DOM) and use browser Application Programming Interfaces (APIs) to get the information they need. In this way, a screen reader knows what to say when a set of list items begins and ends, and can typically announce how many items are in the list in advance. A screen reader can also traverse a page using heading navigation to speak the heading level. + +There are a few aspects that can affect how screen readers communicate information, which you should consider when building and testing your product: + +- **Semantic HTML**: Semantics refers to the meaning of a piece of code. A semantic element clearly describes its meaning to both the browser and the developer. For example, `
` and `` are non-semantic elements because they don't describe their contents. On the other hand, `
` and `` are semantic elements, because they clearly define their contents. Screen readers expect semantic HTML when traversing the DOM, so non-semantic elements (that aren't customized to be made accessible) are highly likely to be inaccessible. ARIA and other accessible attributes are meant to extend the functionality and meaning of native semantics, but at the core, your HTML should be semantic. + +- **Headings**: A user with vision can scan a page to quickly understand its information architecture. Visually impaired users have other methods of achieving this, such as using heading levels to determine the flow of information. Headings that vary in size for design purposes, rather than functionality, will likely confuse these users. A clear flow of sequential heading sizes based on headings and subheadings is significantly clearer to all users. + +- **Accessible names for all elements**: When an element doesn't have visual text, or when further explanation is necessary, a screen reader will not know what an item is or does. For example, if you have an icon `