Why accessible documentation is a must for design systems

Design system documentation is a foundational part of how products are designed, used, and delivered at a company. Similar to a style guide, documentation gets everyone on the same page. Without it, component usage can be open to interpretation. When it comes to accessibility, documentation can help guide rules and goalposts for keeping things accessible by default. 

Why writing accessibility documentation is good practice

Documentation is critical to a successful, impactful design system. It removes friction for new users; gives context for elements and tokens; supports evangelism, and helps with governance. These benefits are limited if the documentation isn’t written or stored accessibly; as with design and development, accessibility is a key element of functionality.

The positive impact of accessible documentation is multi-fold. Some of these benefits include:

Focus on creativity, not memorization

The human memory is unreliable and, to recall memories, often relies on a constructive process, auto-filling any missing pieces. For designers and developers trying to maintain consistency and work in patterns, memory is their worst enemy. Shifting the focus to research and interpretation of accessibility guidelines, instead of rote recall, is the secret to successful design system accessibility.

Accessible guidelines empower developers and designers to understand the “big picture” of the design system. Instead of having to memorize endless rules, they can engage in pattern-based workflows, using common sense combined with basic guidelines to work independently (based on precedent). 

Build a good foundation for the whole team

Researching fresh lets you interpret and make new connections. Reciting WCAG or Material guidelines from memory doesn’t help you to compare it with or apply it to new information. This kind of improvisation is a skill requiring a more broad understanding of universal design principles. This also requires an understanding of accessibility and design systems and usage. The advantage is you don’t have to understand auditing or managing accessibility.

For new teammates, or those who are unfamiliar with WCAG guidelines, it can be daunting to look at and digest accessibility guides like WCAG. To internalize and use all of that information, you need a basic understanding of the principles of accessibility. 

To embed this understanding into your design system, you can:

• Use component documentation to highlight relevant accessibility features, decreasing overload and shortening onboarding.
• Link to related components to create progressive understanding or easy ideation
• Create reusable modules and patterns to increase accessibility on difficult-to-use component combinations.
  

Shifting accessible design/development needs from memorization to interpretation takes the pressure off you and your team to know everything on the spot. Even better, it sets culture norms across your team and product org. On-the-spot estimation requests in the hallway can become a thing of the past.

Want to contribute to Design System Insights by Knapsack? Get in touch!

How accessibility strengthens documentation

Writing accessible documentation isn’t just the right thing to do; it’s in the business’ best interest. To maximize productivity, minimize onboarding, and encourage reuse within your design system, write documentation that can be understood with minimal outside guidance by anyone interacting with your design system.

Dedicate space to accessibility

Having your own designated space is not only nice, it’s necessary for operations. Delivery is already a tough time for many product teams, and teams new to accessibility might feel overwhelmed. Product, engineering, and design teams can collaborate on guidelines and stay on the same page when in delivery mode when there is documentation on accessibility.

Documentation can serve as a “preflight” for cross-functional teams to make sure all the boxes both accessibility and otherwise have been checked before shipping. Global documentation (where color, typography, and layout usually live) is a great place to include accessibility. You can document the practical principles as well as express risk tolerance and accessibility processes.

Repeat excellence with component documentation 

Documentation allows us to stop solving the same problems over and over like Sisiphus rolling a boulder up a hill endlessly. Solving for documentation allows teams to mature and move to solving strategic, novel problems. In product maturity, repeatable results are the heart of mature teams. Being able to repeat consistent, tested, and successful results will never put you out of a job—it will change the type of problem you are working on. 

Systems components alone make accessibility more repeatable. Documentation sounds like it’s optional. It’s creating written guides, states of components, and limits. Documentation magnifies accessibility, guiding team members less familiar with accessibility and giving structure and rigor to practice. 

Break into pieces for smaller steps and easier estimation

Sometimes when looking at a list of all the separate pages that have to be audited, it can be daunting. Breaking that down into components and then applying the components to the pages feels like smaller bites. Just auditing a design library feels like a smaller lift and a known size. When auditing a design library, you can see what your current speed is by doing an average test component and calculating by the number of components.

Estimation becomes easier and project planning seems less overwhelming. Results are more repeatable and consistent. If your team is looking to scale accessibility quickly, paying attention to design documentation is a key piece of success.

Accessibility and design systems are intertwined

After starting several accessibility transformation programs, I know that accessibility and design systems may seem like a big lift and large skillset add. Accessible design systems still won’t guarantee you an accessible product idea or comprehensive product. But by implementing incremental changes, step by step, you can get to an important goal. In the end, accessibility should be part of the team culture, embedded in everything you do. And when it’s part of everything you do, you can confidently design and build for everyone.