Creating Sa11y

The story and philosophy behind the accessibility quality assurance assistant.

Sa11y is an accessibility checker that visually highlights common accessibility and usability issues. Sa11y straightforwardly identifies errors or warnings at the source with a simple tooltip on how to fix them.

Most accessibility tools are designed for developers and often require knowledge of code to make sense of the results. Sa11y is designed for content authors and focuses on content related issues and successes. Sa11y is not a comprehensive code analysis tool.

Available as a JavaScript plugin, bookmarklet, and WordPress plugin.

Visit the project website.


A little background about why I created Sa11y. Sa11y was originally developed and customized for Toronto Metropolitan University's (TMU) content management system.

With several hundred website editors and over 40, 000 web pages; ensuring brand consistency, usability and website accessibility poses its challenges. As the university's IT Accessibility Specialist, it is one of my responsibilities to ensure all of our websites are accessible.

A couple of cowboys dramatically herding hundreds of cats in open rolling plains.
Trying to get several hundred people to make their content comply with the Web Content Accessibility Guidelines (WCAG) is kind of like herding cats.

Back in 2017, a new website template was created to address many of the branding and accessibility issues. This was also an opportunity to think about web accessibility more strategically. Several significant changes were made to the authoring tool to change the way how and what content authors can publish. To summarize, our content authors:

Long story short, our content editors only need to focus on a few WCAG criteria.

Unlike WordPress or Drupal, our content management system Adobe Experience Manager (AEM) has a small plugin ecosystem. At the time, there were no integrations or plugins for AEM that could help our efforts either. Given the scale of our organization, finding a tool to compliment our new template was still necessary if we wanted to achieve our compliance goals. Several cloud-based accessibility suites were potential contenders. Although there's a few problems with them:

  1. Most of these tools crawl and report issues on published content only.
  2. Content authors require training on how to use these tools, otherwise must decipher what is and what is not an issue.
  3. They flag too much. A content author should not be getting warnings to check for the presence of a "Skip to content" link.
  4. They get very expensive. Pricing is usually determined by API calls or by number of pages your website has.
A football referree signalling no good with his hands.
Don't use a sledgehammer to crack a nut.

Given the small number of WCAG criteria we needed to test for, I looked at various open source tools that I could adapt. My criteria for an automatic tool for content authors:

  1. Worked in-context and was available during content creation.
  2. Focuses on content issues only.
  3. Content author friendly. Should be able to use the tool with minimal or no training.
  4. Scalable. It needed to work on every page.

The closest tool I could find was Tota11y by Khan Academy. I admired it's simplicity and rulesets, although realized it could be simplified even further for internal use. Our forms were already accessible, and our content authors can't introduce contrast issues - which means we could eliminate two of Tota11y's plugins. With the help of TMU computer science students, we dissected Tota11y and created a new prototype that would only focus on alt text, links, and headings. We created several additional rulesets that focused on quality accessible content creation. We eventually had a working prototype and implemented it internally in 2019. In May 2020, we released Sa11y as open-source given its internal success.

Sa11y is currently at version 2, and has greatly improved since it's initial release. Sa11y is featured by institutions like Stanford and Queen's University, and many others. Sa11y was also adapted by John Jameson from Princeton University, which is available as a turnkey Drupal plugin called Editoria11y.


When it comes to managing accessibility in a large organization or team, it requires distributing responsibilities. Sa11y highlights content related accessibility issues that should be fixed by content authors. For example, a developer should not be responsible for adding alternative text to an image uploaded by a content author. Likewise, a content author shouldn't be responsible for figuring out how to develop an accessible mega menu. Sa11y was designed for content authors, not developers. Divide and conquer.

Creating an inclusive experience requires intention. Content authors should have the ability to easily review their work. For example, Sa11y does not only flag images missing alternative text, but content authors can also easily review the alternative text on other images for relevance and quality. Sa11y also has several test conditions to ensure alternative text follows best practices, including a warning prompt when an image is used as a link.

Creating an inclusive experience goes beyond technical accessibility. An accessibility checker for content authors should be able to be easily customized and extend its rulesets beyond technical accessibility. Developers can easily create custom rulesets to deter content authors from following bad practices or promote better usability. For example, flag server-validated forms nested within accordion components as errors. Endless possibilities and rulesets. View some examples of custom checks.

Content authors should not have to decipher what is and what is not an issue. Interpreting mistaken results or false positives is not only frustrating, but can be timely and costly. An accessibility checker for content authors should be intuitive, actionable and have scope. Sa11y complements templated environments where web components are standardized. Check the editable area only and turn off checks that are not relevant to limit the scope. If they can't fix it, don't flag it.

An accessibility checker should provide actionable information and not leave content authors in doubt. Sa11y does not only flag errors, but also highlights successes. Sometimes people need a "thumbs up" to let them know they are on the right track. Instill confidence in people who may not be technical or familiar with accessibility concepts. Sa11y has three states: error, warning, and pass. A passing state provides content authors with positive reinforcement, or a small way of acknowledging their efforts.


Have feedback, a bug to report, or a testimonial? Share your response on this feedback form or send me an email: adam@chaboryk.xyz