refactor(theme): rename mode APIs to color mode names

Copilot · IzumiSy · web-flow · commit cc9ed83c4bc8 · 2026-06-15T02:32:35.000Z
Co-authored-by: IzumiSy &lt;982850+IzumiSy@users.noreply.github.com&gt;
diff --git a/.changeset/theme-mode-palette-axes.md b/.changeset/theme-mode-palette-axes.md
@@ -4,8 +4,8 @@
 
 Split theming into two independent axes — **mode** (`light` / `dark` / `system`) and **theme/palette** (`default` / `cream` / `bloom`) — so every palette works in both light and dark.
 
-- New `useMode()` hook + `MODE_OPTIONS` for the end-user appearance control (light/dark/system). `useTheme()` now returns the color palette: `{ theme, setTheme }`. `ResolvedTheme` is replaced by `ResolvedMode`.
-- `<AppShell>` gains `defaultMode` (default `"system"`, persisted as the user preference); `defaultTheme` now selects the palette (default `"default"`). The palette is a developer config driven by the prop — it is **not** persisted to localStorage, so a stale stored value can't shadow the configured brand. Only mode (and font) persist.
+- New `useColorMode()` hook + `COLOR_MODE_OPTIONS` for the end-user appearance control (light/dark/system). `useTheme()` now returns the color palette: `{ theme, setTheme }`. `ResolvedTheme` is replaced by `ResolvedColorMode`.
+- `<AppShell>` gains `defaultColorMode` (default `"system"`, persisted as the user preference); `defaultTheme` now selects the palette (default `"default"`). The palette is a developer config driven by the prop — it is **not** persisted to localStorage, so a stale stored value can't shadow the configured brand. Only mode (and font) persist.
 - DOM: `<html>` carries the mode as the `.light` / `.dark` class and the palette as `data-theme`.
 - CSS: `light.css` + `dark.css` are merged into `default.css`; **Cream** and **Bloom** gain dark variants. The shell gradient is parameterized per mode.
 - The appearance switcher now offers Light / Dark / System only — the palette is a developer configuration. The font axis is unchanged.
diff --git a/packages/core/src/components/appshell.tsx b/packages/core/src/components/appshell.tsx
@@ -17,7 +17,7 @@ import {
   type ContextData,
 } from "@/contexts/appshell-context";
 import { RouterContainer } from "@/routing/router";
-import { ThemeProvider, type Mode, type Theme, type Font } from "@/contexts/theme-context";
+import { ThemeProvider, type ColorMode, type Theme, type Font } from "@/contexts/theme-context";
 import { BreadcrumbOverrideProvider } from "@/contexts/breadcrumb-context";
 import { CommandPaletteProvider, type SearchSource } from "@/contexts/command-palette-context";
 import { BuiltInCommandPalette } from "@/components/command-palette";
@@ -186,12 +186,12 @@ type SharedAppShellProps = React.PropsWithChildren<{
    *
    * @default "system"
    */
-  defaultMode?: Mode;
+  defaultColorMode?: ColorMode;
 
   /**
    * Color palette / brand (developer configuration), applied as `data-theme`.
    * One of **`default`**, **`cream`**, or **`bloom`** — each ships both light and dark
-   * variants, so the active variant follows {@link AppShellProps.defaultMode}.
+   * variants, so the active variant follows {@link AppShellProps.defaultColorMode}.
    * This is set by the product (not a user-facing picker), so it is driven by this
    * prop and not persisted to localStorage.
    *
@@ -350,7 +350,7 @@ export const AppShell = (props: AppShellProps) => {
         <BreadcrumbOverrideProvider>
           <CommandPaletteProvider searchSources={props.searchSources}>
             <ThemeProvider
-              defaultMode={props.defaultMode}
+              defaultColorMode={props.defaultColorMode}
               defaultTheme={props.defaultTheme}
               defaultFont={props.defaultFont}
             >
diff --git a/packages/core/src/components/theme-switcher.test.tsx b/packages/core/src/components/theme-switcher.test.tsx
@@ -2,7 +2,7 @@ import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { FONT_OPTIONS, MODE_OPTIONS, ThemeProvider } from "@/contexts/theme-context";
+import { FONT_OPTIONS, COLOR_MODE_OPTIONS, ThemeProvider } from "@/contexts/theme-context";
 
 import { ThemeSwitcher } from "./theme-switcher";
 
@@ -69,7 +69,7 @@ describe("ThemeSwitcher", () => {
     const user = userEvent.setup();
 
     render(
-      <ThemeProvider defaultMode="light">
+      <ThemeProvider defaultColorMode="light">
         <ThemeSwitcher />
       </ThemeProvider>,
     );
@@ -78,11 +78,11 @@ describe("ThemeSwitcher", () => {
 
     await waitFor(() => {
       expect(screen.getAllByRole("menuitemradio").length).toBe(
-        MODE_OPTIONS.length + FONT_OPTIONS.length,
+        COLOR_MODE_OPTIONS.length + FONT_OPTIONS.length,
       );
     });
 
-    for (const opt of MODE_OPTIONS) {
+    for (const opt of COLOR_MODE_OPTIONS) {
       expect(screen.getByRole("menuitemradio", { name: opt.label })).toBeDefined();
     }
     for (const opt of FONT_OPTIONS) {
@@ -111,7 +111,7 @@ describe("ThemeSwitcher", () => {
 
   it("exposes the resolved mode on the trigger when system mode is selected", () => {
     render(
-      <ThemeProvider defaultMode="system">
+      <ThemeProvider defaultColorMode="system">
         <ThemeSwitcher />
       </ThemeProvider>,
     );
@@ -125,7 +125,7 @@ describe("ThemeSwitcher", () => {
     const user = userEvent.setup();
 
     render(
-      <ThemeProvider defaultMode="light">
+      <ThemeProvider defaultColorMode="light">
         <ThemeSwitcher />
       </ThemeProvider>,
     );
@@ -148,7 +148,7 @@ describe("ThemeSwitcher", () => {
     const user = userEvent.setup();
 
     render(
-      <ThemeProvider defaultMode="light" defaultFont="geist">
+      <ThemeProvider defaultColorMode="light" defaultFont="geist">
         <ThemeSwitcher />
       </ThemeProvider>,
     );
diff --git a/packages/core/src/components/theme-switcher.tsx b/packages/core/src/components/theme-switcher.tsx
@@ -4,16 +4,16 @@ import { Menu } from "@/components/menu";
 import { Button } from "@/components/button";
 import { cn } from "@/lib/utils";
 import {
-  useMode,
+  useColorMode,
   useFont,
-  type ResolvedMode,
-  type Mode,
+  type ResolvedColorMode,
+  type ColorMode,
   type Font,
-  MODE_OPTIONS,
+  COLOR_MODE_OPTIONS,
   FONT_OPTIONS,
 } from "@/contexts/theme-context";
 
-const RESOLVED_MODE_SHORT: Record<ResolvedMode, string> = {
+const RESOLVED_MODE_SHORT: Record<ResolvedColorMode, string> = {
   light: "Light",
   dark: "Dark",
 };
@@ -23,7 +23,7 @@ const RESOLVED_MODE_SHORT: Record<ResolvedMode, string> = {
  * tones; system splits the two to signal "follows the OS".
  * Kept as static hex previews so they render before any stylesheet loads.
  */
-const MODE_PREVIEW: Record<Mode, { readonly a: `#${string}`; readonly b: `#${string}` }> = {
+const MODE_PREVIEW: Record<ColorMode, { readonly a: `#${string}`; readonly b: `#${string}` }> = {
   light: { a: "#ffffff", b: "#d4d4d8" },
   dark: { a: "#3f3f46", b: "#71717a" },
   system: { a: "#ffffff", b: "#3f3f46" },
@@ -36,8 +36,8 @@ const FONT_PREVIEW: Record<Font, string> = {
   inter: '"Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif',
 };
 
-function isMode(value: string): value is Mode {
-  return MODE_OPTIONS.some((o) => o.value === value);
+function isMode(value: string): value is ColorMode {
+  return COLOR_MODE_OPTIONS.some((o) => o.value === value);
 }
 
 function isFont(value: string): value is Font {
@@ -56,7 +56,7 @@ function radioItemClasses(active: boolean) {
   );
 }
 
-function ModePreviewSwatches({ modeId }: { modeId: Mode }) {
+function ModePreviewSwatches({ modeId }: { modeId: ColorMode }) {
   const { a, b } = MODE_PREVIEW[modeId];
   return (
     <div
@@ -97,7 +97,7 @@ function FontPreview({ fontId }: { fontId: Font }) {
  * shown here. **System** stays explicit on the mode axis.
  */
 function ThemeSwitcher() {
-  const { mode, resolvedMode, setMode } = useMode();
+  const { mode, resolvedMode, setMode } = useColorMode();
   const { font, setFont } = useFont();
 
   const fontLabel = FONT_OPTIONS.find((o) => o.value === font)?.label ?? font;
@@ -135,7 +135,7 @@ function ThemeSwitcher() {
               if (typeof value === "string" && isMode(value)) setMode(value);
             }}
           >
-            {MODE_OPTIONS.map((opt) => (
+            {COLOR_MODE_OPTIONS.map((opt) => (
               <Menu.RadioItem
                 key={opt.value}
                 value={opt.value}
diff --git a/packages/core/src/contexts/theme-context.test.tsx b/packages/core/src/contexts/theme-context.test.tsx
@@ -1,7 +1,7 @@
 import { cleanup, render, act, waitFor } from "@testing-library/react";
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { ThemeProvider, useMode, useTheme, useFont } from "./theme-context";
+import { ThemeProvider, useColorMode, useTheme, useFont } from "./theme-context";
 
 /** happy-dom / Node can omit a full `localStorage`; ThemeProvider persists via it. */
 function installLocalStorageStub() {
@@ -72,7 +72,7 @@ afterEach(() => {
 });
 
 function Probe() {
-  const { mode, resolvedMode } = useMode();
+  const { mode, resolvedMode } = useColorMode();
   const { theme } = useTheme();
   return (
     <div>
@@ -89,11 +89,11 @@ function FontProbe() {
 }
 
 describe("ThemeProvider — storage validation", () => {
-  it("falls back to defaultMode for an unrecognized stored mode", () => {
+  it("falls back to defaultColorMode for an unrecognized stored mode", () => {
     storageMap.set("appshell-ui-mode", "totally-not-a-mode");
 
     const { getByTestId } = render(
-      <ThemeProvider defaultMode="dark">
+      <ThemeProvider defaultColorMode="dark">
         <Probe />
       </ThemeProvider>,
     );
@@ -235,13 +235,13 @@ describe("ThemeProvider — system mode resolution", () => {
 });
 
 describe("provider guards", () => {
-  it("throws when useMode is called outside ThemeProvider", () => {
+  it("throws when useColorMode is called outside ThemeProvider", () => {
     const spy = vi.spyOn(console, "error").mockImplementation(() => {});
     const ModeProbe = () => {
-      useMode();
+      useColorMode();
       return null;
     };
-    expect(() => render(<ModeProbe />)).toThrow(/useMode must be used within a ThemeProvider/);
+    expect(() => render(<ModeProbe />)).toThrow(/useColorMode must be used within a ThemeProvider/);
     spy.mockRestore();
   });
 
diff --git a/packages/core/src/contexts/theme-context.tsx b/packages/core/src/contexts/theme-context.tsx
@@ -4,17 +4,17 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useState }
  * Color mode — the end-user accessibility preference. `system` follows the OS
  * light/dark setting. Applied to `<html>` as the `.light` / `.dark` class.
  */
-export type Mode = "light" | "dark" | "system";
+export type ColorMode = "light" | "dark" | "system";
 
 /** Mode after resolving `system` to a concrete value. */
-export type ResolvedMode = "light" | "dark";
+export type ResolvedColorMode = "light" | "dark";
 
-const ALL_MODES: readonly Mode[] = ["light", "dark", "system"] as const;
+const ALL_COLOR_MODES: readonly ColorMode[] = ["light", "dark", "system"] as const;
 
 /** Switcher entries for the appearance (mode) control. */
-export type ModeOption = { readonly value: Mode; readonly label: string };
+export type ColorModeOption = { readonly value: ColorMode; readonly label: string };
 
-export const MODE_OPTIONS: readonly ModeOption[] = [
+export const COLOR_MODE_OPTIONS: readonly ColorModeOption[] = [
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
   { value: "system", label: "System" },
@@ -23,7 +23,7 @@ export const MODE_OPTIONS: readonly ModeOption[] = [
 /**
  * Color palette / brand — a developer/product configuration (not a user-facing
  * picker). Each palette ships both a light and a dark variant; the active
- * variant is chosen by the {@link Mode} axis. Applied to `<html>` as `data-theme`.
+ * variant is chosen by the {@link ColorMode} axis. Applied to `<html>` as `data-theme`.
  */
 export type Theme = "default" | "cream" | "bloom";
 
@@ -64,17 +64,17 @@ function readStored<T extends string>(key: string, allowList: readonly T[], fall
 type ThemeProviderProps = {
   children: React.ReactNode;
   /** Initial color mode (user preference). @default "system" */
-  defaultMode?: Mode;
+  defaultColorMode?: ColorMode;
   /** Color palette / brand (developer config). @default "default" */
   defaultTheme?: Theme;
   /** Initial font. @default "geist" */
   defaultFont?: Font;
 };
 
 type ThemeProviderState = {
-  mode: Mode;
-  resolvedMode: ResolvedMode;
-  setMode: (mode: Mode) => void;
+  mode: ColorMode;
+  resolvedMode: ResolvedColorMode;
+  setMode: (mode: ColorMode) => void;
   theme: Theme;
   setTheme: (theme: Theme) => void;
   font: Font;
@@ -85,12 +85,12 @@ const ThemeProviderContext = createContext<ThemeProviderState | undefined>(undef
 
 export function ThemeProvider({
   children,
-  defaultMode = "system",
+  defaultColorMode = "system",
   defaultTheme = "default",
   defaultFont = "geist",
 }: ThemeProviderProps) {
-  const [mode, setModeState] = useState<Mode>(() =>
-    readStored(MODE_STORAGE_KEY, ALL_MODES, defaultMode),
+  const [mode, setModeState] = useState<ColorMode>(() =>
+    readStored(MODE_STORAGE_KEY, ALL_COLOR_MODES, defaultColorMode),
   );
   // Palette is a developer configuration, not a user preference — it comes from
   // `defaultTheme` (the brand the product chose) and is NOT read from / persisted
@@ -115,7 +115,7 @@ export function ThemeProvider({
     return () => mql.removeEventListener("change", handler);
   }, []);
 
-  const resolvedMode: ResolvedMode = (() => {
+  const resolvedMode: ResolvedColorMode = (() => {
     if (mode !== "system") return mode;
     return systemDark ? "dark" : "light";
   })();
@@ -133,7 +133,7 @@ export function ThemeProvider({
     window.document.documentElement.dataset.font = font;
   }, [font]);
 
-  const setMode = useCallback((newMode: Mode) => {
+  const setMode = useCallback((newMode: ColorMode) => {
     try {
       localStorage.setItem(MODE_STORAGE_KEY, newMode);
     } catch {
@@ -164,9 +164,9 @@ export function ThemeProvider({
 }
 
 /** Color mode (light / dark / system) — the end-user accessibility preference. */
-export const useMode = () => {
+export const useColorMode = () => {
   const context = useContext(ThemeProviderContext);
-  if (context === undefined) throw new Error("useMode must be used within a ThemeProvider");
+  if (context === undefined) throw new Error("useColorMode must be used within a ThemeProvider");
 
   const { mode, resolvedMode, setMode } = context;
   return useMemo(() => ({ mode, resolvedMode, setMode }), [mode, resolvedMode, setMode]);
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -25,15 +25,15 @@ export { WithGuard, type WithGuardProps } from "./components/with-guard";
 
 export { useAppShell, useAppShellConfig, useAppShellData } from "./contexts/appshell-context";
 export {
-  useMode,
+  useColorMode,
   useTheme,
   useFont,
-  MODE_OPTIONS,
+  COLOR_MODE_OPTIONS,
   THEME_OPTIONS,
   FONT_OPTIONS,
-  type Mode,
-  type ResolvedMode,
-  type ModeOption,
+  type ColorMode,
+  type ResolvedColorMode,
+  type ColorModeOption,
   type Theme,
   type ThemeOption,
   type Font,
