Accessibility (& style): add dark mode toggleable w/ light mode

[sadielbartholomew]

Issue stemming from the CF Workshop 25 Hackathon session '(Digital) accessibility of the CF Convention document' (see also #606). As chair of the session, I want to capture our agreed goals in formal Issues to track progress.

Title

Accessibility (& style): add dark mode toggle-able with existing light mode

Moderator

n/a or TBC - likely not needed as this is an infrastructure change, and not controversial?

Moderator Status Review [last updated: YYYY-MM-DD]

n/a or TBC

Requirement Summary

Define and make available, in a way where it can be toggled on/off as an alternative to the existing light mode theme, a 'dark mode' theme - one with light text on a dark background as opposed to vice versa - for any documents in HTML build form of relevance to CF (notably the main/canonical and conformance documents) and ideally also for the website, too - or at very least in terms of the website, for the listings/tables of the controlled vocabularies in HTML/webpage format, which also define the metadata standard itself as opposed to providing context/detail.

I have prepared a PR as a proof of concept which implements and showcases a configurable (by toggle button) dark mode for the HTML build of the canonical document (specifically, just the latest/v1.13 draft build and not previous documents). This could be merged as-is but note a comprehensive solution would also have the same, or similar, for the other documents, and a website solution would also be required.

Technical Proposal Summary

The CF Conventions documents (main, conformance, etc.) are built to HTML (i.e. webpage view in a browser) and to PDF, viewable in either format. Both formats are built by AsciiDoc (in the latter case, AsciiDoc PDF) which builds them in a set theme - in the PDF case only we customise this with a YAML form stylesheet, but for the HTML build we don't customise theming so that the theme the HTML documents are rendered to is the default for AsciiDoc. Notably this is a light mode - dark text on a light background.

We advocate for the addition of an alternative theme in the form of a 'dark mode' - light text on a dark background, with benefits outlined in the section below, notably improving digital accessibility of CF. Ideally, the dark mode option would be:

• available for all standard documents in HTML view, as well as all webpages on the website - note since the alternative build format to HTML is PDF which is, in the internet age, used much more with printing in mind, I don't think it is important to consider here for dark mode support (but that is open for discussion);
• configurable so that the viewer can switch easily between light and dark mode by means of a button or similar;
• by default, assigned to the dark or light mode preference expressed by the viewer in their browser preferences.

Note whilst further theme/style options might be nice to have, a dark mode alternative to light mode is the most pressing and common alternative to provide, so would be a good first step to support, even if in future others wish to extend with even more possibilities for themes/modes.

Benefits

Dark mode is preferred by many to light mode because it can be less strain on the eyes and facilitate working from a dark room and/or at night, or simply is favoured as a style preference - so many community members would benefit from being able to choose to view the CF documents and website in dark mode. Anyone viewing the document could (on paper), at least, appreciate that we have provided a choice of themes rather than one fixed one.

Status Quo

At present, both the documents in HTML and the website only have one styling theme available i.e. the theme is fixed, and it is in 'light' mode - that is, dark text on a light background. There is no native configurability there (though someone could technically tweak theming via a browser plugin, and one can for sure tweak things via changing CSS values from the developer console/tools, but both of these are contrived, custom solutions that require effort and knowledge, therefore not acceptable).

Associated pull request

#608

Detailed Proposal

n/a - all covered above.

[DocOtak]

This is great! The problem with the parallel hackathons is I usually want to be in all of them...

In some other technical documentation sites that I'm used to (mostly from python), the light/dark more toggle switch is often three states:

• force dark
• force light
• system (the thing you get from prefers-color-scheme)

I haven't looked recently, but are all our figures SVG? if yes we would probably get those colors from CSS variables as well.

Re fonts:
I personally really like using the system front stack, and I have a slight interest is not needing a request to google to view the cf html pages. I do see that this matches the current CF document, so perhaps this is a topic for a different/separate discussion.

[ChrisBarker-NOAA]

Question about what is considered "best pracice" these days?

That is, should we be providing a "dark mode", or, rather, making sure that our sites work well with system / third party "dark modes" (and high contrast modes, etc).

My experience:

Before I got cataract surgery recently I was struggling to see a lot on the computer screen. One thing that helped was using a high contrast mode on my Mac. However, the high contrast modes on Windows options were pretty painful. But I suspect a web site designed well to work with them would be better.

At the time, I didn't try "Dark Mode" on my MAc -- it seems the community is treating that as a preference, rather than an accessibility thing, but I digress -- it IS and accessibility issue for some folks.

Anyway, a little bit ago, one of our team reported that one of our web apps looked horrible in the MAc System Dark mode. And it did. It turns out if you don't design for it, the default behavior can be pretty bad.

And it turns out that there's a mechanism -- at least according to Gemini:

"""
...If your website looks bad in dark mode on a Mac, it's likely because it doesn't have a dedicated dark mode design, so the browser is trying to automatically adapt it. To fix this, implement a dark mode-specific stylesheet using a media query like @media (prefers-color-scheme: dark) { ... } to define dark colors for text, backgrounds, and images that work well with a dark background.
"""

@sadielbartholomew -- maybe that's what you are already doing??

Or, now that I think about it, perhaps we can do both with one method -- auto-detect dark mode and apply the proper style sheet, and also provide a way for users to turn it on for just this site.

Some testing:

On a Mac, version 14.8

Just turning on Dark mode doesn't change wither the main CF website or the Main CF conventions doc at all.

• should it? I really don't know how that is supposed to work -- maybe it would make a change if we had addCSS with a dark mode option?

The Mac also provided other accessibility options:

Trying a few on the CF document:

"Invert Colors":

• Works beautifully on the text in the document you get white-on-black and links are orange -- quite readable
• Figures: many work quite. well, e.g.

• I haven't checked them all, but the ones I did are pretty good.

"Contrast:" -- cranking up to highest contrast doesn't work grat, but not horrible, either -- I think as good as any other site.

"Differentiate without color": doesn't seem to do anything ???

That's what I got -- the short version is that we seem to be in pretty good shape -- at least for MAc users. MAybe someone could try out the options on Windows.

[sadielbartholomew]

Thanks for your comments, Andrew and Chris. I will reply to each one at a time:

@DocOtak:

This is great! The problem with the parallel hackathons is I usually want to be in all of them...

Same here! Missed out on some exciting stuff sadly but on the plus side with less to think about I can focus on pushing along progress for sessions I attended (and chaired in a few cases).

In some other technical documentation sites that I'm used to (mostly from python) ...

I guess you are possibly referring to Sphinx-based documentation? That's what I consult/build a lot and where I most often see the toggle switch, for more modern themes at least where accessibility has been thought about more - notably the PyData Sphinx Theme which is more and more common and used as the theme for docs of such popular libraries as matploltib, SciPy and Jupyter. It has a whole section covering their accessibility efforts, so in my view we can take it as major inspiration for our own accessibility efforts (though we can't use the theme naturally given our infrastructure isn't Sphinx and there isn't as far as I can tell an easy way to 'port' their theme across to AsciiDoc for the documents nor Bootstrap for the website).

I haven't looked recently, but are all our figures SVG? if yes we would probably get those colors from CSS variables as well.

Yes, all SVG, as far as we ascertained in the Hackathon (I will need to double check) - though some are defined as SVG and some are built to SVG from '.gv' format.

Re fonts: ...

I haven't applied any styling to change the fonts from the default - but it did occur to me that it might be nice (but maybe overkill as far as accessibility improvements go) to allow some font configuration. I agree that using fonts configured as preference on the viewer's system would be a nice way to cater for their preferences (and reduce the need to fetch custom fonts, not that I imagine the page load speed would improve in any noticeable way from that).

[sadielbartholomew]

Sorry for the delay to reply to your comment, @ChrisBarker-NOAA, after replying to Andrew I kept getting pulled away with other work so I have had a half-finished comment on this page sitting idle in a tab for days...

@ChrisBarker-NOAA:

That is, should we be providing a "dark mode", or, rather, making sure that our sites work well with system / third party "dark modes" (and high contrast modes, etc).

I would strongly argue that it isn't an accessible solution to be satisfied that our pages and site work well with system or third party theming or styling, where there's a good motivation to provide some alternative theme feature (such as for dark mode, perhaps not for fonts as per my response to Andrew above).

This is because not everyone knows how to change/adjust their theme (from the default) via system or third-party plugin/app, and I would argue that the average internet user wouldn't readily know this, as opposed to those of us commenting here who are technically savvy hence could likely know how to do such things. So it would become an accessibility issue in itself - that dark mode would only be accessible to those with the technical know-how.

Also, we'd have to consider all of the cases one by one, for example the various OSs - you point out what works on Mac and that we'd have to check Windows but then there's also Linux and all the various distributions which vary greatly - so it would also be, I think, a lot simpler to just provide a dark mode solution that natively changes the theme.

Providing a native dark mode would not, of course, prevent those who know how to, and want to, from using system or third-party dark mode by applying it on top of the existing light mode, which nobody is saying we should get rid of altogether. (Certainly it would be inaccessible to not have a light mode.)

it seems the community is treating that as a preference, rather than an accessibility thing, but I digress -- it IS and accessibility issue for some folks.

Certainly dark mode can also be a style preference, perhaps more so at times than an accessibility feature, but I do agree that it is also a useful feature for accessibility, as well - that it also caters for stylistic preferences is a bonus, in my view.

@sadielbartholomew -- maybe that's what you are already doing??

What I've one so far, which is a proof of concept so can be scrapped if people don't like the idea or implementation, but serves as an illustration of the idea and how simple code-wise it can be to implement, is the PR #608 which provides a dark mode for the main document only (but could be trivially applied across all of the CF documents) and has a button in the top right to switch between the light and dark options, by default starting on the system preference for light or dark mode. You can preview how this looks on the branch I built via GitHub pages from the PR branch at: https://sadielbartholomew.github.io/cf-conventions/cf-conventions-previewonly.html. What do you think, Chris?

It seems as per @DocOtak's comment that it is perhaps more standard to have a toggle button have three options - light, dark, and default, in which case I can update the JavaScript theme switching logic to have the third option of default instead of initiating the theme on that without the option to switch back to it once toggled to dark or light. But that's a detail which can be decided at formal review time.