Invert color-mode toggle icon to show the target mode

src/theme/ColorModeToggle/index.tsx

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ */
+
+// Ejected from @docusaurus/theme-classic to invert which icon the toggle
+// shows: the icon now represents the mode you'd switch TO (moon on a light
+// background, sun on a dark background). The component logic is unchanged from
+// upstream; only the co-located styles.module.css swaps the light/dark mapping.
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+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';
+
+// 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';
+  }
+
+  // 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 color mode toggle',
+    },
+    {
+      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
+        className={clsx(
+          'clean-btn',
+          styles.toggleButton,
+          !isBrowser && styles.toggleButtonDisabled,
+          buttonClassName,
+        )}
+        type="button"
+        onClick={() =>
+          onChange(getNextColorMode(value, respectPrefersColorScheme))
+        }
+        disabled={!isBrowser}
+        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>
+  );
+}
+
+export default React.memo(ColorModeToggle);

src/theme/ColorModeToggle/styles.module.css

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+
+.toggle {
+  width: 2rem;
+  height: 2rem;
+}
+
+.toggleButton {
+  -webkit-tap-highlight-color: transparent;
+  align-items: center;
+  display: flex;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  transition: background var(--ifm-transition-fast);
+}
+
+.toggleButton:hover {
+  background: var(--ifm-color-emphasis-200);
+}
+
+.toggleIcon {
+  display: none;
+}
+
+/*
+ * Inverted from upstream: the toggle shows the icon of the mode you'd switch TO,
+ * not the current mode. Light background -> moon (dark icon); dark background ->
+ * sun (light icon). System choice still shows the system icon.
+ */
+[data-theme-choice='system'] .systemToggleIcon,
+[data-theme-choice='light'] .darkToggleIcon,
+[data-theme-choice='dark'] .lightToggleIcon {
+  display: initial;
+}
+
+.toggleButtonDisabled {
+  cursor: not-allowed;
+}