From 0af50370b5a093151b12b08e2490d7b1b9cc8c3f Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Wed, 1 Jun 2022 16:11:51 -0400 Subject: [PATCH 01/11] docs(a11y): create template for a11y docs --- .../content/accessibility/a11y-template.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 packages/v4/patternfly-docs/content/accessibility/a11y-template.md diff --git a/packages/v4/patternfly-docs/content/accessibility/a11y-template.md b/packages/v4/patternfly-docs/content/accessibility/a11y-template.md new file mode 100644 index 0000000000..b202cb23d0 --- /dev/null +++ b/packages/v4/patternfly-docs/content/accessibility/a11y-template.md @@ -0,0 +1,78 @@ +The following is a general template for how accessibility docs should be written for components. Following the code block below are further explanations of each section, including replacement verbiage under certain circumstances. + +``` +--- +id: { Component name (sentence case) } +section: components +--- + +## Accessibile application + +The following guidelines outline some of the ways that a PatternFly { component name } should generally be operable, understandable, and perceivable in order to improve accessibility for users. + +{ Explanation(s) for how the component should generally be operable, understandable, and perceivable by various types of users. } + +## React library considerations + +PatternFly's React library has taken into account various considerations for the standard use of {"a"/"an"} { component name } by ensuring certain accessibility functionality is built-in by default. + +{ Explanation(s) of considerations that can be summed up in a sentence or two, and do not need any accompanying code snippets or images. } + +Additionally, some further considerations provided by PatternFly are outlined below. + +### { Consideration heading } + +{ An explanation for a consideration that needs more detail, including what it does or is for and any necessary code snippets or images. } + +### Customizable props + +The table below outlines the various React props that can be passed in or customized by the consumer, and which can affect accessibility. Each prop includes what component it should be applied to, the reason for using it or what it does, and whether it is ever required. + +| Prop | Applied to | Reason | +|---|---|---| +| propName | ComponentName | Reason for using propName | + +## HTML/CSS library considerations + +When using PatternFly's HTML/CSS library consumers must take several considerations into account by following the table below, which outlines the various HTML attributes that can affect accessibility. Each attribute includes what element it should be applied to, the reason for using it or what it does, and whether it is ever required. + +| Attribute | Applied to | Reason | +|---|---|---| +| attribute-name | selector | Reason for using attribute-name | + +## Additional considerations + +Consumers must ensure they take any additional considerations when customizing {"a"/"an"} {component name}, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. + +### { Consideration heading } + +{ An explanation of the consideration and what a consumer must ensure. } + +## Further reading + +To read more about accessibility with {component name}'s, refer to the resources listed below. + +- { A link to a resource } +``` + +**Accessible application**:** This section should serve as a higher-level overview for how various types of users should be able to operate, perceive, or understand the component, or what the component should do/how it should function within the context of a page. Use separate paragraphs for different areas of the component functionality/behavior. When referring to specific types of users, use user-first verbiage, e.g. "Users interacting via keyboard..." or "Users with a color deficiency..." + +This section should only state what should occur rather than *how* it occurs via mentions of React props or HTML attributes, e.g. "Users interacting via keyboard should be able to press **Tab** to place focus on the component", rather than "The component has `tabindex="0"` to allow focus to be placed on it via keyboard." + +Consumers should be able to read this section and have an understanding for whether their application of the component meets the points outlined, regardless of whether they are using the component as-is or customizing it in some way. + +**React library considerations**: This section refers only to the React library. It should include what considerations PatternFly has taken and built into the component by default and why, often so that consumers are not required to manually pass anything in themselves (even if there is the option to do so). This can include expanding upon the previous section by explaining *how* some functionality occurs, e.g. "The component has `tabindex="0"` to allow focus to be placed on it via keyboard." + +Considerations that do not need a detailed explanation or accompanying code snippets/images should not receive their own sub-section, while more lengthy/significant explanations or considerations that include code snippets/images should be given their own sub-section. + +Consumers should be able to read this section and understand what accessibility functionality is built into the component and for what purpose, so that they have a better understanding of the component's accessibility should they customize it in some way. + +If PatternFly has not built any accessibility functionality in by default, the verbiage of the section should be replaced with, "By default, {"a" / "an"} {component name} does not have any accessibility functionality built into it by PatternFly. Any considerations must be taken by the consumer, some of which are outlined in the sub-section below." + +**Customizable props**: This sub-section serves to inform consumers of some of the considerations they should take when using the component from the React library. It should only include a table of the various React props that can be passed in and/or customized, and which can affect accessibility. Consumers should be able to read this section and understand how a specific prop should be used and how it will affect accessibility when they pass it in or customize it. + +**HTML/CSS library considerations**: This section refers only to the HTML/CSS library. It should only include a table of the various attributes that a consumer can pass in and which can affect accessibility. Consumers should be able to read this section and understand how a specific attribute should be used and how it will affect accessibility when they pass it in. + +**Additional considerations**: This section should include any additional considerations a consumer should take. It should only include more general considerations that don't pertain specifically to either the React or HTML/CSS library. If there are no additional considerations, this section can be omitted. + +**Further reading**: This section should include any significant resources in regards to the component's accessibility. It can usually include links to a specific section of the WCAG, the WAI-ARIA authoring practices, or other resources that PatternFly may have used in coming to decisions on accessibiltiy functionality. If there are no resources to include, this section can be omitted. \ No newline at end of file From d996cf29d9f38a80dec57fbae26a36ff533b49a4 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Tue, 7 Jun 2022 13:55:38 -0400 Subject: [PATCH 02/11] Refactor template as webpage on PF site --- .../writing-accessibility-documentation.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md diff --git a/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md b/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md new file mode 100644 index 0000000000..ade82461c9 --- /dev/null +++ b/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md @@ -0,0 +1,126 @@ +--- +id: Writing accessibility documentation for PatternFly +section: accessibility +--- + +Accessibility documentation is meant to help consumers improve accessibility for their users. This page focuses on how to write consistent and robust accessibility documentation. + +## Content architecture + +Your accessibility documentation should generally follow the [design guidelines content architecture](/ux-writing/writing-design-guidelines-for-patternfly#content-architecture). + +### Keyboard inputs + +When referencing specific inputs on a keyboard, wrap each input in a `kbd` element and capitalize the first letter of the input. When referencing a combination of inputs, place each input in its own `kbd` element with a "+" between them. + +For example: + +"When a user presses Tab + Shift..." + +### Person first language + +When referring to specific types of users in your documentation, use person first language. This places emphasis on the person before the assistive technology, disability, or limitation. + +For example: + +"Users interacting via keyboard..." or "Users with a color deficiency..." + +## General structure + +Your documentation should follow a defined structure of headings and sections, which are outlined in the following sub-sections. Each section includes default verbiage, usually prefacing the content that you will add in yourself. Depending on your content, you might find it necessary to omit or alter various sections. + +### Accessible application + +This section should serve as a list of higher-level guidelines for how various types of users should be able to operate, perceive, or understand the component, or what the component should do/how it should function within the context of a page. + +Consumers should be able to read this section and have a general understanding for whether their application of the component satisfies the points outlined, regardless of whether they are using the component as-is or customizing it in some way. + +Avoid detailing how the component achieves a specific accessibility functionality, and instead only state what the expected functionality is. + +| Do | Don't | +|:--|:--| +| "Users interacting via keyboard should be able to..." | "The component has `tabIndex="0"` so that users interacting via keyboard can..." | + +Example: + +>The following guidelines outline some of the ways that a PatternFly **accordion** should generally be operable, understandable, and perceivable in order to improve accessibility for users. +> +>- Bullet item describing a guideline... + +### React library considerations + +This section should only refer to the React library. It should include what considerations PatternFly has taken and built into the component by default and why, often so that consumers are not required to manually pass anything in themselves (even if there is the option to do so). This can include expanding upon the previous section by explaining *how* some functionality occurs. For example, "The component has `tabIndex="0"` so that users interacting via keyboard can...". + +Consumers should be able to read this section and understand what accessibility functionality is built into the component and for what purpose. This should provide them a better understanding of what functionality affects the component's accessibility should it be customized in some way. + +Considerations that do not need a detailed explanation, or accompanying code blocks or images, should not receive their own sub-section. If a consideration has a more lengthy explanation, is considered more significant, or has accompanying code blocks or images, it should be given its own sub-section. + +Example: + +>PatternFly's React library has taken into account various considerations for the standard use of an accordion by ensuring certain accessibility functionality is built-in by default. +> +>A simple explanation that doesn't require accompanying code blocks or images... +> +>Additionally, some further considerations provided by PatternFly are outlined below. +> +>### Consideration heading +> +>A more complex or significant explanation, with or without accompanying code blocks or images. + +If PatternFly has not built any accessibility functionality in by default, the content of the section should be replaced to notify consumers of this. Example: + +>By default, PatternFly has not built in any accessibility functionality into the accordion. Any considerations must be taken by the consumer, some of which are outlined in the sub-section below. + +### Customizable props + +This sub-section should only include a table of the various React props that can be passed in and/or customized, and which can affect accessibility. + +Consumers should be able to read this section and understand how a specific prop should be used and how it will affect accessibility when they pass it in or customize it. + +Example: + +>The table below outlines the various React props that can be passed in or customized by the consumer, and which can affect accessibility. Each prop includes what component it should be applied to, the reason for using it or what it does, and whether it is ever required. +> +>| Prop | Applied to | Reason | +>|---|---|---| +>| propName | ComponentName | Reason for using propName | + +### HTML/CSS library considerations + +This section should only refer only to the HTML/CSS library. It should only include a table of the various attributes that a consumer can pass in and which can affect accessibility. + +Consumers should be able to read this section and understand how a specific attribute should be used and how it will affect accessibility when they pass it in. + +Example: + +>When using PatternFly's HTML/CSS library consumers must take several considerations into account by following the table below, which outlines the various HTML attributes that can affect accessibility. Each attribute includes what element it should be applied to, the reason for using it or what it does, and whether it is ever required. +> +>| Attribute | Applied to | Reason | +>|---|---|---| +>| attribute-name | selector | Reason for using attribute-name | + +### Additional considerations + +This section should include any additional considerations a consumer should take when using the component. It should only include more general considerations that don't pertain only to the React or HTML/CSS library, and have not been mentioned elsewhere in the documentation. + +If there are no additional considerations, this section can be omitted. + +Example: + +>Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. +> +>### Consideration heading +> +>An explanation of an additional consideration... + +### Further reading + +This section should include any significant resources in regards to the component's accessibility. It can usually include links to a specific section of the [WCAG](https://www.w3.org/TR/WCAG21/) or the [ARIA authoring practices guide](https://www.w3.org/WAI/ARIA/apg/), or other resources that PatternFly may have used in coming to decisions on accessibiltiy functionality. + +If there are no resources to include, this section can be omitted. + +Example: + +>To read more about accessibility with accordions, refer to the resources listed below. +> +>- A resource link \ No newline at end of file From afe8c365a4480b6fc52d309e8fcad8ad3b994419 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Fri, 17 Jun 2022 13:36:06 -0400 Subject: [PATCH 03/11] Convert accordion doc to align with template --- .../accessibility/accordion/accordion.md | 56 +++++++++++++++---- 1 file changed, 46 insertions(+), 10 deletions(-) diff --git a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md index b90aeb4185..75c44ee905 100644 --- a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md @@ -3,18 +3,54 @@ id: Accordion section: components --- +## Accessibile application -An **accordion** is an interactive container that expands and collapses to hide or reveal the nested content. It takes advantage of progressive disclosure to help reduce page scrolling by allowing users to choose to show or hide more detailed information as needed. +The following guidelines outline some of the ways that a PatternFly **accordion** should generally be operable, understandable, and perceivable in order to improve accessibility for users. -**To make accordion accessible:** -- Make sure to include the `isExpanded` prop on the AccordionToggle based on the toggle’s state. This prop adds necessary accessibility attributes and styling such as `aria-expanded=”true/false”` +- Each accordion toggle should be a button that includes unique and descriptive labels so that users can more quickly scan through the accordion contents without having to expand individual panels. An accordion toggle should also include an icon to visually notify users if an accordion item is in an expanded or collapsed state. +- Users interacting via keyboard should be able to use standard keyboard navigation to navigate between accordion toggles or other focusable elements: Tab to navigate to the next accordion toggle or focusable element, and Shift + Tab to navigate to the previous accordion toggle or focusable element. +- An accordion toggle should be able to be collapsed or expanded by pressing either Space or Enter. +- Users interacting via screen reader or similar assistive technologies with an announced output should be notified whether the accordion toggle is in an expanded or collapsed state when focus is first placed on it, and they should be informed when the state of the currently focused accordion toggle changes. +- When using headings for an accordion, never skip heading levels within the context of the rest of the page. -
+## React library considerations -In general, the application launcher component already has accessibility built in. However, if you would like to customize it, you can edit the following: +PatternFly's React library has taken into account various considerations for the standard use of an accordion by ensuring certain accessibility functionality is built-in by default. -| React component| Prop or attribute | Which HTML element it appears on in markup | Explanation | -|---|---|---|---| -| Accordion | aria-label | .pf-c-accordion | Adds accessible text to the Accordion - available for customization | -| AccordionContent | aria-label | .pf-c-accordion__expanded-content | Adds accessible text to the Accordion content - available for customization. | -|AccordionToggle| isExpanded | .pf-c-accordion__toggle | Flag to show if the expanded content of the Accordion item is visible. This prop adds necessary accessibility attributes and styling such as `aria-expanded=”true/false”`. | \ No newline at end of file +- The accordion toggle is a `button`, allowing for standard keyboard, mouse, or touch interaction and allowing it to be tabbed to. +- The icon for an accordion toggle has `aria-hidden="true"` to remove it from the accessibility tree since it is decorative content. This prevents assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. + +### Customizable props + +The table below outlines the various React props that can be passed in or customized by the consumer, and which can affect accessibility. Each prop includes what component it should be applied to, the reason for using it or what it does, and whether it is ever required. + +| Prop | Applied to | Reason | +|---|---|---| +| aria-label | Accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with a descriptive label. | +| headingLevel | Accordion | When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a section that has an `h2` heading, you should not pass `headingLevel="h4"`. | +| aria-label | AccordionContent | Adds an accessible name to the content of an accordion item. | +| isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded="true/false"`, which notifies screen readers whether the accordion toggle is expanded or collapsed. Should be used in conjunction with `isHidden` on the accordion content. | +| isHidden | AccordionContent | Determines whether the content of the accordion item is visible or not. The value of this prop should always be the opposite of `isExpanded` on the accordion toggle. | + +## HTML/CSS library considerations + +When using PatternFly's HTML/CSS library consumers must take several considerations into account by following the table below, which outlines the various HTML attributes that can affect accessibility. Each attribute includes what element it should be applied to, the reason for using it or what it does, and whether it is ever required. + +| Attribute | Applied to | Reason | +|---|---|---| +| aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the expanded content element is collapsed to assistive technologies. **Required** | +| aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the expanded content element is expanded to assistive technologies. **Required** | +| hidden | .pf-c-accordion__expanded-content | Visually hides the expanded content element. **Required** when `aria-expanded="false"` is passed in. +| aria-hidden="true" | .pf-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** | + +## Additional considerations + +Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. + +- Avoid adding complex interaction to the accordion. This can often cause loops or traps that prevent users from efficiently navigating the content when using a keyboard. + +## Further reading + +To read more about accessibility with accordions, refer to the resources listed below. + +- [ARIA Authoring Practices Guide - Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) \ No newline at end of file From 8785499a58d5be18e6918bb2fb3ef25d0c6fb4c9 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Fri, 17 Jun 2022 14:06:46 -0400 Subject: [PATCH 04/11] Update guidelines and accordion doc --- .../accessibility/accordion/accordion.md | 12 ++++++----- .../writing-accessibility-documentation.md | 21 ++++++++++++------- 2 files changed, 21 insertions(+), 12 deletions(-) diff --git a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md index 75c44ee905..e260ecae4b 100644 --- a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md @@ -29,8 +29,10 @@ The table below outlines the various React props that can be passed in or custom | aria-label | Accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with a descriptive label. | | headingLevel | Accordion | When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a section that has an `h2` heading, you should not pass `headingLevel="h4"`. | | aria-label | AccordionContent | Adds an accessible name to the content of an accordion item. | -| isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded="true/false"`, which notifies screen readers whether the accordion toggle is expanded or collapsed. Should be used in conjunction with `isHidden` on the accordion content. | -| isHidden | AccordionContent | Determines whether the content of the accordion item is visible or not. The value of this prop should always be the opposite of `isExpanded` on the accordion toggle. | +| isHidden | AccordionContent | Determines whether the content of the accordion item is hidden or not. Should be used along with the `isExpanded` prop on the accordion toggle. | +| isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded="true/false"`, which notifies screen readers whether the accordion toggle is expanded or collapsed. Should be used along with the `isHidden` prop on the accordion content. | + +The `isHidden` and `isExpanded` props should always have opposite values of one another; if an accordion toggle is collpased (`isExpanded={false}`), then the accordion content should be hidden (`isHidden={true}`). ## HTML/CSS library considerations @@ -38,9 +40,9 @@ When using PatternFly's HTML/CSS library consumers must take several considerati | Attribute | Applied to | Reason | |---|---|---| -| aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the expanded content element is collapsed to assistive technologies. **Required** | -| aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the expanded content element is expanded to assistive technologies. **Required** | -| hidden | .pf-c-accordion__expanded-content | Visually hides the expanded content element. **Required** when `aria-expanded="false"` is passed in. +| aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** | +| aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the accordion toggle is expanded to assistive technologies. **Required** | +| hidden | .pf-c-accordion__expanded-content | Hides the accordion content. **Required** when `aria-expanded="false"` is passed in. | aria-hidden="true" | .pf-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** | ## Additional considerations diff --git a/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md b/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md index ade82461c9..984f5dd85a 100644 --- a/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md +++ b/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md @@ -7,23 +7,25 @@ Accessibility documentation is meant to help consumers improve accessibility for ## Content architecture -Your accessibility documentation should generally follow the [design guidelines content architecture](/ux-writing/writing-design-guidelines-for-patternfly#content-architecture). +Your accessibility documentation should generally follow the [design guidelines content architecture](/ux-writing/writing-design-guidelines-for-patternfly#content-architecture), with the below additions. ### Keyboard inputs When referencing specific inputs on a keyboard, wrap each input in a `kbd` element and capitalize the first letter of the input. When referencing a combination of inputs, place each input in its own `kbd` element with a "+" between them. -For example: +Example: -"When a user presses Tab + Shift..." +>When a user presses Tab + Shift... ### Person first language When referring to specific types of users in your documentation, use person first language. This places emphasis on the person before the assistive technology, disability, or limitation. -For example: +Example: -"Users interacting via keyboard..." or "Users with a color deficiency..." +>Users interacting via keyboard... +> +>Users with a color deficiency... ## General structure @@ -43,13 +45,15 @@ Avoid detailing how the component achieves a specific accessibility functionalit Example: ->The following guidelines outline some of the ways that a PatternFly **accordion** should generally be operable, understandable, and perceivable in order to improve accessibility for users. +>The following guidelines outline some of the ways that a PatternFly **componentName** should generally be operable, understandable, and perceivable in order to improve accessibility for users. > >- Bullet item describing a guideline... ### React library considerations -This section should only refer to the React library. It should include what considerations PatternFly has taken and built into the component by default and why, often so that consumers are not required to manually pass anything in themselves (even if there is the option to do so). This can include expanding upon the previous section by explaining *how* some functionality occurs. For example, "The component has `tabIndex="0"` so that users interacting via keyboard can...". +This section should only refer to the React library. It should include what considerations PatternFly has taken and built into the component by default and why, often so that consumers are not required to manually pass anything in themselves (even if there is the option to do so). This can include expanding upon the previous section by explaining *how* some functionality occurs: + +>The component has `tabIndex="0"` so that users interacting via keyboard can... Consumers should be able to read this section and understand what accessibility functionality is built into the component and for what purpose. This should provide them a better understanding of what functionality affects the component's accessibility should it be customized in some way. @@ -103,12 +107,15 @@ Example: This section should include any additional considerations a consumer should take when using the component. It should only include more general considerations that don't pertain only to the React or HTML/CSS library, and have not been mentioned elsewhere in the documentation. +Depending on your content, you can include sub-sections with a level 3 heading, an unordered list of considerations, or both. + If there are no additional considerations, this section can be omitted. Example: >Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. > +> - A list item for an additional consideration... >### Consideration heading > >An explanation of an additional consideration... From bda3b7c2a3a3d5ba6c2dda0e545c250dceeb1490 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Fri, 17 Jun 2022 14:07:51 -0400 Subject: [PATCH 05/11] Remove duplicate a11y info from accordion design guidelines --- .../components/accordion/accordion.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md b/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md index ad564ff6c6..a32bcd750c 100644 --- a/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md @@ -36,13 +36,3 @@ The accordion is used not only to help shorten the page length, but also provide Some common use cases include using an accordion in the FAQ section and product comparison. Accordion multi-expand behavior - - -## Accessibility -When implementing this component, consider the following guidance to ensure that it is 508 compliant. - -1. Use unique and descriptive labels for each header bar. This allows both sighted users and those with assitive technologies to quickly scan through the content, without having to expand individual panels. -2. Avoid adding complex interaction to the accordion. This can often cause loops or traps that prevent users from efficiently navigating the content using a keyboard. - - - From 4bed14c5e7cf28627bb1a5976cd0b22c4a7bcd4b Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Mon, 27 Jun 2022 09:21:04 -0400 Subject: [PATCH 06/11] Make suggested updates --- .../accessibility/accordion/accordion.md | 62 ++++++++++++------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md index e260ecae4b..35741a71ed 100644 --- a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md @@ -3,51 +3,67 @@ id: Accordion section: components --- -## Accessibile application +import { Checkbox, List, ListItem } from '@patternfly/react-core'; -The following guidelines outline some of the ways that a PatternFly **accordion** should generally be operable, understandable, and perceivable in order to improve accessibility for users. +## Accessibility -- Each accordion toggle should be a button that includes unique and descriptive labels so that users can more quickly scan through the accordion contents without having to expand individual panels. An accordion toggle should also include an icon to visually notify users if an accordion item is in an expanded or collapsed state. -- Users interacting via keyboard should be able to use standard keyboard navigation to navigate between accordion toggles or other focusable elements: Tab to navigate to the next accordion toggle or focusable element, and Shift + Tab to navigate to the previous accordion toggle or focusable element. -- An accordion toggle should be able to be collapsed or expanded by pressing either Space or Enter. -- Users interacting via screen reader or similar assistive technologies with an announced output should be notified whether the accordion toggle is in an expanded or collapsed state when focus is first placed on it, and they should be informed when the state of the currently focused accordion toggle changes. -- When using headings for an accordion, never skip heading levels within the context of the rest of the page. +To implement an accessible PatternFly **accordion**: -## React library considerations +- Give each accordion toggle a unique and descriptive label. +- Include the `isExpanded` prop (PatternFly React) or `aria-expanded` attribute (HTML/CSS) on the accordion toggle based on the toggle's state. -PatternFly's React library has taken into account various considerations for the standard use of an accordion by ensuring certain accessibility functionality is built-in by default. +## Testing -- The accordion toggle is a `button`, allowing for standard keyboard, mouse, or touch interaction and allowing it to be tabbed to. -- The icon for an accordion toggle has `aria-hidden="true"` to remove it from the accessibility tree since it is decorative content. This prevents assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. +At a minimumm, an accordion should meet the following criteria: -### Customizable props + + + + + + Tab navigates to the next accordion toggle or focusable element, and Shift + Tab navigates to the previous accordion toggle or focusable element.} /> + + + Accordion toggles can be collapsed or expanded via keyboard by pressing Space or Enter.} /> + + + + + + This can be checked with a screen reader, or by checking that the aria-expanded attribute is accurate and updating in the DOM.} /> + + -The table below outlines the various React props that can be passed in or customized by the consumer, and which can affect accessibility. Each prop includes what component it should be applied to, the reason for using it or what it does, and whether it is ever required. +## React customization + +Various React props have been provided for more fine-tuned control over accessibility. | Prop | Applied to | Reason | |---|---|---| -| aria-label | Accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with a descriptive label. | -| headingLevel | Accordion | When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a section that has an `h2` heading, you should not pass `headingLevel="h4"`. | +| aria-label | Accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. | +| headingLevel | Accordion | When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a page section that has an `h2` heading, you should not pass `headingLevel="h4"`. | | aria-label | AccordionContent | Adds an accessible name to the content of an accordion item. | | isHidden | AccordionContent | Determines whether the content of the accordion item is hidden or not. Should be used along with the `isExpanded` prop on the accordion toggle. | -| isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded="true/false"`, which notifies screen readers whether the accordion toggle is expanded or collapsed. Should be used along with the `isHidden` prop on the accordion content. | +| isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded` with a value of "true" or "false", which notifies screen readers whether the accordion toggle is expanded ("true") or collapsed ("false"). Should be used along with the `isHidden` prop on the accordion content. | The `isHidden` and `isExpanded` props should always have opposite values of one another; if an accordion toggle is collpased (`isExpanded={false}`), then the accordion content should be hidden (`isHidden={true}`). -## HTML/CSS library considerations +## HTML/CSS customization -When using PatternFly's HTML/CSS library consumers must take several considerations into account by following the table below, which outlines the various HTML attributes that can affect accessibility. Each attribute includes what element it should be applied to, the reason for using it or what it does, and whether it is ever required. +Various HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility. | Attribute | Applied to | Reason | |---|---|---| -| aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** | -| aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the accordion toggle is expanded to assistive technologies. **Required** | -| hidden | .pf-c-accordion__expanded-content | Hides the accordion content. **Required** when `aria-expanded="false"` is passed in. -| aria-hidden="true" | .pf-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-label | .pf-c-accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. | +| aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** if the toggle is collapsed. | +| aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the accordion toggle is expanded to assistive technologies. **Required** if the toggle is expanded. | +| aria-label | .pf-c-accordion__expanded-content | Adds an accessible name to the content of an accordion item. | +| hidden | .pf-c-accordion__expanded-content | Hides the accordion content. **Required** when `aria-expanded="false"` is passed in. | +| aria-hidden="true" | .pf-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**. | ## Additional considerations -Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. +Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere on this page. - Avoid adding complex interaction to the accordion. This can often cause loops or traps that prevent users from efficiently navigating the content when using a keyboard. From 0a304b5c1ae0c467a3c390c1360beca08a3797b8 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Wed, 29 Jun 2022 08:43:10 -0400 Subject: [PATCH 07/11] Update minor difference between guidelines --- .../content/accessibility/accordion/accordion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md index 35741a71ed..40208c132d 100644 --- a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md @@ -52,7 +52,7 @@ The `isHidden` and `isExpanded` props should always have opposite values of one Various HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility. -| Attribute | Applied to | Reason | +| Attribute or class | Applied to | Reason | |---|---|---| | aria-label | .pf-c-accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. | | aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** if the toggle is collapsed. | From 79ceeb878bbea60364eb8de42deaf223c58b9a74 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Thu, 30 Jun 2022 16:11:23 -0400 Subject: [PATCH 08/11] Add example for aria label prop --- .../accessibility/accordion/accordion.md | 37 ++++++++++++++++++- .../components/accordion/accordion.md | 4 ++ 2 files changed, 39 insertions(+), 2 deletions(-) diff --git a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md index 40208c132d..0de0ee765d 100644 --- a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md @@ -46,7 +46,40 @@ Various React props have been provided for more fine-tuned control over accessib | isHidden | AccordionContent | Determines whether the content of the accordion item is hidden or not. Should be used along with the `isExpanded` prop on the accordion toggle. | | isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded` with a value of "true" or "false", which notifies screen readers whether the accordion toggle is expanded ("true") or collapsed ("false"). Should be used along with the `isHidden` prop on the accordion content. | -The `isHidden` and `isExpanded` props should always have opposite values of one another; if an accordion toggle is collpased (`isExpanded={false}`), then the accordion content should be hidden (`isHidden={true}`). +### isHidden and isExpanded + +The `isHidden` and `isExpanded` props should always have opposite values of one another; if an accordion toggle is collapsed (`isExpanded={false}`), then the accordion content should be hidden (`isHidden={true}`). For example: + +```noLive +const [expandedItem, setExpandedItem] = React.useState('accordion-item-1'); + + + + + Toggle text... + + + Content text... + + + +``` + +### Aria-label + +Passing in the `aria-label` prop to the accordion component can be helpful when there are multiple accordions on a page, or when there is no other surrounding context: + +```noLive + + ... + + + + ... + +``` ## HTML/CSS customization @@ -54,7 +87,7 @@ Various HTML attributes and PatternFly classes can be used for more fine-tuned c | Attribute or class | Applied to | Reason | |---|---|---| -| aria-label | .pf-c-accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. | +| aria-label | .pf-c-accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text.

See the [aria-label prop example](#aria-label) in the React customization section. | | aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** if the toggle is collapsed. | | aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the accordion toggle is expanded to assistive technologies. **Required** if the toggle is expanded. | | aria-label | .pf-c-accordion__expanded-content | Adds an accessible name to the content of an accordion item. | diff --git a/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md b/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md index a32bcd750c..d3138758ca 100644 --- a/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md @@ -36,3 +36,7 @@ The accordion is used not only to help shorten the page length, but also provide Some common use cases include using an accordion in the FAQ section and product comparison. Accordion multi-expand behavior + +## Accessibility + +For information regarding accessibility, visit the [accordion accessibility](/components/accordion/accessibility) page. \ No newline at end of file From 88cd355730c069df0f630226a7f8a689645fa7fe Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Wed, 6 Jul 2022 11:50:29 -0400 Subject: [PATCH 09/11] Separate out library instructions --- .../accessibility/accordion/accordion.md | 33 +++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md index 0de0ee765d..841800c778 100644 --- a/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/accessibility/accordion/accordion.md @@ -10,7 +10,14 @@ import { Checkbox, List, ListItem } from '@patternfly/react-core'; To implement an accessible PatternFly **accordion**: - Give each accordion toggle a unique and descriptive label. -- Include the `isExpanded` prop (PatternFly React) or `aria-expanded` attribute (HTML/CSS) on the accordion toggle based on the toggle's state. + +For the PatternFly React library: + +- Include the `isExpanded` prop on the accordion toggle based on the toggle's state. + +For the HTML/CSS library: + +- Include the `aria-expanded` attribute on the accordion toggle based on the toggle's state. ## Testing @@ -40,11 +47,11 @@ Various React props have been provided for more fine-tuned control over accessib | Prop | Applied to | Reason | |---|---|---| -| aria-label | Accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. | -| headingLevel | Accordion | When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a page section that has an `h2` heading, you should not pass `headingLevel="h4"`. | -| aria-label | AccordionContent | Adds an accessible name to the content of an accordion item. | -| isHidden | AccordionContent | Determines whether the content of the accordion item is hidden or not. Should be used along with the `isExpanded` prop on the accordion toggle. | -| isExpanded | AccordionToggle | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded` with a value of "true" or "false", which notifies screen readers whether the accordion toggle is expanded ("true") or collapsed ("false"). Should be used along with the `isHidden` prop on the accordion content. | +| `aria-label` | `Accordion` | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. | +| `headingLevel` | `Accordion` | When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a page section that has an `h2` heading, you should not pass `headingLevel="h4"`. | +| `aria-label` | `AccordionContent` | Adds an accessible name to the content of an accordion item. | +| `isHidden` | `AccordionContent` | Determines whether the content of the accordion item is hidden or not. Should be used along with the `isExpanded` prop on the accordion toggle. | +| `isExpanded` | `AccordionToggle` | Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded` with a value of "true" or "false", which notifies screen readers whether the accordion toggle is expanded ("true") or collapsed ("false"). Should be used along with the `isHidden` prop on the accordion content. | ### isHidden and isExpanded @@ -87,12 +94,12 @@ Various HTML attributes and PatternFly classes can be used for more fine-tuned c | Attribute or class | Applied to | Reason | |---|---|---| -| aria-label | .pf-c-accordion | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text.

See the [aria-label prop example](#aria-label) in the React customization section. | -| aria-expanded="false" | .pf-c-accordion__toggle | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** if the toggle is collapsed. | -| aria-expanded="true" | .pf-c-accordion__toggle | Indicates that the accordion toggle is expanded to assistive technologies. **Required** if the toggle is expanded. | -| aria-label | .pf-c-accordion__expanded-content | Adds an accessible name to the content of an accordion item. | -| hidden | .pf-c-accordion__expanded-content | Hides the accordion content. **Required** when `aria-expanded="false"` is passed in. | -| aria-hidden="true" | .pf-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-label` | `.pf-c-accordion` | Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text.

See the [aria-label prop example](#aria-label) in the React customization section. | +| `aria-expanded="false"` | `.pf-c-accordion__toggle` | Indicates that the accordion toggle is collapsed to assistive technologies. **Required** if the toggle is collapsed. | +| `aria-expanded="true"` | `.pf-c-accordion__toggle` | Indicates that the accordion toggle is expanded to assistive technologies. **Required** if the toggle is expanded. | +| `aria-label` | `.pf-c-accordion__expanded-content` | Adds an accessible name to the content of an accordion item. | +| `hidden` | `.pf-c-accordion__expanded-content` | Hides the accordion content. **Required** when `aria-expanded="false"` is passed in. | +| `aria-hidden="true"` | `.pf-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**. | ## Additional considerations @@ -102,6 +109,6 @@ Consumers must ensure they take any additional considerations when customizing a ## Further reading -To read more about accessibility with accordions, refer to the resources listed below. +To read more about accessibility with accordions, refer to the following resources: - [ARIA Authoring Practices Guide - Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) \ No newline at end of file From 6f55ea3508a2574c6a4124a70edbc53c806a5463 Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Wed, 6 Jul 2022 14:54:20 -0400 Subject: [PATCH 10/11] Remove files after rebase --- .../content/accessibility/a11y-template.md | 78 ---------- .../writing-accessibility-documentation.md | 133 ------------------ 2 files changed, 211 deletions(-) delete mode 100644 packages/v4/patternfly-docs/content/accessibility/a11y-template.md delete mode 100644 packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md diff --git a/packages/v4/patternfly-docs/content/accessibility/a11y-template.md b/packages/v4/patternfly-docs/content/accessibility/a11y-template.md deleted file mode 100644 index b202cb23d0..0000000000 --- a/packages/v4/patternfly-docs/content/accessibility/a11y-template.md +++ /dev/null @@ -1,78 +0,0 @@ -The following is a general template for how accessibility docs should be written for components. Following the code block below are further explanations of each section, including replacement verbiage under certain circumstances. - -``` ---- -id: { Component name (sentence case) } -section: components ---- - -## Accessibile application - -The following guidelines outline some of the ways that a PatternFly { component name } should generally be operable, understandable, and perceivable in order to improve accessibility for users. - -{ Explanation(s) for how the component should generally be operable, understandable, and perceivable by various types of users. } - -## React library considerations - -PatternFly's React library has taken into account various considerations for the standard use of {"a"/"an"} { component name } by ensuring certain accessibility functionality is built-in by default. - -{ Explanation(s) of considerations that can be summed up in a sentence or two, and do not need any accompanying code snippets or images. } - -Additionally, some further considerations provided by PatternFly are outlined below. - -### { Consideration heading } - -{ An explanation for a consideration that needs more detail, including what it does or is for and any necessary code snippets or images. } - -### Customizable props - -The table below outlines the various React props that can be passed in or customized by the consumer, and which can affect accessibility. Each prop includes what component it should be applied to, the reason for using it or what it does, and whether it is ever required. - -| Prop | Applied to | Reason | -|---|---|---| -| propName | ComponentName | Reason for using propName | - -## HTML/CSS library considerations - -When using PatternFly's HTML/CSS library consumers must take several considerations into account by following the table below, which outlines the various HTML attributes that can affect accessibility. Each attribute includes what element it should be applied to, the reason for using it or what it does, and whether it is ever required. - -| Attribute | Applied to | Reason | -|---|---|---| -| attribute-name | selector | Reason for using attribute-name | - -## Additional considerations - -Consumers must ensure they take any additional considerations when customizing {"a"/"an"} {component name}, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. - -### { Consideration heading } - -{ An explanation of the consideration and what a consumer must ensure. } - -## Further reading - -To read more about accessibility with {component name}'s, refer to the resources listed below. - -- { A link to a resource } -``` - -**Accessible application**:** This section should serve as a higher-level overview for how various types of users should be able to operate, perceive, or understand the component, or what the component should do/how it should function within the context of a page. Use separate paragraphs for different areas of the component functionality/behavior. When referring to specific types of users, use user-first verbiage, e.g. "Users interacting via keyboard..." or "Users with a color deficiency..." - -This section should only state what should occur rather than *how* it occurs via mentions of React props or HTML attributes, e.g. "Users interacting via keyboard should be able to press **Tab** to place focus on the component", rather than "The component has `tabindex="0"` to allow focus to be placed on it via keyboard." - -Consumers should be able to read this section and have an understanding for whether their application of the component meets the points outlined, regardless of whether they are using the component as-is or customizing it in some way. - -**React library considerations**: This section refers only to the React library. It should include what considerations PatternFly has taken and built into the component by default and why, often so that consumers are not required to manually pass anything in themselves (even if there is the option to do so). This can include expanding upon the previous section by explaining *how* some functionality occurs, e.g. "The component has `tabindex="0"` to allow focus to be placed on it via keyboard." - -Considerations that do not need a detailed explanation or accompanying code snippets/images should not receive their own sub-section, while more lengthy/significant explanations or considerations that include code snippets/images should be given their own sub-section. - -Consumers should be able to read this section and understand what accessibility functionality is built into the component and for what purpose, so that they have a better understanding of the component's accessibility should they customize it in some way. - -If PatternFly has not built any accessibility functionality in by default, the verbiage of the section should be replaced with, "By default, {"a" / "an"} {component name} does not have any accessibility functionality built into it by PatternFly. Any considerations must be taken by the consumer, some of which are outlined in the sub-section below." - -**Customizable props**: This sub-section serves to inform consumers of some of the considerations they should take when using the component from the React library. It should only include a table of the various React props that can be passed in and/or customized, and which can affect accessibility. Consumers should be able to read this section and understand how a specific prop should be used and how it will affect accessibility when they pass it in or customize it. - -**HTML/CSS library considerations**: This section refers only to the HTML/CSS library. It should only include a table of the various attributes that a consumer can pass in and which can affect accessibility. Consumers should be able to read this section and understand how a specific attribute should be used and how it will affect accessibility when they pass it in. - -**Additional considerations**: This section should include any additional considerations a consumer should take. It should only include more general considerations that don't pertain specifically to either the React or HTML/CSS library. If there are no additional considerations, this section can be omitted. - -**Further reading**: This section should include any significant resources in regards to the component's accessibility. It can usually include links to a specific section of the WCAG, the WAI-ARIA authoring practices, or other resources that PatternFly may have used in coming to decisions on accessibiltiy functionality. If there are no resources to include, this section can be omitted. \ No newline at end of file diff --git a/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md b/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md deleted file mode 100644 index 984f5dd85a..0000000000 --- a/packages/v4/patternfly-docs/content/developer-resources/writing-accessibility-documentation.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -id: Writing accessibility documentation for PatternFly -section: accessibility ---- - -Accessibility documentation is meant to help consumers improve accessibility for their users. This page focuses on how to write consistent and robust accessibility documentation. - -## Content architecture - -Your accessibility documentation should generally follow the [design guidelines content architecture](/ux-writing/writing-design-guidelines-for-patternfly#content-architecture), with the below additions. - -### Keyboard inputs - -When referencing specific inputs on a keyboard, wrap each input in a `kbd` element and capitalize the first letter of the input. When referencing a combination of inputs, place each input in its own `kbd` element with a "+" between them. - -Example: - ->When a user presses Tab + Shift... - -### Person first language - -When referring to specific types of users in your documentation, use person first language. This places emphasis on the person before the assistive technology, disability, or limitation. - -Example: - ->Users interacting via keyboard... -> ->Users with a color deficiency... - -## General structure - -Your documentation should follow a defined structure of headings and sections, which are outlined in the following sub-sections. Each section includes default verbiage, usually prefacing the content that you will add in yourself. Depending on your content, you might find it necessary to omit or alter various sections. - -### Accessible application - -This section should serve as a list of higher-level guidelines for how various types of users should be able to operate, perceive, or understand the component, or what the component should do/how it should function within the context of a page. - -Consumers should be able to read this section and have a general understanding for whether their application of the component satisfies the points outlined, regardless of whether they are using the component as-is or customizing it in some way. - -Avoid detailing how the component achieves a specific accessibility functionality, and instead only state what the expected functionality is. - -| Do | Don't | -|:--|:--| -| "Users interacting via keyboard should be able to..." | "The component has `tabIndex="0"` so that users interacting via keyboard can..." | - -Example: - ->The following guidelines outline some of the ways that a PatternFly **componentName** should generally be operable, understandable, and perceivable in order to improve accessibility for users. -> ->- Bullet item describing a guideline... - -### React library considerations - -This section should only refer to the React library. It should include what considerations PatternFly has taken and built into the component by default and why, often so that consumers are not required to manually pass anything in themselves (even if there is the option to do so). This can include expanding upon the previous section by explaining *how* some functionality occurs: - ->The component has `tabIndex="0"` so that users interacting via keyboard can... - -Consumers should be able to read this section and understand what accessibility functionality is built into the component and for what purpose. This should provide them a better understanding of what functionality affects the component's accessibility should it be customized in some way. - -Considerations that do not need a detailed explanation, or accompanying code blocks or images, should not receive their own sub-section. If a consideration has a more lengthy explanation, is considered more significant, or has accompanying code blocks or images, it should be given its own sub-section. - -Example: - ->PatternFly's React library has taken into account various considerations for the standard use of an accordion by ensuring certain accessibility functionality is built-in by default. -> ->A simple explanation that doesn't require accompanying code blocks or images... -> ->Additionally, some further considerations provided by PatternFly are outlined below. -> ->### Consideration heading -> ->A more complex or significant explanation, with or without accompanying code blocks or images. - -If PatternFly has not built any accessibility functionality in by default, the content of the section should be replaced to notify consumers of this. Example: - ->By default, PatternFly has not built in any accessibility functionality into the accordion. Any considerations must be taken by the consumer, some of which are outlined in the sub-section below. - -### Customizable props - -This sub-section should only include a table of the various React props that can be passed in and/or customized, and which can affect accessibility. - -Consumers should be able to read this section and understand how a specific prop should be used and how it will affect accessibility when they pass it in or customize it. - -Example: - ->The table below outlines the various React props that can be passed in or customized by the consumer, and which can affect accessibility. Each prop includes what component it should be applied to, the reason for using it or what it does, and whether it is ever required. -> ->| Prop | Applied to | Reason | ->|---|---|---| ->| propName | ComponentName | Reason for using propName | - -### HTML/CSS library considerations - -This section should only refer only to the HTML/CSS library. It should only include a table of the various attributes that a consumer can pass in and which can affect accessibility. - -Consumers should be able to read this section and understand how a specific attribute should be used and how it will affect accessibility when they pass it in. - -Example: - ->When using PatternFly's HTML/CSS library consumers must take several considerations into account by following the table below, which outlines the various HTML attributes that can affect accessibility. Each attribute includes what element it should be applied to, the reason for using it or what it does, and whether it is ever required. -> ->| Attribute | Applied to | Reason | ->|---|---|---| ->| attribute-name | selector | Reason for using attribute-name | - -### Additional considerations - -This section should include any additional considerations a consumer should take when using the component. It should only include more general considerations that don't pertain only to the React or HTML/CSS library, and have not been mentioned elsewhere in the documentation. - -Depending on your content, you can include sub-sections with a level 3 heading, an unordered list of considerations, or both. - -If there are no additional considerations, this section can be omitted. - -Example: - ->Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere in this accessibility documentation. -> -> - A list item for an additional consideration... ->### Consideration heading -> ->An explanation of an additional consideration... - -### Further reading - -This section should include any significant resources in regards to the component's accessibility. It can usually include links to a specific section of the [WCAG](https://www.w3.org/TR/WCAG21/) or the [ARIA authoring practices guide](https://www.w3.org/WAI/ARIA/apg/), or other resources that PatternFly may have used in coming to decisions on accessibiltiy functionality. - -If there are no resources to include, this section can be omitted. - -Example: - ->To read more about accessibility with accordions, refer to the resources listed below. -> ->- A resource link \ No newline at end of file From 0eee92e1c99b72eed5d0f02cf73364757cb8436d Mon Sep 17 00:00:00 2001 From: Eric Olkowski Date: Thu, 7 Jul 2022 15:02:34 -0400 Subject: [PATCH 11/11] Update verbiage --- .../content/design-guidelines/components/accordion/accordion.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md b/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md index d3138758ca..d46a2f6f8e 100644 --- a/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md +++ b/packages/v4/patternfly-docs/content/design-guidelines/components/accordion/accordion.md @@ -39,4 +39,4 @@ Some common use cases include using an accordion in the FAQ section and product ## Accessibility -For information regarding accessibility, visit the [accordion accessibility](/components/accordion/accessibility) page. \ No newline at end of file +For information regarding accessibility, visit the [accordion accessibility](/components/accordion/accessibility) tab. \ No newline at end of file