Need template/process for communicating accessibility related aspects of design

[seanforyou23]

Design template needed for identifying accessible names in interactive components

I'd like to propose we introduce a somewhat formal means of identifying accessibility-related design concepts in design deliverables to be used as part of the design documentation for every component. Ultimately, this would be an enhancement to the existing design process.

Today, it's almost always the case that we end up with duplicate accessible names for critical interactive controls, which makes the accessible experience (AX) not great. For example, we end up with views that are represented as like below (Notice the duplicate text "Actions collapsed popup buton" which doesn't distinguish between table items)

This problem exists across many of our existing components and it would be good to solve them all in a simple and same manner.

Here's an example of a simple way we can document what the accessible names should be for component elements that may have many instances on a same page.

The main thing to notice in this example is that the accessible name for the edit icon button uses a format which is the text "Edit" followed by the name of the thing it is going to edit. This is critical because, without it, every edit button simply reads "Edit" to assistive technology - which doesn't signify which thing the user is actually editing.

This format should be used for all labels in similar interactions like expanding/deleting/selecting/etc.

IMO the definition for done for this issue would be to have delivered said design documentation for the existing components which currently exhibit this problem. These cases are easily identifiable by driving the documentation site with a screen reader of your choice.

What do others think? Is it something we can commit to or want to do at all? Ping @mcarrano & @mmenestr

[jgiardino]

👍

An example of one method where we are handling a similar situation (e.g. many actions of the same kind for different elements) is with Remove button in the ChipGroup component. In that case, we use aria-labelledby to create an accessible name for the Remove button.

It would be helpful to capture what techniques are possible (aria-label vs aria-labelledby) for meeting this guideline.

Also, regarding the syntax to use for labels, this WCAG item provides some guidance (i.e. the visible label of the element must be stated first, followed by any additional text): https://www.w3.org/WAI/WCAG21/quickref/#label-in-name

[mcarrano]

Thanks for filing this issue @seanforyou23 . Sounds like this is an issue of educating consumers of PatternFly about best practices and what's available to help make pages more accessible. Perhaps the first step is to create more/better documentation. Not sure if this belongs as a design guideline, as part of the component documentation or both. Do you think there is also an opportunity to create a Katacoda tutorial about this?

Because this mostly involves documentation IMO, I am going to move this issue over to patternfly-org for further tracking. If you think there are changes we need to make to any components to achieve this, we can open separate issues.

cc @LHinson @rachael-phillips

[seanforyou23]

I do think educating PF consumers of this detail is important, but specifically, I'm trying to get this addressed on the PatternFly side as much as is practical. To me, this means including information like the above screenshot in design deliverables for components/demos - so that we can put into place better defaults where we possible, and where defaults can't address the uniqueness issue due to the modular nature of how components are expected to be composed, we can at least code the examples in this way so the good end result is still achieved.

I think documenting this in English (like in the design guidelines section) but not having our examples reflect this practice is the major bind we want to avoid. If we show these details in the design deliverables (or at least get the conversation started there) then developers will be better equipped to build real-world examples and write tests that enforce the contracts that are needed to be put into place to guarantee a baseline accessible experience.

Let me know if I can help clarify anything else!

[mcarrano]

@seanforyou23 So when you say "design deliverables," what exactly does that mean to you? Do you mean the documentation that gets exchanged between design and development? I'm just struggling to figure out where this information should live. @rachael-phillips and I have talked about creating a more structured hand off document for new components. Maybe it should live there? @rachael-phillips what do you think?

[seanforyou23]

@mcarrano yes exactly - the documentation that gets exchanged between design and development. Are these what eventually turn into the design guidelines we have in the docs? Having this information in a persistent location would be great as well.