How it works

This page explains how Accented works under the hood, why it’s designed the way it is, and what its limitations are.

Design principles#

• Make the highlights stand out, but don’t break the page. It should be obvious to the developer what elements have accessibility issues. At the same time, we should make minimal changes to the DOM to ensure the page still looks and behaves as expected.
• Make it work everywhere. No matter how simple or complex the page is — whether it’s static or highly dynamic, and regardless of the HTML or CSS features used — Accented should work reliably.
• Performance matters. Developers should be able to use Accented without worrying about page slowdown. While some impact is inevitable — since axe-core runs on the main thread — we will provide tools to help measure and optimize performance. (see Improving performance).
• Accessibility matters, too. Accented has a UI of its own, and that has to be accessible. See Accessibility.

Architecture overview#

Accented consists of a few core components.

• The axe-core runner. Accented doesn’t have its own logic for detecting issues — it delegates that to axe-core by calling axe.run().
• The DOM mutation observer. Accented uses a mutation observer to detect changes in the DOM and re-run the axe-core script whenever such changes happen. That way, Accented can find accessibility issues as soon as they are introduced.
• The task queue.
  • Ensures that all mutations are processed correctly, even if they happen in quick succession.
  • Throttles calls to the axe-core script to avoid performance issues.
• The DOM updater. This component is responsible for adding highlights (outlines, dialogs, and dialog trigger buttons) to the DOM and keeping them in sync with the page.

Known limitations#

Accented aims to be as helpful and reliable as possible, but it does have limitations.

• Most importantly, no automated tool can make an application perfectly accessible, and Accented is no exception. Accented helps avoid many issues, but it’s no substitute for manual testing or usability testing with people with disabilities.
• Since Accented modifies the DOM (adding outlines, buttons, and dialogs), it can affect the results of subsequent axe-core runs — possibly causing false positives or false negatives. As you fix issues, these DOM changes are removed, reducing the chance of inaccurate results.
• Not all page changes trigger re-scans. Accented uses a mutation observer to detect changes on the page, but not all changes are mutations. For example, applying a pseudo-class like :hover or :focus, or toggling dark mode, may visually change the page — but won’t trigger a scan.
• Some issue dialogs may not be easy to open. Accented adds a trigger button for each element with accessibility issues, and that button opens the issue dialog. There may be cases, however, when the button is hard or impossible to activate, for example, if the element is inside a container with hidden overflow, or only becomes visible on hover. In such cases, you can still view the issue details in the console.
• Accented is only as good as axe-core at accessibility testing, and axe-core itself may have bugs and flag accessibility issues unreliably. Open an issue with axe-core if you find a bug in it.

Performance#

Accented is designed to minimize performance impact on the host application, but it still runs on the main thread, and some of its operations may still take hundreds of milliseconds (especially on pages with lots of elements).

The most expensive operation is running axe.run() after a DOM mutation.

To make it as fast as possible, Accented only runs axe.run() on the parts of the page that changed.

Accented provides APIs to help you measure and tune its performance.

Throttling#

Calls to axe.run() are throttled, unless you explicitly set wait to 0.

Throttling ensures that if mutations happen frequently in your app, the main thread will still have periods during which the axe-core script is guaranteed not to run. This can help your app stay responsive.

Here’s how it works:

1. Accented is initialized (accented() is called) or a DOM mutation happens.
2. If leading is false, Accented does nothing for wait milliseconds. If leading is true, Accented runs a scan immediately.
3. Axe-core runs its scan, and depending on its findings, Accented may add or remove some outlines and dialog triggers.
4. Accented waits for wait milliseconds after scanning and page updates are complete.
5. If there have been other mutations during the scan or the wait time, Accented goes back to step 3.

No matter how many mutations occurred during the previous scan or the wait period, the current scan accounts for all of them. This guarantees that the issues are always up to date, with a maximum delay of the wait time + the scan time.