Just in time accessibility docs

Just in time accessibility docs

Just in time accessibility docs

Aug 24, 2024

Equitable design patterns

I think I’ve been doing it all wrong. As we build out our design system, we’ve been continuing to add lengthy accessibility documentation to each of our components, check. But is it actually helpful

  • W3C Guidelines are verbose and many of the guidelines become redundant once the component has been built.

  • Text based documentation can be hard to visualize without examples or access to assistive technology.

  • While components may test accessible in isolation, new issues come up when components are used in context.

Resources

Some folks who are doing it right that we're trying to learn from at Exygy

Carbon design system from IBM provides context specific tips for both designers and developers. The guidelines they provide act as quick implementation checklists.

GOLD Design System by Design System AU is really unique in the way that it provides accessibility previews of components. I really dig how they simulate keyboard navigation and color blindness!

USWDS from GSA goes above and beyond any system that I have seen by providing accessibility testing documentation that can be used when doing QA of components in the wild. ...whoa

Takeaways

A couple of things our team has taken away from these amazing resources that might be helpful to others:

  • Focus component documentation on the most "actionable" implementation details for both designers and engineers.

  • Reserve verbose technical setup requirements for the initial component acceptance criteria.

  • Experiment with ways to easily preview accessibility options and outputs.

  • If possible, document how someone could test issues that could come up during ongoing product feature development and QA.

This post was in part inspired by a talk from Dan Mall at the last Figma Config when he referenced "Harry Potter and the Half Blood Prince" to describe the "notes in the margins that help Harry improve his potion skills" as a way to describe better "just in time" design system documentation.

If you do actually need the verbose stuff for component acceptance criteria you can always get it at W3C Authoring practices guide

I think I’ve been doing it all wrong. As we build out our design system, we’ve been continuing to add lengthy accessibility documentation to each of our components, check. But is it actually helpful

  • W3C Guidelines are verbose and many of the guidelines become redundant once the component has been built.

  • Text based documentation can be hard to visualize without examples or access to assistive technology.

  • While components may test accessible in isolation, new issues come up when components are used in context.

Resources

Some folks who are doing it right that we're trying to learn from at Exygy

Carbon design system from IBM provides context specific tips for both designers and developers. The guidelines they provide act as quick implementation checklists.

GOLD Design System by Design System AU is really unique in the way that it provides accessibility previews of components. I really dig how they simulate keyboard navigation and color blindness!

USWDS from GSA goes above and beyond any system that I have seen by providing accessibility testing documentation that can be used when doing QA of components in the wild. ...whoa

Takeaways

A couple of things our team has taken away from these amazing resources that might be helpful to others:

  • Focus component documentation on the most "actionable" implementation details for both designers and engineers.

  • Reserve verbose technical setup requirements for the initial component acceptance criteria.

  • Experiment with ways to easily preview accessibility options and outputs.

  • If possible, document how someone could test issues that could come up during ongoing product feature development and QA.

This post was in part inspired by a talk from Dan Mall at the last Figma Config when he referenced "Harry Potter and the Half Blood Prince" to describe the "notes in the margins that help Harry improve his potion skills" as a way to describe better "just in time" design system documentation.

If you do actually need the verbose stuff for component acceptance criteria you can always get it at W3C Authoring practices guide

I think I’ve been doing it all wrong. As we build out our design system, we’ve been continuing to add lengthy accessibility documentation to each of our components, check. But is it actually helpful

  • W3C Guidelines are verbose and many of the guidelines become redundant once the component has been built.

  • Text based documentation can be hard to visualize without examples or access to assistive technology.

  • While components may test accessible in isolation, new issues come up when components are used in context.

Resources

Some folks who are doing it right that we're trying to learn from at Exygy

Carbon design system from IBM provides context specific tips for both designers and developers. The guidelines they provide act as quick implementation checklists.

GOLD Design System by Design System AU is really unique in the way that it provides accessibility previews of components. I really dig how they simulate keyboard navigation and color blindness!

USWDS from GSA goes above and beyond any system that I have seen by providing accessibility testing documentation that can be used when doing QA of components in the wild. ...whoa

Takeaways

A couple of things our team has taken away from these amazing resources that might be helpful to others:

  • Focus component documentation on the most "actionable" implementation details for both designers and engineers.

  • Reserve verbose technical setup requirements for the initial component acceptance criteria.

  • Experiment with ways to easily preview accessibility options and outputs.

  • If possible, document how someone could test issues that could come up during ongoing product feature development and QA.

This post was in part inspired by a talk from Dan Mall at the last Figma Config when he referenced "Harry Potter and the Half Blood Prince" to describe the "notes in the margins that help Harry improve his potion skills" as a way to describe better "just in time" design system documentation.

If you do actually need the verbose stuff for component acceptance criteria you can always get it at W3C Authoring practices guide

Jesse James Arnold

Jesse James Arnold

Jesse James Arnold