Add new dark link option and improve inverted link accessibility documentation

[bartaz]

As discussed in comments under https://github.com/canonical/vanilla-framework/issues/3350#issuecomment-1072448352 we need to improve how we handle links on dark backgrounds:

• introduce new class name for links on dark background (with new lighter blue colour)
• update current "inverted" link to show an underline (possibly rename it)
• update documentation to describe when to use new dark link and when to use "inverted" link

[lyubomir-popov]

I just filed a separate issue, maybe close one of them and consolidate the info in the remaining one?

---

Edit: Comment from that issue:

I'm revisiting the problem of accessible link colours for dark backgrounds again. To pass WCAG 2.0 rules about contrast against surrounding text, we are forced to use a colour that is difficult to read. Unless we decide it ok to fail the WCAG reqs to improve readability, I would suggest sticking to that for now. Here are the values, can we please make them available in the framework?:

For reference, Here's a related working group discussion prpoising a change to the inverted link documentation, and the addition of an .is-dark class.

We will discuss this in the Accessibility guild and hopefully reach a conclusion whether we can afford to breach the outdated (but still in force) WCAG requirements, which is something most other sites do - including github and google chrome's settings pages for example.

For what it's worth, following thenew APCA recommendations is also not ideal, because links become almost indistinguishable from white text, thereby failing the https://www.w3.org/WAI/WCAG21/Techniques/general/G183 technique.

[bartaz]

Thanks @lyubomir-popov, I closed the other one and moved your comment here.

[bartaz]

In the dark theme make links underlined.

Inverted link (white underlined) is supposed to be only used on dark backgrounds we can't control (images)?

Blue underlined link is for solid dark backgrounds (new class for that).

[juanruitina]

We have received feedback from a colleague that contrast is too low on dark theme links on canonical.com; I had the same perception, particularly on my years-old screen and in bright environments. Given contrast is heavily perceptual, users' perceptions should be taken into consideration.

The WCAG algorithm is known to throw false positives in many instances and for blues in particular (one source), because blue has low luminance. As @lyubomir-popov mentioned already, the combination fails the APCA algorithm (blue on graphite, purple on graphite), particularly given the very thin font weight we are using.

For context, here's Github's own discussion around the topic. They agree it's a tough one. I agree that "Visual task of differentiation is not all the same as the visual task of fluent readability" (a comment by the way made by the proponent of the APCA algorithm). It is a tradeoff, and I am on the side of ensuring readability, as differentiation can be achieved in other ways (e.g. positioning, underlining).

I acknowledge this is difficult to address, as we might need to choose between compliance and actual accessibility; this is something we have discussed a few times already. But wanted to document this nonetheless.

Some more reads:

• https://github.com/w3c/low-vision-a11y-tf/issues/84
• NASA research on designing with blue

[juanruitina]

Following on the conversation on Mattermost with @lyubomir-popov, I'm doing some more explorations on Figma, also comparing with how VS Code and GitHub handle this. VS Code combination clearly fails the 3:1 contrast ratio with surrounding text, still seems to strike a good balance between readability and making links distinct. (Fun fact: I checked this by using the web version of VS Code, so that's by all means subject to WCAG compliance :D)

I acknowledge that 3:1 contrast requirement with surrounding text is important, and I understand we don't want to use underlining for every link. I get it, can get a page such as the home visually heavy. But there are alternatives.

In many cases, links are already followed by a chevron to convey they are, indeed, links. Another low-risk mitigation we could explore is leveraging the prefers-contrast media query, to be extra careful with users that have set high contrast on their device's accessibility settings. For instance, we could add underlines to all links only in those cases:

@media (prefers-contrast: more) {
  .is-graphite .inner-wrapper a:not([class^=p-button]), .is-dark .inner-wrapper a:not([class^=p-button]) {
      text-decoration: underline;
      text-decoration-thickness: 1px;
      /* perhaps with some offset so it looks better: */
      text-underline-offset: 0.2em;
  }

  .is-graphite .inner-wrapper a:not([class^=p-button]):hover, .is-dark .inner-wrapper a:not([class^=p-button]):hover {
      text-decoration-thickness: 2px;
  }
}

With chevrons or underlines, the 3:1 contrast is no longer needed, because function is already conveyed visually.

I'd personally feel inclined to use a lighter, crisper tone of blue such as #79BCF9(mine) or #4DAAFC (VS Code's), and use the mitigations above when possible. True, we might not be fully compliant with the letter of the standard, but we would be addressing real accessibility concerns flagged up by real users, and in line with the feedback others are getting.

[lyubomir-popov]

@juanruitina can you clarify APCA's stance on contrast with surrounding text? we need to define what qualifies as "accessible" against both adjacent text and background. If we decide we want to switch to APCA compliance, that's fine, but let's understand what that means.

I guess we need to agree - if we achieve APCA "spot text" level, does that qualify in APCA's interpretation

some more benchmarking from me, with generic colours from vscode and elsewhere where dark themes are mature (e.g. chrome settings) https://www.figma.com/file/H6MSsN3taoXXOJCPUbIImQ/Design-System-Library?type=design&node-id=7476%3A14558&mode=design&t=vmdB3pGXQE5wbpV1-1

(note vscode's background is darker, giving them more clearance)

because there are shades that provide spot color against both our background 262626 and adjacent text white, for example:

[juanruitina]

I really think we should keep WCAG 2 as our main reference. But we can decide to make some (well documented) exceptions when we have strong evidence (feedback, benchmarking, research, in this case APCA) of the standard being insufficient.

I couldn't find any info about adjacent text and APCA. The APCA author has opinions; I agree with him, but I won't claim that's a standard. In any case, I think APCA as a tool proves that a contrast triangle with a blue link colour, a dark background and white adjacent text that is both WCAG 2 compliant and genuinely accessible is a chimera because of the low perceptual luminance of blue that the WCAG 2 algorithm fails to acknowledge. The benchmarking we are doing now proves major companies are finding those issues and making compromises: "compliant" != accessible. (BTW, "spot text" seems to refer to disabled, placeholder, ancillary, decorative text)

It's interesting to see Google Search also going for lighter, readable shades in the dark theme (#99c3ff, #c58af9), even with adjacent text, failing the 3:1 requirement (just 1.48:1 contrast!):

In line with what I see VS Code and Google doing, I'm suggesting to prioritise link colours that pass WCAG 2 and get relatively better scores for APCA on background, and have acceptable contrast with adjacent text that doesn't compromise the former, even if that strictly means failing the 3:1 requirement. No colour combination will pass both on APCA. VS Code link colour #4DAAFC is particularly balanced, with a value of ~50 Lc with both white and dark background. Contrast with adjacent text is not terrible either (2.48:1). Although I would personally opt for going slightly higher on the contrast with the background, in line with Google's approach.

Ah, fascinating challenge.

[juanruitina]

I'm putting together a spec collecting all the evidence.