Editoria11y Accessibility Checker

Editoria11y (“editorial accessibility ally”) is a quality assurance tool built for an author’s workflow:

1. It provides instant feedback in the post and page editors. Authors do not need to remember to press a button or visit a dashboard to check their work.
2. It checks in context on pages, not just within the post editor, allowing it to test content edited in widgets or theme features.
3. It focuses exclusively on content issues: assisting authors at improving the things that are their responsibility.

This plugin is the WordPress adaptation of the open-source Editoria11y library. Tests run in the browser and findings are stored in your own database; nothing is sent to any third party. It is meant to supplement, not replace, testing your code and visual design with developer-focused tools and testing practices.

The authoring experience

Check out a demo of the checker itself.

• When logged-in authors and editors are viewing pages, Editoria11y inserts tooltips marking any issues present on the current page. Issues are also highlighted while editing in the Block Editor (Gutenberg) and Classic Editor (TinyMCE).
• Tooltips explain each problem and what actions are needed to resolve it. Some issues are “manual checks,” which have buttons to ignore the check or mark the content as OK.
• Clicking the main toggle shows and hides the tooltips.
• The main toggle also allows authors to jump to the next issue, restore previously dismissed alerts, visualize text alternatives for images on the page (“alts”), view the document’s heading outline, and view site-wide detection lists.

The admin experience

• Filterable reports let you explore recent issues, which pages have the most issues, which issues are most common, and which issues have been dismissed. These populate and update when published content is viewed by logged-in authors.
• Various settings are available to constrain checks to specific parts of the page and tweak the sensitivity of several tests.

The tests

• Text alternatives for visual content
  • Images with no alt text
  • Images with a filename as alt text
  • Images with very long alt text
  • Images with fake alt text to get around field validation (e.g. “TBD”)
  • Alt text that contains redundant text like “image of” or “photo of”
  • Images in links with alt text that appears to be describing the image instead of the link destination
  • Embedded visualizations that usually require a text alternative
• Meaningful links
  • Links with no text
  • Links titled with a filename
  • Links only titled with generic text: “click here,” “learn more,” “download,” etc.
  • Links that open in a new window without warning
• Document outline and structure
  • Skipped heading levels
  • Empty headings
  • Very long headings
  • Suspiciously short blockquotes that may actually be headings
  • All-bold paragraphs with no punctuation that may actually be headings
  • Suspicious formatting that should probably be converted to a list (sequences of sentences that start with asterisks, emoji or incrementing numbers/letters)
  • Tables without headers
  • Empty table header cells
  • Tables with document headers (“Header 3”) instead of table headers
• General quality assurance
  • LARGE QUANTITIES OF CAPS LOCK TEXT
  • Links to PDFs and other documents, reminding the user to test the download for accessibility or provide an alternate, accessible format
  • Video embeds, reminding the user to add closed captions
  • Audio embeds, reminding the user to provide a transcript
  • Social media embeds, reminding the user to provide alt attributes
• Custom results provided by your JS

Credit

Editoria11y’s WordPress plugin is maintained by Princeton University’s Web Development Services team:

• John Jameson: Editoria11y JS and CMS integrations
• Jason Partyka: Devops
• Brian Osborne: Code review
• Michael Muzzie: Wapuu photos

Editoria11y began as a fork of the Toronto Metropolitan University’s Sa11y Accessibility Checker, and our teams regularly pass new code and ideas back and forth.

Editoria11y’s default settings will work great for most sites.

Your first task after installation should be clicking through a representative sampling of the main pages of your site. This will start to populate your dashboard report, and give you a chance to look for issues to fix or dismiss.

If you notice anything amiss, experiment with these settings:

1. Pick a “Theme for tooltips” that looks nice with your site’s colors.
2. If the checker is flagging issues that are not relevant to content editors, either use “Check content in these containers” to constrain checks to the parts of the page with editable content, or “Exclude these elements from checks” to skip over certain elements, regions or widgets.
3. Editoria11y also provides an “as-you-type” issue highlighter that works inside the editor. If you find live correction annoying rather than helpful, change “Check while editing content” to unset “always show tips,” or chose “Do not check while editing.”
4. If you do not want PDF or other document types flagged for manual checks, provide a shorter selector list or set “Document types that need manual review” to false
5. If your theme has done something very unusual with its layout, such as setting the height of the content container to 0px, you may see confusing alerts when opening Editoria11y tips saying that the highlighted element may be off-screen or invisible. If that happens, disable “Check if elements are visible when using panel navigation buttons.” This is disabled by defaults on any WordPress themes we have noticed this on, so if you find a theme

If you are a theme developer, note that the library dispatches JavaScript events at several key moments (scan finishes, panel opens, tooltip opens or shuts), allowing you to attach custom functionality. JavaScript on sites running Editoria11y can use these events to do things like automatically opening accordion widgets if they contain hidden alerts, disabling “sticky” site menus if the panel is open, inserting custom results, or syncing results to third-party dashboards.

And then…tell us how it went! This plugin and its base library are both under active development. Ideally send bug reports and feature requests through the GitHub issue queue.

1. 

   Checker with an open "manual check" request, for an image without alt text.

2. 

   The same issue shown while editing the page, this time using the dark theme.

3. 

   The site-wide reporting dashboard.

4. 

   Checker set to dark theme, asking if the whole sentence needs to be in caps lock.

2.1.7

• Adds option on the plugin settings page to select between the library’s various assertiveness levels: start open for any issues, start open for new issues, always start open, start minimized.
• Adds “editoria11y_viewing_params” and “editoria11y_editing_params” filters for developers to modify configuration sent to the browser at runtime.

2.1.5

• Fix for dismissals not saving when editing a page that was not previously tracked. Note that this only syncs if the page already exists in the database; dismissals on the “New Post” or “New Page” screen are only stored temporarily in your browser.

2.1.4

• Fix for text from alerts on headings being included in the heading text in the document outline visualizer.

2.1.3

• Fixes an intermittent false positive on anchor links in the Classic editor.

2.1.2

• Fixes a bug that crashed the Classic editor checker when jumping to a tip on a recently fixed issue.

2.1.1

• Adds an option on the configuration page to hide the shortcut link to the dashboard reports. Hiding it makes the toggle smaller, and the link does not work in all configurations.

2.1.0

• Adds support for live-checking in the Classic editor (TinyMCE). Big thank you to Ricardo at PressBooks for showing me how to pass variables in and out of its iframe!
  No configuration changes are needed for this to work. If you do not want to check inside the classic editor, add a “.mce-edit-area iframe” selector to the “Do not flag these elements” field on the plugin configuration page.
• Switches the position of the flag and number in the checker toggle in response to user feedback.

2.0.12

• Adds custom test for Buttons without links not flagged in the block editor
• Adds images with role=presentation to the default ignore list.
• Fix issue with false positives for links containing both images and text when the link contains space characters.

2.0.11

• Resolves PHP error when image ID is not set.

2.0.10

• Adds dismiss-all buttons when there are several of the same issue type on a page.
• Adds “Edit Media” link to the tooltips for alt text error messages (hat tip cbirdsong).
• Adds auto shadow DOM detection for the frontend checker, and automatically inserts buttons outside shadow host nodes. This is disabled in the as-you-type checker at the moment; reach out if you need it while editing. It adds ~20ms to test runs, so I am waiting to see if somebody actually needs it first, since performance matters much more there.
• Empty first table header cell is now a manual check.
• Name calculation better handles null aria labels, title attributes and pseudoContent.
• Various bugfixes and typo corrections.