Vanilla’s accessibility documentation process

Following on from our previous post about accessibility by design, we’d like to share our accessibility documentation process here in the Web & Design team. In the Vanilla squad, we work hard to make sure the Vanilla framework is as accessible as possible. We don’t claim to be perfect, but accessibility is a real priority to us and we’re continuously trying to improve. We’ve recently started writing some accessibility docs to go alongside our components. They outline how the components work, and any important accessibility considerations to note in implementation.

The importance

In the current Vanilla implementation docs , we give a code example for each of our components. People can jump into the docs, find which variant they need, then copy and paste the code. Easy, right? We don’t have much to worry about when it’s a simple static component. But, in more complex cases, the implementation is important in making sure the component remains accessible. We decided, instead of expecting people to understand why we added an aria-describedby here, an aria-label there, we thought we’d help with an explanation.

The people involved

We started an Accessibility Guild in the Web & Design team, which has helped us curate a wonderful group of humans from different disciplines with a special interest in accessibility. This means, when the writing commenced, we were lucky to have a wide range of expertise ready and raring to go. The group includes developers, UX (user experience) designers and UI (user interface) designers.

When writing, it’s tough trying to make sure you cover all bases. There are always going to be things you haven’t considered, but involving as many people as possible in the review process reduces the likelihood of this.

Deciding what to include

We haven’t included the accessible design considerations when building the component from scratch, as these aren’t something a user of Vanilla framework has control over. Our wonderful design team do their best to strive towards the most accessible components, so we leave this in their hands.

The problems may arise however in areas we can’t control, such as what someone decides to use for their label text or ARIA attribute values. We figured focussing on this would be the most beneficial for the users – how to use our already existing components in the most accessible way.

What we’ve found so far

The first thing we’ve noticed is how much we’ve learned. To be able to write accurate and concise docs for each component, there needs to be information gathered from different sources. The obvious ones being the Web Content Accessibility Guidelines (WCAG) 2.1 and the WAI-ARIA Authoring Practices 1.1 (Pattern specific guidelines), which have been super helpful. We’ve also gathered ideas by snooping around, and being inspired by, how other design systems have tackled their accessibility documentation, such as the Carbon design system.

All this research has benefited the team hugely. We recently completed an excellent accessibility workshop with HeX productions, and writing the docs has been a great revision for us. Also, delving into each component in such detail means we’ve come across points we may not have initially thought of.

Some components have been (comparatively) a walk in the park, for example the accordion. There’s tons of resources around it. A specific section in the WAI-ARIA pattern specific guidelines made it easy to find what we should cover, along with an example to look at in the Carbon design system.

Others have been more tricky, for example the card. There’s no specific card section in the pattern specific guidelines to follow, so we had to do a little more digging. We had to find which parts of (WCAG) 2.1 are applicable when using cards, and include these in the documentation. 

Some components have had us questioning our current examples. We noticed when researching lists, one of our list examples doesn’t use HTML list elements. This means screen readers won’t know the content should be grouped together, making it not very accessible. A Github issue was filed so we can track and fix it. 

Work in progress

We’ve only just embarked on the journey of writing our accessibility documentation, and we still have some way to go. We’re always learning, and welcome your feedback with open arms. If you’re interested and would like to take a look at what we’ve done so far, you can see which components we’ve already covered and which ones are still in review where we’re tracking this on Github. Please feel free to comment, any feedback is greatly appreciated!