Dark mode toggle

[mbostock]

Should we support a dark mode toggle, like some sites do? It’s a bit redundant given that you can control it via system preferences, and that we automatically chose the default mode based on your system preferences, but it’s nice if the user wants to change it quickly I suppose.

[Fil]

Super useful in dev mode, maybe not useful (or optional) in prod?

[mbostock]

If it’s just for you in dev, you can also do this as a macOS Shortcut:

Then you can drag it to your menu bar or give it a keyboard shortcut or whatever.

[Fil]

Nice! I have adopted it.

A point in favor of a visible toggle: it is a way to make the developer aware that this is supported by default, so they don't end up shipping something they haven't thought to test.

[Fil]

Could be a configuration option (and a frontmatter option), with:

color-scheme: "light" | "dark" | "toggle" | "auto"

it would default to "auto" to retain the same behavior as it has now, or to "toggle" to make it visible by default.

[mbostock]

There are some fairly strong implications of adding a toggle:

• We’ll have to teach users to write mode-dependent style rules using a ::root.dark selector (or some such) instead of the standard @media (prefers-color-scheme: dark)
• Certain libraries may need to be configured based on the mode, such as the default theme for Mermaid (which currently uses matchMedia); these now have to know about ::root.dark too?
• If we want the libraries to be responsive, we’ll need to design and document a custom event to report changes, since we won’t be able to use the change event supported by matchMedia; or they need to use a mutation observer on the root element? 🤔

Overall, I’m not sure if we should head down this path.

[Fil]

The opposing view is that CLI's default support for user preference adds strong demands on the developer, by "forcing" them to support both light and dark modes.

Default templates and themes will support this, of course, and we're trying to have as much support as we can to make it easier. But still, it's not always easy. A developer might add a black or white stroke or fill with a view to a certain result, and not realize that they should have used currentColor or --var(--theme-background-alt) instead. Or they will use a color that works well on a white background (say, a dark blue, or maybe even a default value, such as interpolateturbo(0)), and not realize that it becomes almost invisible for users who have a dark os setting.

The toggle would be a good reminder that you need to develop the two versions. Another mitigation could be to add a way to "opt-out" of supporting user preference, and use only light (or only dark) mode. But indeed, it adds complexity. Unless there is a way to "set" the @media (prefers-color-scheme) in javascript? https://mybyways.com/blog/forcing-dark-mode-with-prefs-color-scheme-media-query shares an interesting technique.

[mbostock]

The opposing view is that CLI's default support for user preference adds strong demands on the developer, by "forcing" them to support both light and dark modes.

I think this onus is worth it because respecting the user’s preference improves the user’s experience substantially. And like you say, we should make it easy (as easy as possible) with the default themes and components.

We should allow the developer to opt-out with a project-level and page-level configuration option to force either light mode or force dark mode. (That’ll put some onus on our Mermaid library to ignore the user’s preference, too… not sure how we’ll do that.) I’ll file an issue.

[mbostock]

Apple explicitly advises against this:

Avoid offering an app-specific appearance setting. An app-specific appearance mode option creates more work for people because they have to adjust more than one setting to get the appearance they want. Worse, they may think your app is broken because it doesn’t respond to their systemwide appearance choice.

[Fil]

Should we disable it in our vitepress docs too? observablehq/plot#1955

Also, it makes sense to avoid this distraction for viewers, but I'm still looking for ways to surface to the developer that they have to think about the two presentations.