Pico-SDK use of Red Text on Pure Black Background Strains Eyes

[drankinatty]

The dark theme for the pico-sdk documentation is much appreciated, but it has some rough-edges.

In the pico-sdk, the web page uses a dark-red-text on black background that is very hard on the eyes. This isn't a major issue, but is something that would be very helpful to address and correct -- especially for older eyes.

I'm not a web designer, but have done a lot of dark-theme UI design. The choice of complementary colors that provide proper contrast for readability is crucial. There are a couple of axioms that the current colors used by the pico-sdk violate:

1. never use dark text on dark backgrounds, (dark refers to the color-character, where, e.g. red is a "dark" color, while yellow is a "light" color);
2. never use pure black for text or backgrounds (e.g. #000000).

The current pico-sdk violates both. Here is a screenshot from the multicore - fifo documentation:

You can alter the red (or any "dark" color) by reducing the saturation to improve contrast (e.g. #FF6464), but with red that usually ends up looking a bit pinkish or orange, but is still much easier on the eyes than a dark red on black. Cyans work exceptionally well on a "close to black" background (something around #53C6FF) as do faux ambers (like #FFEAB0).

As far as replacing the pure black background with something close to pure black, a black desaturated cyan works really well to eliminate eye-strain. Anything in the range of #070A10 to #18191D works really well. You can even get by with a bit lighter and you can tweak the desaturated offset color to suit your taste. Text renders cleaner on something that isn't pure black and your eyes with thank you. (this github page uses #0D1117 which works fine)

Again, not a major issue, but something very easily corrected by changing a couple of color-codes. Then people would have no excuse for not RTFM...

If this isn't the proper place for this issue, just let me know and I'm happy to migrate it to wherever is proper. I looked at the raspberrypi/documentation repo, but that didn't seem like the right place for pico-sdk doc issues.

[lurch]

I'm not a web designer,

Me neither. Ping @mudge and @clowder 🙂

If this isn't the proper place for this issue, just let me know and I'm happy to migrate it to wherever is proper. I looked at the raspberrypi/documentation repo, but that didn't seem like the right place for pico-sdk doc issues.

pico-sdk would be the right place for issues with the doxygen content (typos, missing functions, etc.), but documentation is the right place for discussions around the styling and layout of https://www.raspberrypi.com/documentation/pico-sdk/ (e.g. see also #4063 ).

[mudge]

The red mentioned is coming from the colour of links, see https://github.com/raspberrypi/documentation/blob/a08e5b988ce3a130c2693490f99a6df24a10c646/jekyll-assets/css/style.css#L109

Please note this uses a CSS variable (--accent) that varies between #cd2355 for light (the default) and #d75a64 for dark mode. You can also see the other variables used and their light and dark versions if you want to experiment with a higher contrast palette.

[drankinatty]

Thanks! I'll do that. I should have time in the next day or two to put a local copy of the docs on my server and I'll play with the css. If I end up with something I'm happy with, I'll post a diff of the files for others to evaluate.

Another issues I didn't catch in the first screenshot is the mixing of the reds you mention for "NOTE:" boxes next to the darker red for the function (link) names. Where this occurs, your eyes are drawn to the lighter red of the NOTE (and bright box outline) making the links appear even darker.

Here is an example of the same multicore fifo with the NOTE box included:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[drankinatty]

My apologies. We have had kids weddings and I've not had a chance to look for better combinations in the source yet. It's an issue worth fixing.