tech-docs Legibility and Readability Issues with Dark Mode Themes

Operating System: macOS Ventura 13.5 Browsers: Safari 17, Chrome 115, Firefox 116

When viewing the documentation using the Ayu, Coal, and Navy dark mode themes, some of the labels in images that have text in a space with a transparent background are unreadable, and the contrast. Also, the widgets and header text color are not very readable with the Coal, Navy, and Ayu themes, plus the body font color for Coal is too low-contrast to be legible.

I have included screenshots for the three dark mode themes and screenshots for the Rust theme for contrast (pun intended).

Theme: Ayu System76 Docs Ayu 1 System76 Docs Ayu 2

Theme: Coal System76 Docs Coal 1 System76 Docs Coal 2

Theme: Navy System76 Docs Navy 1 System76 Docs Navy 2

Theme: Rust System76 Docs Rust 1 System76 Docs Rust 2

Aug 15 '23 23:08 questionlp

For desktops, having more padding in the photo for the text to sit on doesn't make too much of a difference, but for laptops (which use professional photos with transparent backgrounds), scrapping the transparency would be a matter of making them look a lot worse in the default light theme in order to cater to the dark themes:

I've tried using orange or light blue text that's readable in both light and dark themes instead of the dark blue, although again, that hurts the contrast in the default light theme. This is orange text on https://tech-docs.system76.com/models/thelio-major-r3/external-overview.html:

And light blue text on https://tech-docs.system76.com/models/addw3/external-overview.html:

Maybe I can edit the themes so just the dark themes put a background color behind the images. We still want to avoid that for the product hero images on the spec pages, though. Using some kind of image class so we can specify which images need a background in the dark themes would work, if that's possible in mdbook.

Aug 16 '23 03:08 jacobgkau

I'm not sure if mdbook supports this or not, but maybe adding a fragment to the images that need a special background in dark mode themes and adding the necessary CSS to support it:

Markdown:

![Front & Back Views](./img/external-front-back.webp#bg)

CSS:

img[src~="#bg"] {
   background-color: white;
}

Aug 16 '23 03:08 questionlp

Forgot to mention that you can use CSS prefers-color-scheme to set specific styles for either light or dark mode:

@media (prefers-color-scheme: light) {
  /* Light mode styles */
}

@media (prefers-color-scheme: dark) {
  /* Dark mode styles */
}

It is generally supported in most modern browsers per MDN: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme#

Aug 16 '23 03:08 questionlp