Sa11y 4.0

As a tool designed for content authors, Sa11y 4 aims to simplify accessibility checking by clearly distinguishing between content author checks and those intended for developers.

Simplified settings panel

The main check now includes Contrast checking and Links (Advanced) by default, while more developer-focused checks—such as Form labels, missing page language, and title—are grouped under a new Developer checks toggle.

Colour tools and suggestions for contrast checks

Sa11y will suggest a new colour as close as possible to your original, offering a quick fix. For normal text, it suggests a colour that meets a contrast ratio of 4.5:1 or higher, and for large text, 3:1 or higher.

You can also use color pickers to find another color. This feature relies on the browser's built-in color picker, which may vary slightly in appearance across different browsers and operating systems.

Contrast checks for simple SVGs (developer check)

Simple SVGs that only contain a single <path> can automatically be checked for non-text contrast. All other SVGs will receive a warning.

More dismissal options

On pages with many issues, seeing numerous annotations can be overwhelming, particularly when working on a page that's still being developed. You can now:

• Dismiss “Good” annotations.
• “Dismiss all” some checks. This will temporarily turn off that check for the current page. Only some checks have a “Dismiss all” button:
  • Links that open in a new tab or window without warning.
  • Warnings for items whose contrast can’t be programmatically determined.
  • Links that have identical text as another link, although it points to a different page.
  • Links to PDF documents.

New content author checks

New content author warnings for:

• Justify-aligned text.
• Text that is too small or less than 10px or 7.5pt.
• Nested interactive layout components.
• Decorative images with an image carousel should have alt text.
• Skipped heading check will now suggest the appropriate heading.
• Link’s title attribute is the same as the link text.
• Image’s title attribute is the same as the alt text.
• Links with non-descript text will receive a warning, regardless of aria-label.

Please note, these additional checks are not WCAG criterions but are aligned with best practices.

Expanded test coverage for developers

Sa11y isn't designed to replace comprehensive automated tools, but to complement them. Sa11y still doesn't check for complex developer issues like proper ARIA implementation. Although as the library continues to steadily grow, so does the responsibility to maintain a balance between test coverage and simplicity for content authors. There are several new developer-oriented warnings and errors:

• Zooming and scaling is not disabled.
• Page does not automatically refresh.
• Buttons have accessible names.
• Buttons must have its visible label as part of its accessible name.
• Button does not have the word “button” as part of its accessible name.
• List items not contained within a <ul> or <ol>.
• Tabindex attributes greater than 0.
• Disappearing placeholder text for form fields.
• Contrast of an input’s placeholder.
• Contrast of simple SVG elements (where there is only one <path> or a single colour). A general warning for all other SVG elements.
• Links with accessible names defined via ARIA may still be flagged as a warning if their visible text is vague or meaningless, such as “click here.”

Additional properties to support custom implementations

Any check can be individually turned off or customized upon instantiation. You can now easily change a:

• Tooltip’s message.
• Classification as a warning or error.
• Classification as a “Developer check”.
• Give “Dismiss all” ability to a check.

Some props have been deprecated or replaced in favor of a more organized approach to customizing checks. For example, all properties relating to checks are organized within a “checks” object.

const sa11y = new Sa11y({
  checkRoot: "main",
  checks: {
        IMAGE_DECORATIVE_CAROUSEL: {
          type: 'error',
          sources: '.slideshow',
        },
        TABLES_EMPTY_HEADING: {
          type: 'warning',
        }
   },
});

For more information, please see props & methods.

Developer related updates and bug fixes

• Minimize false positives for error regarding broken in-page links.
• Minor visual changes to make tooltips within Sa11y’s control panel more visible.
  • Sa11y’s interface now adheres to both WCAG 2.0 and APCA contrast algorithms.
  • Tooltips within Sa11y’s panel have better contrast in dark mode.
• If the alt text within a tooltip exceeds 600 characters, it will be truncated.
• Issue preview in Sa11y’s control panel:
  • Truncated after 600 characters.
  • Displays clickable links instead of an HTML preview.
  • Incorporates improved sanitization for safer output.
  • Displays correct colour for error or warning badge.
• Minimized number of DOM queries for performance.
• Images with alt text within a button will not receive a “Good” annotation.
• Tables that are explicitly hidden (e.g. style=“display:none”) will be ignored.
• Minimize false positives for error regarding links with the same name but different destination.
• Extend missing label checks for <meter> and <progress> elements.
• Warning correctly displays when target=“_BLANK” in uppercase text.
• Semantic list will now visually render in the “Preview” area of the control panel.
• Improvements to “Image” panel, where image’s with a “srcset” attribute or <source srcset> will take priority.
• Dismissal keys across all checks are now more unique, ensuring only the intended dismissed check is affected without impacting other warnings for the same element.
• Resolved an issue in the Images panel where the "warning" indicator would persist even after being dismissed.
• <abbr> elements will not get flagged as a warning for underlined text.
• Flagged elements will no longer have a red or yellow background color, only an outline. This adjustment ensures contrast errors are consistently reported.
• Accessible name computation support for slot elements.
• “No headings found” message will now correctly appear again in the Outline tab.

Improvements to contrast checks

• Supports transparency and alpha blending for foreground and background colours.
• Newly supported colour spaces: HSL, HSLA, LCH, Lab, OkLab, OKLCH, HWB.
  • Note: These colors are supported by using a technique where the browser converts the color by rendering it on a <canvas> element and extracting the resulting RGB values, offering similar accuracy to third-party colour libraries.
  • Note: The following colour spaces are not supported and will prompt a manual warning: Rec. 2020 and DisplayP3.
• Contrast ratios of exactly 1:1 will not be flagged as an error, assuming text was intentionally made visually hidden.
• Elements that are explicitly hidden (e.g. style=“display:none”) will be ignored by contrast check.
• If adjacent nodes share the same colour and background image, only a single warning will be pushed.
• Warning for SVGs that have <text> elements.

APCA support (beta)

Advanced Perceptual Contrast Algorithm (APCA) is a new colour contrast model that is based on colour perception. In addition to lightness/darkness contrast, it also considers font size and weight.

Developers or administrators can enable the APCA algorithm by setting contrastAPCA to true.

APCA colour suggestions

Sa11y takes into consideration font size and weight when providing advice. Sa11y will either:

• Suggest a new colour that has sufficient contrast.
• Suggest both a new font size and colour if the colour combination will not be accessible at any size.

Disclaimer

APCA is the candidate contrast method for WCAG 3, but it is still in beta. WCAG 3 is still in development and subject to change. The APCA model should not be used for WCAG 2 conformance.

Acknowledgments

• Toronto Metropolitan University computer science student’s Michael Nesci and Rishabh Seth for their code contributions, testing, and bug reports.
• John Jameson for the suggestion to add colour suggestions to contrast checking.
  • P.S. Check out Editoria11y 2.3 for real-time accessibility “spell check”
• APCA was created by Andrew Somers. Sa11y utilizes the apca-w3 library as a dependency for APCA calculation and font lookup tables.
• Greg Gay for suggesting a new warning: Links with accessible names defined via ARIA may still be flagged if their visible text is vague or meaningless, such as “click here.” (Issue #98)

Feedback and bug reports

Please provide feedback or report issues via GitHub or Google Forms!