1816515 - [meta] Add web accessibility related documentation to Storybook

Status: NEW

(Toolkit :: UI Widgets, task)

Description

[Tim Giles [:tgiles]]

In order to ensure our reusable widgets are accessible and make this accessibility more easily understandable, we should add accessibility statements next to each component in our Storybook instance.

For example, here is Audi's design system that shows the accessibility statement for their checkbox element. This explains in plain language why the element was implemented this way and has citations to the relevant WCAG criteria as well as other web accessibility resources.

Web accessibility is a complex and deep topic and so we should take the opportunity to make it easier to implement and understand good practices when it comes to this topic. Another thing we could add is something like Microsoft's Fluent UI Accessibility component overview which gives a high level overview of what role their components fill, as well as what is out of scope and how to ensure web accessibility in their components.

Comment 1

[Mark Striemer [:mstriemer]]

We have some accessibility docs in acorn now, but there could be some that are still more technical and belong in Storybook. We will want to link to acorn docs on accessibility when possible.

Comment 2

[Tim Giles [:tgiles]]

I need to break down and refine this ticket more. Now that acorn.firefox.com is live, we can use that as a resource for more high level accessibility considerations. For example, if we create a new button, the accessibility section of buttons in the design system would apply. I don't think we would need to write additional information since the most common accessibility considerations are already addressed in the design system, we would just link out as needed. Then, if there was no relevant accessibility section for a particular element, we could write that in Storybook if it's a implementation specific detail or in Acorn if it's a design detail.

So what would be a case where we would want accessibility details in Storybook but not Acorn? For example, let's use the <button> case. The design system says:

• Use a text label color that has sufficient color contrast with your button's background color.
• Check contrast across all states.
• Use an appropriate font size for your text label, ensuring proper legibility.
• Provide alternative text for all buttons.
• Use a sufficient amount of padding to ensure your button is large enough to reduce frustrating click or touch scenarios.

These points are relevant at the design level as well as the implementation level. I don't think we would want to put any specific accessibility information in Storybook in this case. Maybe the guidance should be to add accessibility information when creating domain specific UI widgets. Since these widgets wouldn't be in the design system, they would need their own recommendations/guidance accordingly (if I understand correctly).

Maybe when there are more complex interactions that only appear when composing widgets? That doesn't feel correct though as those interactions should be encountered and discussed at the design level. Maybe the accessibility details in Storybook are things like why we are doing things the way we are or something.

:hjones, :mstriemer what are your opinions on what kind of accessibility information should go in Storybook? It feels like we should be putting UI developer specific information here, but I'm having a hard time finding a case where that information wouldn't be better suited in the general design system documentation instead. Maybe the domain-specific UI widgets case is the only time we'd put specific accessibility information in Storybook?

Comment 3

[Hanna Jones [:hjones]]

(In reply to Tim Giles [:tgiles] from comment #2)

:hjones, :mstriemer what are your opinions on what kind of accessibility information should go in Storybook? It feels like we should be putting UI developer specific information here, but I'm having a hard time finding a case where that information wouldn't be better suited in the general design system documentation instead.

I wouldn't necessarily assume that someone who just wants to use one of these components is going to read all the design system documentation and all the documentation in Storybook, so there could still be value in distilling down information a developer would need to have in order to make sure they use the component in an accessible way.

We could also include information on how we took accessibility considerations into account when building the components/how the components solve common accessibility problems (or whether or not the components have existing accessibility issues people should be aware of). Some examples might be:

• For moz-toggle you should always provide a label or an aria-label attribute for cases where you don't want to have a visible label
• We could also give some details on why moz-toggle is a button/what the aria-pressed role is doing
• For moz-support-link maybe it's worth mentioning the limitations you identified with the "Learn more" text?
• We could also mention how it's important to maintain the underline styles for moz-support-link/not to rely on color only for link styles (since it's not using the shadow DOM in theory someone could try to override the styles in specific instances)
• For moz-button-group maybe there's something to be said about tab order?

It might be easier to just fit some of this into component specific README files - like maybe we just have an "Accessibility" section when we feel there's something to discuss?

Maybe the domain-specific UI widgets case is the only time we'd put specific accessibility information in Storybook?

So right now we don't explicitly support adding domain-specific widget documentation. It can definitely be done, but we might need to re-think the structure of the storybook/stories folder, or re-think where domain-specific widget stories live.

Comment 4

[Stuart Colville [:muffinresearch]]

Removing this from jira, in favour of tracking the child issues in jira.