Writing accessibility documentation for PatternFly

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 formatting, with the below additions.

Keyboard inputs

Wrap each keyboard input in a kbd element and capitalize the first letter of each word of the input when referencing specific inputs on a keyboard. Place each input in its own kbd element with a "+" between them when referencing a combination of inputs.

Example:

When a user presses <kbd>Shift</kbd> + <kbd>Tab</kbd>...

Pressing <kbd>Right Arrow</kbd> should...

Person-first language

Use person-first language when referring to specific types of users in your documentation. This places emphasis on the person, rather than the disability or assistive technology.

Do	Don't
"Users interacting via keyboard..."	"Keyboard users..."
"Users with a color deficiency..."	"Colorblind users..."

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.

Be sure to include the following import line before the first section of your content:

import { Checkbox, List, ListItem } from '@patternfly/react-core';

If you need to insert links in the "Testing" section of the documentation, include the following import as well:

import { Link } from '@patternfly/documentation-framework/components/link/link';

Accessibility

This section serves as a list of instructions that consumers must follow in order to implement the component in an accessible manner. This should generally only include instructions that apply to the most standard use of the component. More specific use-case information should instead be placed in the appropriate customization sections or under additional considerations.

Instructions should be broken into separate lists for general instructions, those that apply only to the PatternFly React library, and those that apply only to the HTML/CSS library.

Consumers should be able to read only this section and still be able to ensure they are implementing the component in an accessible manner. All other sections of the accessibility documentation should serve as additional reading that expands upon this section with more detailed explanation or provides additional information.

Avoid detailing how the component achieves a specific accessibility functionality or why something should be done, and instead only state what a consumer should do.

Do	Don't
"Provide a unique and descriptive title."	"A descriptive title should be included because..."
"Pass in the aria-label prop with a descriptive text."	"Pass in the aria-label prop so that it can be placed on this sub-component in order to..."

Example:

To implement an accessible PatternFly componentName:

• Provide a unique and descriptive title.

For the PatternFly React library:

• Pass in the exampleProp prop...

For the HTML/CSS library:

• Pass in the exampleAttribute attribute...

Testing

This section provides a checklist of self-evaluated tests that can be checked against an implementation of the component. Each checklist item can include additional information or can expand upon why a particular test matters. This section can also include items from the previous section, and should only include tests for the most standard use of the component.

When inserting links in testing item labels or descriptions, be sure to use the <Link> component that is imported from the documentation framework.

Consumers should be able to check off each test item that applies to their use-case in order to ensure their use of the component is functioning in as accessible a manner as possible.

Example:

At a minimum, a PatternFly componentName should meet the following criteria:

<List isPlain>
 <ListItem>
   <Checkbox 
     id="componentName-a11y-checkbox-1" 
     label="The componentName has the aria-label prop passed in when there is no title." 
     description="This provides more accurate context for users navigating via screen reader." 
   />
 </ListItem>
</List>

If you would like to use an inline code block within the checkbox label or description, be sure to wrap the content in a <code className="ws-code">...</code> element. This will apply consistent styling for inline code blocks with other PatternFly pages. When inserting other HTML elements in either the testing item label or description, you must wrap the passed in content inside of a <span> element. For example:

<List isPlain>
 <ListItem>
   <Checkbox 
     id="componentName-a11y-checkbox-1" 
     label={<span>A label that mentions the <kbd>Escape</kbd> key.</span>} 
     description={<span>A description that links to <Link href="/some/link">another component</Link>.</span>} 
   />
 </ListItem>
</List>

React customization

This section should only refer to the PatternFly React library. It should usually only include a table of the various React props that can be passed in and/or customized, and which can affect accessibility. If a prop should have a value passed into it, the "Prop" column should include a placeholder value that describes what should be passed in.

Code blocks or any additional information regarding the props can also be included after the table.

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. They should also be able to utilize the information in this section if their use-case isn't entirely covered by the first two sections or if they want further information about a specific prop.

Example:

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

Prop	Applied to	Reason
propName="[a placeholder value]"	ComponentName	Reason for using propName
isPropName	ComponentName	Reason for using isPropName

If there are no React props to list in this section, the content of this section should be, "A/an [component] does not have any further React props for accessibility."

HTML/CSS customization

This section should only refer to the HTML/CSS library. It should usually only include a table of the various attributes and classes that a consumer can use and which can affect accessibility. If an attribute should have a value passed into it, the "Attribute or class" column should include a placeholder value that describes what should be passed in.

Code blocks or any additional information regarding the attributes or class names can also be included after the table.

Consumers should be able to read this section and understand how a specific attribute or class name should be used and how it will affect accessibility when they use it. They should also be able to utilize the information in this section if their use-case isn't entirely covered by the first two sections or if they want further information about a specific attribute/class name.

Example:

The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.

Attribute or class	Applied to	Reason
attribute-name="[a placeholder value]"	selector	Reason for using attribute-name
another-attribute	selector	Reason for using another-attribute
class="class-name"	selector	Reason for using class

If there are no HTML/CSS attributes or classes to list in this section, the content of this section should be, "A/an [component] does not have any further HTML/CSS attributes or classes for accessibility."

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 PatternFly 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 a componentName, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere on this page.

• 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 or the ARIA authoring practices guide, or other resources that PatternFly may have used in coming to decisions on accessibility functionality.

If there are no resources to include, this section can be omitted.

Example:

To read more about accessibility with a componentName, refer to the following resources:

• A resource link