feat(theme): Allow resetting colorMode to System/OS value

packages/docusaurus-theme-classic/src/inlineScripts.ts

@@ -30,43 +30,22 @@ export function getThemeInlineScript({
   return `(function() {
     var defaultMode = '${defaultMode}';
     var respectPrefersColorScheme = ${respectPrefersColorScheme};
-
-    function setDataThemeAttribute(theme) {
-      document.documentElement.setAttribute('data-theme', theme);
+    function getSystemColorMode() {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
     }
-
     function getQueryStringTheme() {
       try {
         return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
-      } catch (e) {
-      }
+      } catch (e) {}
     }
-
     function getStoredTheme() {
       try {
         return window['${siteStorage.type}'].getItem('${themeStorageKey}');
-      } catch (err) {
-      }
+      } catch (err) {}
     }
-
     var initialTheme = getQueryStringTheme() || getStoredTheme();
-    if (initialTheme !== null) {
-      setDataThemeAttribute(initialTheme);
-    } else {
-      if (
-        respectPrefersColorScheme &&
-        window.matchMedia('(prefers-color-scheme: dark)').matches
-      ) {
-        setDataThemeAttribute('dark');
-      } else if (
-        respectPrefersColorScheme &&
-        window.matchMedia('(prefers-color-scheme: light)').matches
-      ) {
-        setDataThemeAttribute('light');
-      } else {
-        setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
-      }
-    }
+    document.documentElement.setAttribute('data-theme', initialTheme || (respectPrefersColorScheme ? getSystemColorMode() : defaultMode));
+    document.documentElement.setAttribute('data-theme-choice', initialTheme || (respectPrefersColorScheme ? 'system' : defaultMode));
   })();`;
 }
 

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -1555,12 +1555,13 @@ declare module '@theme/ColorModeToggle' {
   export interface Props {
     readonly className?: string;
     readonly buttonClassName?: string;
-    readonly value: ColorMode;
+    readonly respectPrefersColorScheme: boolean;
+    readonly value: ColorMode | null;
     /**
      * The parameter represents the "to-be" value. For example, if currently in
-     * dark mode, clicking the button should call `onChange("light")`
+     * light mode, clicking the button should call `onChange("dark")`
      */
-    readonly onChange: (colorMode: ColorMode) => void;
+    readonly onChange: (colorMode: ColorMode | null) => void;
   }
 
   export default function ColorModeToggle(props: Props): ReactNode;
@@ -1617,6 +1618,14 @@ declare module '@theme/Icon/LightMode' {
   export default function IconLightMode(props: Props): ReactNode;
 }
 
+declare module '@theme/Icon/SystemColorMode' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function IconSystemColorMode(props: Props): JSX.Element;
+}
+
 declare module '@theme/Icon/Menu' {
   import type {ComponentProps, ReactNode} from 'react';
 

packages/docusaurus-theme-classic/src/theme/ColorModeToggle/index.tsx

@@ -11,40 +11,105 @@ import useIsBrowser from '@docusaurus/useIsBrowser';
 import {translate} from '@docusaurus/Translate';
 import IconLightMode from '@theme/Icon/LightMode';
 import IconDarkMode from '@theme/Icon/DarkMode';
+import IconSystemColorMode from '@theme/Icon/SystemColorMode';
 import type {Props} from '@theme/ColorModeToggle';
+import type {ColorMode} from '@docusaurus/theme-common';
 
 import styles from './styles.module.css';
 
-function ColorModeToggle({
-  className,
-  buttonClassName,
-  value,
-  onChange,
-}: Props): ReactNode {
-  const isBrowser = useIsBrowser();
+// The order of color modes is defined here, and can be customized with swizzle
+function getNextColorMode(
+  colorMode: ColorMode | null,
+  respectPrefersColorScheme: boolean,
+) {
+  // 2-value transition
+  if (!respectPrefersColorScheme) {
+    return colorMode === 'dark' ? 'light' : 'dark';
+  }
 
-  const title = translate(
+  // 3-value transition
+  switch (colorMode) {
+    case null:
+      return 'light';
+    case 'light':
+      return 'dark';
+    case 'dark':
+      return null;
+    default:
+      throw new Error(`unexpected color mode ${colorMode}`);
+  }
+}
+
+function getColorModeLabel(colorMode: ColorMode | null): string {
+  switch (colorMode) {
+    case null:
+      return translate({
+        message: 'system mode',
+        id: 'theme.colorToggle.ariaLabel.mode.system',
+        description: 'The name for the system color mode',
+      });
+    case 'light':
+      return translate({
+        message: 'light mode',
+        id: 'theme.colorToggle.ariaLabel.mode.light',
+        description: 'The name for the light color mode',
+      });
+    case 'dark':
+      return translate({
+        message: 'dark mode',
+        id: 'theme.colorToggle.ariaLabel.mode.dark',
+        description: 'The name for the dark color mode',
+      });
+    default:
+      throw new Error(`unexpected color mode ${colorMode}`);
+  }
+}
+
+function getColorModeAriaLabel(colorMode: ColorMode | null) {
+  return translate(
     {
       message: 'Switch between dark and light mode (currently {mode})',
       id: 'theme.colorToggle.ariaLabel',
-      description: 'The ARIA label for the navbar color mode toggle',
+      description: 'The ARIA label for the color mode toggle',
     },
     {
-      mode:
-        value === 'dark'
-          ? translate({
-              message: 'dark mode',
-              id: 'theme.colorToggle.ariaLabel.mode.dark',
-              description: 'The name for the dark color mode',
-            })
-          : translate({
-              message: 'light mode',
-              id: 'theme.colorToggle.ariaLabel.mode.light',
-              description: 'The name for the light color mode',
-            }),
+      mode: getColorModeLabel(colorMode),
     },
   );
+}
 
+function CurrentColorModeIcon(): ReactNode {
+  // 3 icons are always rendered for technical reasons
+  // We use "data-theme-choice" to render the correct one
+  // This must work even before React hydrates
+  return (
+    <>
+      <IconLightMode
+        // a18y is handled at the button level,
+        // not relying on button content (svg icons)
+        aria-hidden
+        className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
+      />
+      <IconDarkMode
+        aria-hidden
+        className={clsx(styles.toggleIcon, styles.darkToggleIcon)}
+      />
+      <IconSystemColorMode
+        aria-hidden
+        className={clsx(styles.toggleIcon, styles.systemToggleIcon)}
+      />
+    </>
+  );
+}
+
+function ColorModeToggle({
+  className,
+  buttonClassName,
+  respectPrefersColorScheme,
+  value,
+  onChange,
+}: Props): ReactNode {
+  const isBrowser = useIsBrowser();
   return (
     <div className={clsx(styles.toggle, className)}>
       <button
@@ -55,18 +120,23 @@ function ColorModeToggle({
           buttonClassName,
         )}
         type="button"
-        onClick={() => onChange(value === 'dark' ? 'light' : 'dark')}
+        onClick={() =>
+          onChange(getNextColorMode(value, respectPrefersColorScheme))
+        }
         disabled={!isBrowser}
-        title={title}
-        aria-label={title}
-        aria-live="polite"
-        aria-pressed={value === 'dark' ? 'true' : 'false'}>
-        <IconLightMode
-          className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
-        />
-        <IconDarkMode
-          className={clsx(styles.toggleIcon, styles.darkToggleIcon)}
-        />
+        title={getColorModeLabel(value)}
+        aria-label={getColorModeAriaLabel(value)}
+
+        // For accessibility decisions
+        // See https://github.com/facebook/docusaurus/issues/7667#issuecomment-2724401796
+
+        // aria-live disabled on purpose - This is annoying because:
+        // - without this attribute, VoiceOver doesn't announce on button enter
+        // - with this attribute, VoiceOver announces twice on ctrl+opt+space
+        // - with this attribute, NVDA announces many times
+        // aria-live="polite"
+      >
+        <CurrentColorModeIcon />
       </button>
     </div>
   );

packages/docusaurus-theme-classic/src/theme/ColorModeToggle/styles.module.css

@@ -25,11 +25,16 @@
   background: var(--ifm-color-emphasis-200);
 }
 
-[data-theme='light'] .darkToggleIcon,
-[data-theme='dark'] .lightToggleIcon {
+.toggleIcon {
   display: none;
 }
 
+[data-theme-choice='system'] .systemToggleIcon,
+[data-theme-choice='light'] .lightToggleIcon,
+[data-theme-choice='dark'] .darkToggleIcon {
+  display: initial;
+}
+
 .toggleButtonDisabled {
   cursor: not-allowed;
 }

packages/docusaurus-theme-classic/src/theme/Icon/SystemColorMode/index.tsx

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactNode} from 'react';
+import type {Props} from '@theme/Icon/SystemColorMode';
+
+export default function IconSystemColorMode(props: Props): ReactNode {
+  return (
+    <svg viewBox="0 0 24 24" width={24} height={24} {...props}>
+      <path
+        fill="currentColor"
+        d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"
+      />
+    </svg>
+  );
+}

packages/docusaurus-theme-classic/src/theme/Navbar/ColorModeToggle/index.tsx

@@ -13,10 +13,10 @@ import styles from './styles.module.css';
 
 export default function NavbarColorModeToggle({className}: Props): ReactNode {
   const navbarStyle = useThemeConfig().navbar.style;
-  const disabled = useThemeConfig().colorMode.disableSwitch;
-  const {colorMode, setColorMode} = useColorMode();
+  const {disableSwitch, respectPrefersColorScheme} = useThemeConfig().colorMode;
+  const {colorModeChoice, setColorMode} = useColorMode();
 
-  if (disabled) {
+  if (disableSwitch) {
     return null;
   }
 
@@ -26,7 +26,8 @@ export default function NavbarColorModeToggle({className}: Props): ReactNode {
       buttonClassName={
         navbarStyle === 'dark' ? styles.darkNavbarColorModeToggle : undefined
       }
-      value={colorMode}
+      respectPrefersColorScheme={respectPrefersColorScheme}
+      value={colorModeChoice}
       onChange={setColorMode}
     />
   );