refactor(v2): refactor color mode system to enable all possibilities

[slorber]

Breaking change!

This is a proposal for now to validate the API/config.

I'll add documentation and clear user errors to make migration easier.

Motivation

Related to:

• [bug] v2 doesn't honor defaultDarkMode options #2919
• (v2) Can't enable light mode by default #2871

The current settings are a bit confusing and do not allow maximum flexibility for all users needs

Some things impossible with current api:

• disable the toggle, but use the dark mode by default
• disable the toggle, and respect the user preferred color
• force default light theme, ignoring the user preferred color
• set dark theme by default, but respect the user preference to light if set

The new settings should allow all possible variations and be less confusing.

{
    colorMode: {
      // false = light, true = dark
      defaultDarkMode: false,

      // should we care about `prefers-color-scheme` ?
      // according to issues, users expect `defaultDarkMode` to have higher priority
      // so I think we should ignore user preference by default
      respectUserPreference: false,

      // can we toggle the color or not
      disableSwitch: false,
    },
}

Test Plan

Preview and local tests

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 2637668

https://deploy-preview-2939--docusaurus-2.netlify.app

[apsdehal]

Since v2 has active users, it would be good to throw a proper error on older configuration parameters.

[apsdehal]

It would be better to more explicitly describe in the option itself that what exactly is this preference. respectUserDarkModeSystemPreference (being elaborate here)

[slorber]

https://drafts.csswg.org/mediaqueries-5/#prefers-color-scheme

I don't like the idea to have dark mode in the attribute name. As it's specified, the preferred color scheme may be extended in the future to other values like "sepia" (wouldn't be surprised to see new values being created for color blind people in the future).

Also not fan of "system". It's not part of the spec where this preference is configured exactly. It can be your OS, it can be your browser, it can be a browser plugin...

[apsdehal]

Need to run prettier here?

[slorber]

as it's a string literal it would be hard to run prettier here :)

[slorber]

@apsdehal

Since v2 has active users, it would be good to throw a proper error on older configuration parameters.

Yes, this is what I'd like to do. Didn't work on the docs and migration plan for now, as I want your opinion on the new API first.

[slorber]

BTW, as mentioned, the colors might be extended to "sepia" and other values in the future.

Not totally a fan of having a boolean defaultDarkMode: false

What about defaultValue: "dark" / defaultValue: "light" instead? It could be more explicit and future-proof

[EthanSK]

BTW, as mentioned, the colors might be extended to "sepia" and other values in the future.

Not totally a fan of having a boolean defaultDarkMode: false

What about defaultValue: "dark" / defaultValue: "light" instead? It could be more explicit and future-proof

defaultValue seems much better and future proof. Everything else looks good - I would personally call it something more explicit than respectUserPreference as if I saw that without understanding how user preference works (and even the existence of it!) I would be quite confused...if not make sure to document it well 😅

[slorber]

thanks @EthanSK will update the PR soon.

About respectUserPreference I'm open for a better naming if you have something to suggest that does not mention dark or system :p

[EthanSK]

@slorber Here are some suggestions:
overrideUserPreference
overrideBrowserPreference
overrideBuiltinPreference

But actually, since prefer-color-scheme is a css standard , maybe it's best to incorporate that in the name:
overridePrefersColorScheme
preventPrefersColorScheme
overridePrefersColorSchemeMedia
overrideCssPrefersColorScheme
overrideMediaFeature
overrideCSSMediaFeature

However, I do think it isn't a big deal to have system in the name, because as you can see here (https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme), "...to detect if the user has requested the system use a light or dark color theme." They mention that it is a system thing.

My favourite would probably be
overridePrefersColorSchemeMedia or overridePrefersColorScheme

[slorber]

@EthanSK my reasoning for respectUserPreference is that I think by default, users would expect D2 to pick their theme as the default one, ignoring the actual user preference.

I think it's simpler to have a default value to false than to true, and why I prefer respectUserPreference: undefined to overrideUserPreference: true for the default value.

By default, should we ignore the user preference? I think we do, otherwise D2 site owners might develop their website with a single dark theme (their own user preference), and report that some of their uses are actually seeing the light theme. That can be annoying, in particular for sites having disableSwitch: true.

I think respecting the user preference here is:

• confusing for a site without a dark mode switch
• quite useless for a site where the user can choose his color mode with the switch

---

What about:

• respectPreferredColorScheme: true?
• usePreferredColorScheme: true?
• usePrefersColorScheme: true?

[EthanSK]

@slorber I agree with you, the default should be to ignore the user preference. TBH I did use the word 'override' in all of my examples, but the main suggestions was the rest of the word, I should've made that clear :p

I like usePrefersColorScheme, the only (very minor) problem with use instead of respect is that it doesn't indicate to the user that it will fall back to the config-provided color scheme settings if prefers-color-scheme isn't set. respect kind of implies that it will try to use the prefers-color-scheme if possible, and there will not be any errors if it doesn't exist, so in that regard it's better...just feels a bit weird having the word respect in a config choice, but I guess that more accurately describes what it's doing... so yeah, i'd go with respectPrefersColorScheme...Could also have tryUsePreferredColorScheme

I also don't know if it should be the past tense preferred because then that doesn't match the css media query and could cause confusion...that's why maybe it might be a good idea to have another word to indicated what it actually is...like css or media, so it would be respectPrefersColorSchemeMedia, but maybe that's too verbose

Dam this is hard xD

I think at the end of the day, it's probably best to not make it too verbose, because the user is going to read the documentation for how to use it anyway, so respectPrefersColorScheme or respectPreferredColorScheme is my final recommendation

[slorber]

Thanks for the feedback

So, the final config might be:

{
    colorMode: {
      // The default color mode you want
      defaultMode: "light",

      // should we use the user preferred color scheme media query?
      // people generally expect "defaultMode" to 
      respectPrefersColorScheme: false,

      // disable the light/dark color mode switch
      disableSwitch: false,
    },
}

[slorber]

New PR to track: #3012