refactor(theme): rename Theme→ThemePalette, ColorMode→ColorTheme

IzumiSy · IzumiSy · commit d3137b313670 · 2026-06-15T16:45:27.000+09:00
Clarify the two independent axes of the theming system:
- ThemePalette (default/cream/bloom): developer-configured brand palette
- ColorTheme (light/dark/system): user-facing color scheme preference

Rename internal variables, props, constants, and test IDs to align
with the new terminology. Public hook API (useTheme → theme/resolvedTheme/setTheme)
remains unchanged for backward compatibility.
diff --git a/.changeset/theme-mode-palette-axes.md b/.changeset/theme-mode-palette-axes.md
@@ -6,10 +6,14 @@ Introduce a **theme** (palette) system with built-in `default`, `cream`, and `bl
 
 #### Color mode (end-user preference, persisted)
 
-- `useColorMode()` hook returns `{ mode, resolvedMode, setMode }`.
+- `useTheme()` hook continues to return `{ theme, resolvedTheme, setTheme }` (backward compatible).
 - `<AppShell defaultColorMode="system">` sets the initial preference; user choice is persisted to localStorage.
 
-#### Theme (developer configuration, not persisted)
+#### Theme / Palette (developer configuration, not persisted)
 
-- `useTheme()` hook returns `{ theme }` (read-only).
 - `<AppShell defaultTheme="default">` selects the brand palette; not stored in localStorage so a stale value never shadows the configured brand.
+- Palette is applied via `data-theme` attribute on `<html>`.
+
+#### AppearanceSwitcher
+
+- New `<AppearanceSwitcher />` component for toggling color mode.
diff --git a/examples/nextjs-app/src/app/dashboard/[[...props]]/page.tsx b/examples/nextjs-app/src/app/dashboard/[[...props]]/page.tsx
@@ -13,7 +13,7 @@ const App = () => {
   const appShellConfig: AppShellProps = {
     title: "AppShell",
     basePath: "dashboard",
-    defaultTheme: "cream",
+    defaultThemePalette: "cream",
     modules: [customPageModule],
     rootComponent: () => <div>Dashboard Home (accessible at /dashboard)</div>,
     settingsResources: [profileResource],
diff --git a/examples/vite-app/src/App.tsx b/examples/vite-app/src/App.tsx
@@ -25,7 +25,11 @@ const searchSources: SearchSource[] = [
 
 const App = () => {
   return (
-    <AppShell title="File-Based Routing Demo" searchSources={searchSources} defaultTheme="bloom">
+    <AppShell
+      title="File-Based Routing Demo"
+      searchSources={searchSources}
+      defaultThemePalette="bloom"
+    >
       <SidebarLayout
         sidebar={
           <DefaultSidebar>
diff --git a/packages/core/src/components/appearance-switcher.test.tsx b/packages/core/src/components/appearance-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 { COLOR_MODE_OPTIONS, ThemeProvider } from "@/contexts/theme-context";
+import { COLOR_THEME_OPTIONS, ThemeProvider } from "@/contexts/theme-context";
 import { AppearanceSwitcher } from "./appearance-switcher";
 
 /** happy-dom / Node can omit a full `localStorage`; ThemeProvider persists via it. */
@@ -67,18 +67,18 @@ describe("AppearanceSwitcher", () => {
     const user = userEvent.setup();
 
     render(
-      <ThemeProvider defaultColorMode="light">
+      <ThemeProvider defaultColorTheme="light">
         <AppearanceSwitcher />
       </ThemeProvider>,
     );
 
     await user.click(screen.getByRole("button", { name: "Appearance" }));
 
     await waitFor(() => {
-      expect(screen.getAllByRole("menuitemradio").length).toBe(COLOR_MODE_OPTIONS.length);
+      expect(screen.getAllByRole("menuitemradio").length).toBe(COLOR_THEME_OPTIONS.length);
     });
 
-    for (const opt of COLOR_MODE_OPTIONS) {
+    for (const opt of COLOR_THEME_OPTIONS) {
       expect(screen.getByRole("menuitemradio", { name: opt.label })).toBeDefined();
     }
   });
@@ -104,7 +104,7 @@ describe("AppearanceSwitcher", () => {
 
   it("exposes the resolved mode on the trigger when system mode is selected", () => {
     render(
-      <ThemeProvider defaultColorMode="system">
+      <ThemeProvider defaultColorTheme="system">
         <AppearanceSwitcher />
       </ThemeProvider>,
     );
@@ -118,7 +118,7 @@ describe("AppearanceSwitcher", () => {
     const user = userEvent.setup();
 
     render(
-      <ThemeProvider defaultColorMode="light">
+      <ThemeProvider defaultColorTheme="light">
         <AppearanceSwitcher />
       </ThemeProvider>,
     );
@@ -134,6 +134,6 @@ describe("AppearanceSwitcher", () => {
     await waitFor(() => {
       expect(document.documentElement.classList.contains("dark")).toBe(true);
     });
-    expect(localStorage.getItem("appshell-ui-mode")).toBe("dark");
+    expect(localStorage.getItem("appshell-ui-theme")).toBe("dark");
   });
 });
diff --git a/packages/core/src/components/appearance-switcher.tsx b/packages/core/src/components/appearance-switcher.tsx
@@ -4,30 +4,33 @@ import { Menu } from "@/components/menu";
 import { Button } from "@/components/button";
 import { cn } from "@/lib/utils";
 import {
-  useColorMode,
-  type ResolvedColorMode,
-  type ColorMode,
-  COLOR_MODE_OPTIONS,
+  useTheme,
+  type ResolvedColorTheme,
+  type ColorTheme,
+  COLOR_THEME_OPTIONS,
 } from "@/contexts/theme-context";
 
-const RESOLVED_MODE_SHORT: Record<ResolvedColorMode, string> = {
+const RESOLVED_COLOR_THEME_SHORT: Record<ResolvedColorTheme, string> = {
   light: "Light",
   dark: "Dark",
 };
 
 /**
- * Decorative dual swatches for the mode picker. Light/dark show their surface
+ * Decorative dual swatches for the color theme picker. Light/dark show their surface
  * 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<ColorMode, { readonly a: `#${string}`; readonly b: `#${string}` }> = {
+const COLOR_THEME_PREVIEW: Record<
+  ColorTheme,
+  { readonly a: `#${string}`; readonly b: `#${string}` }
+> = {
   light: { a: "#ffffff", b: "#d4d4d8" },
   dark: { a: "#3f3f46", b: "#71717a" },
   system: { a: "#ffffff", b: "#3f3f46" },
 };
 
-function isMode(value: string): value is ColorMode {
-  return COLOR_MODE_OPTIONS.some((o) => o.value === value);
+function isColorTheme(value: string): value is ColorTheme {
+  return COLOR_THEME_OPTIONS.some((o) => o.value === value);
 }
 
 /** Shared radio-item chrome — used by both the mode and font grids. */
@@ -42,8 +45,8 @@ function radioItemClasses(active: boolean) {
   );
 }
 
-function ModePreviewSwatches({ modeId }: { modeId: ColorMode }) {
-  const { a, b } = MODE_PREVIEW[modeId];
+function ColorThemePreviewSwatches({ colorTheme }: { colorTheme: ColorTheme }) {
+  const { a, b } = COLOR_THEME_PREVIEW[colorTheme];
   return (
     <div
       className="astw:flex astw:h-10 astw:w-full astw:max-w-[5.5rem] astw:items-center astw:justify-center astw:gap-1.5 astw:rounded-md astw:border astw:border-border/80 astw:bg-card astw:px-2"
@@ -62,15 +65,15 @@ function ModePreviewSwatches({ modeId }: { modeId: ColorMode }) {
 }
 
 /**
- * Appearance menu. The end-user controls **mode** (light / dark / system);
+ * Appearance menu. The end-user controls **color theme** (light / dark / system);
  * the color palette/brand is a developer configuration, so it is not shown here.
  */
 function AppearanceSwitcher() {
-  const { mode, resolvedMode, setMode } = useColorMode();
+  const { theme, resolvedTheme, setTheme } = useTheme();
 
   const triggerTitle =
-    mode === "system"
-      ? `Following system — currently ${RESOLVED_MODE_SHORT[resolvedMode]}`
+    theme === "system"
+      ? `Following system — currently ${RESOLVED_COLOR_THEME_SHORT[resolvedTheme]}`
       : "Choose appearance";
 
   return (
@@ -97,21 +100,21 @@ function AppearanceSwitcher() {
           <Menu.GroupLabel className="astw:px-0 astw:pb-2 astw:pt-0">Appearance</Menu.GroupLabel>
           <Menu.RadioGroup
             className="astw:grid astw:grid-cols-3 astw:gap-2"
-            value={mode}
+            value={theme}
             onValueChange={(value) => {
-              if (typeof value === "string" && isMode(value)) setMode(value);
+              if (typeof value === "string" && isColorTheme(value)) setTheme(value);
             }}
           >
-            {COLOR_MODE_OPTIONS.map((opt) => (
+            {COLOR_THEME_OPTIONS.map((opt) => (
               <Menu.RadioItem
                 key={opt.value}
                 value={opt.value}
-                className={radioItemClasses(mode === opt.value)}
+                className={radioItemClasses(theme === opt.value)}
               >
                 <Menu.RadioItemIndicator className="astw:sr-only">
                   {opt.label}
                 </Menu.RadioItemIndicator>
-                <ModePreviewSwatches modeId={opt.value} />
+                <ColorThemePreviewSwatches colorTheme={opt.value} />
                 <span className="astw:block astw:w-full astw:truncate astw:px-0.5">
                   {opt.label}
                 </span>
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 ColorMode, type Theme } from "@/contexts/theme-context";
+import { ThemeProvider, type ColorTheme, type ThemePalette } 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";
@@ -179,25 +179,25 @@ type SharedAppShellProps = React.PropsWithChildren<{
   searchSources?: readonly SearchSource[];
 
   /**
-   * Initial color mode before any value is loaded from localStorage (`appshell-ui-mode`).
+   * Initial color mode before any value is loaded from localStorage (`appshell-ui-theme`).
    * This is the end-user accessibility preference; does not replace a stored preference.
    *
    * One of **`light`**, **`dark`**, or **`system`** (follows the OS). Works with any palette.
    *
    * @default "system"
    */
-  defaultColorMode?: ColorMode;
+  defaultColorTheme?: ColorTheme;
 
   /**
    * 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.defaultColorMode}.
+   * variants, so the active variant follows {@link AppShellProps.defaultColorTheme}.
    * This is set by the product (not a user-facing picker), so it is driven by this
    * prop and not persisted to localStorage.
    *
    * @default "default"
    */
-  defaultTheme?: Theme;
+  defaultThemePalette?: ThemePalette;
 }>;
 
 /**
@@ -342,8 +342,8 @@ export const AppShell = (props: AppShellProps) => {
         <BreadcrumbOverrideProvider>
           <CommandPaletteProvider searchSources={props.searchSources}>
             <ThemeProvider
-              defaultColorMode={props.defaultColorMode}
-              defaultTheme={props.defaultTheme}
+              defaultColorTheme={props.defaultColorTheme}
+              defaultThemePalette={props.defaultThemePalette}
             >
               <RouterContainer>
                 {props.children}
diff --git a/packages/core/src/components/sonner.tsx b/packages/core/src/components/sonner.tsx
@@ -1,12 +1,12 @@
-import { useColorMode } from "@/contexts/theme-context";
+import { useTheme } from "@/contexts/theme-context";
 import { Toaster as Sonner, ToasterProps } from "sonner";
 
 const Toaster = ({ ...props }: ToasterProps) => {
-  const { resolvedMode } = useColorMode();
+  const { resolvedTheme } = useTheme();
 
   return (
     <Sonner
-      theme={resolvedMode as ToasterProps["theme"]}
+      theme={resolvedTheme as ToasterProps["theme"]}
       className="astw:toaster astw:group"
       style={
         {
diff --git a/packages/core/src/contexts/theme-context.test.tsx b/packages/core/src/contexts/theme-context.test.tsx
diff --git a/packages/core/src/contexts/theme-context.tsx b/packages/core/src/contexts/theme-context.tsx
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
