False Axe contrast failures due to CSS animations (color transitions)

[gabalafou]

Running the accessibility tests (nox -s a11y) produces some false contrast failures.

They are the result of running Axe (the automated accessibility checker script) on the page before certain color transitions have finished. This means that Axe measures the text color against the background while those colors are changing, before they have settled into their final state.

These failures all occur in dark mode because the color animation only happens when toggling the page from one theme to another, whether from light to dark, or dark to light. But I believe the page loads in light mode by default, which is why we don't see these false contrast failures in light mode: because in those cases, the test script toggles the page from light mode (default) to light mode, therefore there is no transition from one set of colors to another and therefore no animation of that transition.

The following PR fixes the issue for one page (Kitchen Sink Admonitions):

• Do not animate the version admonitions colors. #1424

But we need to decide whether we want to get rid of these light-dark mode transitions, or wait for them to finish in the testing script.

The first task in this issue is therefore to:

• Determine all of the remaining places that have a light-dark transition

[drammock]

IMO we should either "lean in" to the light/dark transitions so that all page elements do it, or remove them all. If we lean in, then we can add a short sleep to the test to let the transitions settle down before Axe assesses the page. But I'm guessing that nobody wants to / has time to do the work to add transitions to everything even though it might be nice?

[12rambau]

I'm not a big fan of the night/light transitions TBH

[gabalafou]

I found one light-dark transition via a codebase search for "transition":

• Read the Docs version switcher, which appears in the lower left of the docs site

All the other transitions apply on hover, not when toggling light/dark mode.

However, the CSS transition for Read the Docs switcher seems to only apply in stable version of the docs not the latest version.

Another method I used to find light-dark transitions on elements was to toggle a PST docs page rapidly between light and dark modes, and watch the page for elements whose color changed slower than the rest of the page:

• The version switcher button (top left)
• The search box (top right)

These transitions are inherited from Bootstrap. This means that anywhere we use Bootstrap to style buttons (via the btn class), and use color variables for those buttons that have light and dark variants (such as var(--pst-color-border)), then we will get a timed color transition when toggling light to dark or dark to light mode.

[gabalafou]

My hunch is that the reason Bootstrap defines color transitions on these elements has nothing to do with animating the color change when switching light-dark modes, but probably to ensure that other state changes, such as on hover, are animated. In fact, if you take a look at the Bootstrap buttons docs page and toggle light-dark theme, you will notice that the button colors stay the same in both light and dark themes.

I'm not sure why there's a color transition on the RTD switcher though. @12rambau, looks like you added it?

[gabalafou]

Anyway, I don't see an easy way of eliminating all of the light-dark transitions on the site. I would have to comb through all of the places that Bootstrap defines color animations and then override them on our site, which would probably mess up hover animations and other stuff.

So I think the route forward for the accessibility tests is to either figure out a way to tell Playwright to wait for animations on the page to finish or pause each test function for something like 300ms before running the Axe script.

[12rambau]

I'm not sure why there's a color transition on the RTD switcher though. @12rambau, looks like you added it?

Looks like a copy/paste to me ! you can drop it I won't be sad 😄

[drammock]

• The version switcher button (top left)
• The search box (top right)

These transitions are inherited from Bootstrap [...] anywhere we use Bootstrap to style buttons (via the btn class), and use color variables for those buttons that have light and dark variants [...] we will get a timed color transition

So, if the source is Bootstrap's btn class, can't we add our own CSS rule for btn that overrides just the transition and leaves the rest of the styling alone?

[trallard]

I think, for now, the immediate action would be to add some wait time to the Playwright tests to account for the transitions.

Anyway, I don't see an easy way of eliminating all of the light-dark transitions on the site. I would have to comb through all of the places that Bootstrap defines color animations and then override them on our site,

I am not sure how much of an effort this would be but something tells me this can add up to quite a lot of time/effort and considering that we have a lot of accessibility-related issues to work on atm I'd prefer to prioritise these vs. the transition changes at least short-term