search

python / python-docs-theme

Sphinx theme for Python documentation
Other
75 stars 58 forks source link

Dark mode: fix contrast for C++ specific styling #133

Closed hugovk closed 1 year ago

hugovk commented 1 year ago

Before

  1. Visit https://docs.python.org/3.12/c-api/arg.html#numbers
  2. Look at the C keywords such as unsigned char
  1. Dark mode: the dark blue text on dark background is very hard to read
  2. Check the contrast ratio in devtools, it's below the WCAG AA guidelines of 4.5:

image

  1. (Light mode is fine, ratio is 9.88, above the AAA ratio of 7.0.)

After

That is defined by Sphinx: https://github.com/sphinx-doc/sphinx/blob/d3c91f951255c6729a53e38c895ddc0af036b5b9/sphinx/themes/basic/static/basic.css_t#L547-L550

Copy that CSS to our dark mode file and use #5283ff as suggested by devtools, and the dark mode is improved, with no change to light mode:

Preview

https://python-docs-theme-previews--133.org.readthedocs.build/en/133/c-api/arg.html#numbers

hugovk commented 1 year ago

This will also fix some of the Lighthouse Accessibility audits findings.

Before

image

After

image

sorcio commented 1 year ago

Just a quick comment since this PR has been pointed out to me. I'm not an expert though, so I'll just add a note to the best of my understanding.

Firefox DevTools uses WCAG 2 recommendations. WCAG 3 is still a draft, but it introduces a new model for contrast (APCA) because the previous one has issues. In particular, it's not sensitive to font size and polarity (background vs foreground).

According to the APCA calculator for web colors, the new color doesn't have sufficient contrast against the dark mode background at the given font size, for text reading. Mind, to me it's perfectly readable and a huge improvement over the previous color. It could be that to other users it's not the best.

A more contrasting color with a similar chromaticity might be, only as an example (I have no preference), #8ab7ff. Note that the chromaticity of the currently proposed color cannot be preserved within sRGB (it already saturates the blue channel). Probably not important but, given I'm commenting on something I have no context about, I wanted to be specific :)

Of course this is not about this specific color choice! Possibly the whole theme could benefit from these considerations. But I've been summoned on this PR and maybe this is interesting to @hugovk since you're doing work on this :)

hugovk commented 1 year ago

Thanks for bringing it to my attention, I'd not heard of APCA before.

There's an interesting discussion about it at https://github.com/jupyter/accessibility/issues/65 which also shares this article: https://kilianvalkhof.com/2021/accessibility/wcag-2-is-what-we-have/

Those conclusions seems reasonable: WCAG 2 is a standard agreed through consensus. WCAG 3 is still a draft, and is likely many years from consensus and approval. The consensus is important, it shows there's wide support, consistency, and can be broadly applied. WCAG 2 AA should be used as a baseline.

For example, the EU's Web Accessibility Directive references WCAG 2.1 at level AA.

(Lots more detail: https://digital-strategy.ec.europa.eu/en/policies/web-accessibility-directive-standards-and-harmonisation)

(And WCAG 2 is consistently identified and upheld for the Americans with Disabilities Act https://www.boia.org/blog/is-there-a-legal-requirement-to-implement-wcag)

Level AAA includes AA, and W3C say of AAA:

It is not recommended that Level AAA conformance be required as a general policy for entire sites because it is not possible to satisfy all Level AAA Success Criteria for some content.

AAA is a very high bar and often seen as requiring too much of a change to a design, compared with AA. I usually check the AAA colours too, but often they're a bit too much washed out, so stick with AA.

So I think using WCAG 2.1 AA should be seen as a baseline, and we can of course do better than this where appropriate.

As it happens, the suggested #8ab7ff is also what Chrome suggests for AAA:

image

Here's a comparison of the three options:

Original: 1.6 AA: 4.59 AAA: 7.09
image image image

There's definitely a big improvement from the original -> AA.

The AAA seems a bit on the light side compared to AA, but I guess it's not too bad?

It's fairly similar to the #77aaff used for Py_ssize_t, bytes and bytearray at the bottom of the screen (which has ratio of 6.8, just below AAA).

What do you think?

sorcio commented 1 year ago

The discussion over at Jupyter Accessibility is quite insightful, thanks for linking to it. And I agree that aiming for 100% APCA conformance restricts design choices to an unclear end (maybe it will get better in the future if extended gamut becomes more available).

Just some points:

So, without going for APCA, maybe a good practice could be to overshoot contrast a little bit for small text and for dark mode? E.g. something between the boundaries for AA and AAA.

I have no suggestion for the color in this PR :) I'm a fan of the change in any case, and my graphic design intuition is poor. At first glance, the increased contrast makes the text easier on my eyes. I have no clue if it's important to be able tell apart this blue from other types of blue text in the same page, so maybe that's another factor.

All this said, I don't want to stall this PR with irrelevant discussion, so let's move it elsewhere (and involve someone more competent than me) if it's still interesting.

hugovk commented 1 year ago

Thanks for the discussion! Let's go with this, and further improvements welcome.

Myndex commented 1 year ago

Hi @hugovk and @sorcio

Under WCAG 2.x, If you have one color theme that is compliant, any number of other color schemes may use alternate rules, provided there is a means for the user to switch them.

This is important for dark mode, as WCAG 2 can not calculate for dark mode.

APCA can calculate for dark mode—regarding sorcio's comment:

...lower contrast can be desirable by users of dark themes...

Yes, in dark environments dark mode with an overall dark screen and in a dark room or at night, can use a different contrast. At the moment this is not in the draft guidelines, which are based on the more difficult case of a brightly it ambient.

There are some unreleased versions of APCA with multiple color inputs for this purpose.

APCA exceeds WCAG 2.x in actual accessibility, though there are some edge cases where there is no backwards compatibility, due to the fact that WCAG 2.x is substantially incorrect in calculating dark color pairs.

ALSO, there is a drop in replacement for WCAG 2 that is fully backwards compatible, but using APCA technology, called BridgePCA, see bridgepca.com