Improve the accessibility of focus outlines

Created on 13 February 2025, 2 months ago

There are several problems in the context of focus outlines in Gin:

Many visible focus colors don’t meet the minimum color contrast of 3:1 in light and dark mode. See the following Google sheet https://docs.google.com/spreadsheets/d/1won35PxhRFexJYE8FmZ4DCNTo7xEAxC8... or focus_outlines.xlsx.zip → for a table.

The focus outline is defined by box-shadow: 0 0 0 1px var(--gin-color-focus-border),0 0 0 4px var(--gin-color-focus) - in addition to that for some selectors the outline property is set to none (gin.css in line 994 and 3466). Problem is, focus outlines defined by the box-shadow property are not visible in Forced Colors mode (see https://stackoverflow.com/a/52616313 - looks like Claro uses the same approach @andrewmacpherson proposed in the linked post)

The one pixel wide focus border is barely visible and it looks more like a visual glitch than a stylistic device helping to visually separate the focus outline from the element it highlights. At the moment that focus border only helps to make the focus outline pass formally SC1.4.11 for most of the focus and accent colors in light mode, even though it is barely visible and not the selected focus or accent color but just semi-transparent black in light and dark mode instead.

There is the problem of simultaneous contrast, at the moment the focus outline is directly "touching" the elements it highlights, while Claro is employing an outline offset. An offset isn’t solving the problem of the simultaneous contrast, but it is at least easing it. To illustrate the problem, if you set for example the focus color to "gin focus color (Default)" and the accent color to “Gin blue” in light mode and you focus the blue Drupal logo in the navigation sidebar or the primary button you have a hard time recognizing that the elements are in focus, since the color of the focus outline and the element in focus are close.

Discussed and iterated on the issue with @mgifford, @the_g_bomb, @katannshaw, and @drupa11y

Go to admin/appearance/settings/gin and test the different focus and accent color settings directly on the page. For testing the issue in Forced Colors mode make sure that before activating you’ve switched to dark mode.

The group had a consensus about the following steps to improve the current state:

All focus colors need to have a color contrast of at least 3:1, accent colors have to have to have a color contrast of at least 4.5:1 (see [#Primary and secondary buttons])
Drop the focus border and just use a single colored focus outline like Claro, that way the focus outline would even be compliant with SC2.4.13 as well.
Use the pattern with the transparent outline that is used in Claro to fix the invisible focus outlines in Forced Colors mode (see https://stackoverflow.com/a/52616313)
Add an offset to the focus outline, to ease the problem with simultaneous contrast.