diff --git a/apps/web/index.html b/apps/web/index.html
index dadef17d3bc..b608fd0bbff 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -15,23 +15,255 @@
       (() => {
         const LIGHT_BACKGROUND = "#ffffff";
         const DARK_BACKGROUND = "#161616";
-        const themeColorMeta = document.querySelector('meta[name="theme-color"]');
+        const T3_CHAT_BACKGROUND = "#faf5fa";
+        const T3_CHAT_DARK_BACKGROUND = "#180f1b";
+        const T3_GROVE_BACKGROUND = "#f4f8f5";
+        const T3_GROVE_DARK_BACKGROUND = "#111f19";
+        const CUSTOM_THEMES_STORAGE_KEY = "t3code:themes:v1";
+        const THEME_FOLLOW_SYSTEM_STORAGE_KEY = "t3code:theme-follow-system";
+        const SPLASH_COLORS = {
+          light: {
+            background: "#ffffff",
+            foreground: "#262626",
+            accent: "#4f46e5",
+          },
+          dark: {
+            background: "#161616",
+            foreground: "#f5f5f5",
+            accent: "#818cf8",
+          },
+          t3Chat: {
+            background: "#faf5fa",
+            foreground: "#501854",
+            accent: "#a84370",
+          },
+          t3ChatDark: {
+            background: "#180f1b",
+            foreground: "#faeaf9",
+            accent: "#f06cab",
+          },
+          t3Grove: {
+            background: "#f4f8f5",
+            foreground: "#241523",
+            accent: "#1e7d52",
+          },
+          t3GroveDark: {
+            background: "#111f19",
+            foreground: "#fffaff",
+            accent: "#5dd58e",
+          },
+        };
+        // Built-in themes and the modes they can render. T3 Chat is light-only,
+        // so a dark OS must not flip its splash; the runtime resolves the same
+        // way via getThemeColorsForMode.
+        const BUILT_IN_THEME_MODES = {
+          "t3-chat": ["light"],
+          "t3-grove": ["light", "dark"],
+        };
+        const RESERVED_THEME_IDS = [
+          "system",
+          "light",
+          "dark",
+          "t3-chat",
+          "t3-grove",
+          "t3-chat-dark",
+        ];
+        // Update every theme-color meta (including the media-scoped ones) so
+        // the browser picks up the resolved color regardless of which element
+        // its media query matches.
+        const setThemeColor = (color) => {
+          for (const meta of document.querySelectorAll('meta[name="theme-color"]')) {
+            meta.setAttribute("content", color);
+          }
+        };
+
+        const isHexColor = (value) =>
+          typeof value === "string" &&
+          /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value);
+        const isThemePreferenceMode = (value) =>
+          value === "light" || value === "dark" || value === "system";
+        const isThemeAppearance = (value) => value === "light" || value === "dark";
+        const splitThemePreference = (preference) => {
+          const separatorIndex = preference.lastIndexOf(":");
+          if (separatorIndex <= 0) {
+            return { id: preference, mode: null, invalidMode: false };
+          }
+          const rawMode = preference.slice(separatorIndex + 1);
+          return {
+            id: preference.slice(0, separatorIndex),
+            mode: isThemePreferenceMode(rawMode) ? rawMode : null,
+            invalidMode: !isThemePreferenceMode(rawMode),
+          };
+        };
+        const findCustomTheme = (themeId) => {
+          if (RESERVED_THEME_IDS.includes(themeId)) return null;
+          try {
+            const parsed = JSON.parse(
+              window.localStorage.getItem(CUSTOM_THEMES_STORAGE_KEY) ?? "null",
+            );
+            if (!Array.isArray(parsed)) return null;
+            return (
+              parsed.find(
+                (value) =>
+                  value &&
+                  value.id === themeId &&
+                  isThemeAppearance(value.appearance) &&
+                  value.colors,
+              ) ?? null
+            );
+          } catch {
+            return null;
+          }
+        };
+
         try {
           const storedTheme = window.localStorage.getItem("t3code:theme");
-          const theme =
-            storedTheme === "light" || storedTheme === "dark" || storedTheme === "system"
-              ? storedTheme
-              : "system";
           const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
-          const isDark = theme === "dark" || (theme === "system" && prefersDark);
+          const rawPreference = splitThemePreference(storedTheme ?? "");
+          // Older builds stored the dark T3 Chat palette as its own theme id;
+          // the runtime resolves it to the light-only T3 Chat theme.
+          const isLegacyT3ChatDark =
+            !rawPreference.invalidMode && rawPreference.id === "t3-chat-dark";
+          const preference = isLegacyT3ChatDark
+            ? {
+                id: "t3-chat",
+                mode: rawPreference.mode === "system" ? "system" : null,
+                invalidMode: false,
+              }
+            : rawPreference;
+          const explicitMode =
+            preference.mode === "light" || preference.mode === "dark" ? preference.mode : null;
+          const builtInModes = preference.invalidMode
+            ? null
+            : (BUILT_IN_THEME_MODES[preference.id] ?? null);
+          const customTheme =
+            preference.invalidMode || builtInModes ? null : findCustomTheme(preference.id);
+          const themeModes =
+            builtInModes ??
+            (customTheme
+              ? ["light", "dark"].filter(
+                  (mode) => mode === customTheme.appearance || customTheme.variants?.[mode],
+                )
+              : null);
+          // Mirrors the runtime's isKnownThemePreference: an explicit mode the
+          // theme cannot render makes the whole preference unknown, and the
+          // runtime falls back to the system default.
+          const isKnownTheme =
+            storedTheme === "light" ||
+            storedTheme === "dark" ||
+            storedTheme === "system" ||
+            (themeModes !== null && (explicitMode === null || themeModes.includes(explicitMode)));
+          const theme = isKnownTheme && storedTheme ? storedTheme : "system";
+          const storedFollowSystem = window.localStorage.getItem(THEME_FOLLOW_SYSTEM_STORAGE_KEY);
+          const followSystem =
+            storedFollowSystem === "true"
+              ? true
+              : storedFollowSystem === "false"
+                ? false
+                : theme === "system" || preference.mode === "system";
+          const isThemed = isKnownTheme && themeModes !== null;
+          const baseAppearance = customTheme ? customTheme.appearance : "light";
+          const systemMode = prefersDark ? "dark" : "light";
+          // followSystem already accounts for a `:system` suffix when the
+          // follow-system key is unset; when that key is explicitly "false"
+          // the runtime ignores the suffix, so the boot script must too.
+          const themeMode = !isThemed
+            ? null
+            : followSystem
+              ? themeModes.includes(systemMode)
+                ? systemMode
+                : baseAppearance
+              : (explicitMode ?? baseAppearance);
+          const isDark = isThemed
+            ? themeMode === "dark"
+            : followSystem
+              ? prefersDark
+              : theme === "dark";
+          const customColors =
+            isThemed && customTheme
+              ? themeMode === customTheme.appearance
+                ? customTheme.colors
+                : (customTheme.variants?.[themeMode] ?? customTheme.colors)
+              : null;
+          // The runtime tolerates individual malformed colors, so fall back
+          // per role rather than dropping the theme.
+          const customSplash = customColors
+            ? {
+                background: isHexColor(customColors.canvas)
+                  ? customColors.canvas
+                  : themeMode === "dark"
+                    ? SPLASH_COLORS.t3ChatDark.background
+                    : SPLASH_COLORS.t3Chat.background,
+                foreground: isHexColor(customColors.text)
+                  ? customColors.text
+                  : themeMode === "dark"
+                    ? SPLASH_COLORS.t3ChatDark.foreground
+                    : SPLASH_COLORS.t3Chat.foreground,
+                accent: isHexColor(customColors.accent)
+                  ? customColors.accent
+                  : themeMode === "dark"
+                    ? SPLASH_COLORS.t3ChatDark.accent
+                    : SPLASH_COLORS.t3Chat.accent,
+              }
+            : null;
+          if (isThemed) {
+            document.documentElement.dataset.themeId = customTheme ? customTheme.id : preference.id;
+          } else {
+            delete document.documentElement.dataset.themeId;
+          }
+          if (isKnownTheme && storedTheme !== null) {
+            document.documentElement.dataset.themeSelected = "true";
+          } else {
+            delete document.documentElement.dataset.themeSelected;
+          }
           document.documentElement.classList.toggle("dark", isDark);
-          const chromeColor = isDark ? DARK_BACKGROUND : LIGHT_BACKGROUND;
+          const chromeColor = customSplash
+            ? customSplash.background
+            : isThemed
+              ? themeMode === "dark"
+                ? preference.id === "t3-grove"
+                  ? T3_GROVE_DARK_BACKGROUND
+                  : T3_CHAT_DARK_BACKGROUND
+                : preference.id === "t3-grove"
+                  ? T3_GROVE_BACKGROUND
+                  : T3_CHAT_BACKGROUND
+              : isDark
+                ? DARK_BACKGROUND
+                : LIGHT_BACKGROUND;
           document.documentElement.style.backgroundColor = chromeColor;
-          themeColorMeta?.setAttribute("content", chromeColor);
+          if (isKnownTheme && storedTheme !== null) {
+            const splashColors =
+              customSplash ??
+              (isThemed
+                ? preference.id === "t3-grove"
+                  ? themeMode === "dark"
+                    ? SPLASH_COLORS.t3GroveDark
+                    : SPLASH_COLORS.t3Grove
+                  : themeMode === "dark"
+                    ? SPLASH_COLORS.t3ChatDark
+                    : SPLASH_COLORS.t3Chat
+                : isDark
+                  ? SPLASH_COLORS.dark
+                  : SPLASH_COLORS.light);
+            for (const [name, value] of Object.entries(splashColors)) {
+              document.documentElement.style.setProperty(`--boot-${name}`, value);
+            }
+          }
+          setThemeColor(chromeColor);
         } catch {
-          document.documentElement.classList.add("dark");
-          document.documentElement.style.backgroundColor = DARK_BACKGROUND;
-          themeColorMeta?.setAttribute("content", DARK_BACKGROUND);
+          // Mirror the runtime's storage-failure fallback: follow the OS.
+          let prefersDark = true;
+          try {
+            prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+          } catch {
+            // Keep the dark default when even matchMedia is unavailable.
+          }
+          delete document.documentElement.dataset.themeId;
+          delete document.documentElement.dataset.themeSelected;
+          document.documentElement.classList.toggle("dark", prefersDark);
+          const fallbackColor = prefersDark ? DARK_BACKGROUND : LIGHT_BACKGROUND;
+          document.documentElement.style.backgroundColor = fallbackColor;
+          setThemeColor(fallbackColor);
         }
       })();
     </script>
@@ -63,14 +295,35 @@
       }
 
       #boot-shell {
+        position: relative;
+        overflow: hidden;
         display: flex;
         min-height: 100%;
         align-items: center;
         justify-content: center;
         background: inherit;
+        color: inherit;
+      }
+
+      html[data-theme-selected="true"] #boot-shell {
+        background: var(--boot-background);
+        color: var(--boot-foreground);
+      }
+
+      html[data-theme-selected="true"] #boot-shell::before {
+        position: absolute;
+        inset: -20%;
+        content: "";
+        background: radial-gradient(
+          circle at 50% 38%,
+          color-mix(in srgb, var(--boot-accent) 18%, transparent),
+          transparent 42%
+        );
       }
 
       #boot-shell-card {
+        position: relative;
+        z-index: 1;
         display: flex;
         align-items: center;
         justify-content: center;
diff --git a/apps/web/src/components/CommandPalette.logic.ts b/apps/web/src/components/CommandPalette.logic.ts
index eee6ba5886e..c9ded5e7eee 100644
--- a/apps/web/src/components/CommandPalette.logic.ts
+++ b/apps/web/src/components/CommandPalette.logic.ts
@@ -12,7 +12,7 @@ import { formatRelativeTimeLabel } from "../timestampFormat";
 import { type Project, type SidebarThreadSummary, type Thread } from "../types";
 
 export const RECENT_THREAD_LIMIT = 12;
-export const ITEM_ICON_CLASS = "size-4 text-muted-foreground/80";
+export const ITEM_ICON_CLASS = "size-4 text-icon-muted";
 export const ADDON_ICON_CLASS = "size-4";
 
 /**
diff --git a/apps/web/src/components/ComposerPromptEditor.tsx b/apps/web/src/components/ComposerPromptEditor.tsx
index 169126788ae..078fc130297 100644
--- a/apps/web/src/components/ComposerPromptEditor.tsx
+++ b/apps/web/src/components/ComposerPromptEditor.tsx
@@ -1763,7 +1763,7 @@ function ComposerPromptEditorInner({
           }
           placeholder={
             terminalContexts.length > 0 ? null : (
-              <div className="pointer-events-none absolute inset-0 text-[16px] leading-relaxed text-muted-foreground/35 sm:text-[14px]">
+              <div className="pointer-events-none absolute inset-0 text-[16px] leading-relaxed text-placeholder sm:text-[14px]">
                 {placeholder}
               </div>
             )
diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index d10cb39f0e3..a1d96231c3e 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -91,9 +91,9 @@ const DIFF_PANEL_UNSAFE_CSS = `
 [data-virtualizer-buffer] {
   --diffs-header-font-family: var(--font-sans) !important;
   --diffs-font-family: var(--font-mono) !important;
-  --diffs-bg: color-mix(in srgb, var(--card) 90%, var(--background)) !important;
-  --diffs-light-bg: color-mix(in srgb, var(--card) 90%, var(--background)) !important;
-  --diffs-dark-bg: color-mix(in srgb, var(--card) 90%, var(--background)) !important;
+  --diffs-bg: var(--code-background) !important;
+  --diffs-light-bg: var(--code-background) !important;
+  --diffs-dark-bg: var(--code-background) !important;
   --diffs-token-light-bg: transparent;
   --diffs-token-dark-bg: transparent;
 
@@ -117,19 +117,20 @@ const DIFF_PANEL_UNSAFE_CSS = `
   );
 
   background-color: var(--diffs-bg) !important;
+  color: var(--code-foreground) !important;
 }
 
 [data-file-info] {
-  background-color: color-mix(in srgb, var(--card) 94%, var(--foreground)) !important;
+  background-color: color-mix(in srgb, var(--code-background) 94%, var(--code-foreground)) !important;
   border-block-color: var(--border) !important;
-  color: var(--foreground) !important;
+  color: var(--code-foreground) !important;
 }
 
 [data-diffs-header] {
   position: sticky !important;
   top: 0;
   z-index: 4;
-  background-color: color-mix(in srgb, var(--card) 94%, var(--foreground)) !important;
+  background-color: color-mix(in srgb, var(--code-background) 94%, var(--code-foreground)) !important;
   border-bottom: 1px solid var(--border) !important;
   align-items: center !important;
   font-family: var(--font-sans) !important;
@@ -838,7 +839,7 @@ export default function DiffPanel({
             )}
             {selectedPatchError && !renderablePatch && (
               <div className="px-3">
-                <p className="mb-2 text-[11px] text-red-500/80">{selectedPatchError}</p>
+                <p className="mb-2 text-[11px] text-error/80">{selectedPatchError}</p>
               </div>
             )}
             {!renderablePatch ? (
diff --git a/apps/web/src/components/ProjectFavicon.tsx b/apps/web/src/components/ProjectFavicon.tsx
index 1df19a64075..66216e10cb5 100644
--- a/apps/web/src/components/ProjectFavicon.tsx
+++ b/apps/web/src/components/ProjectFavicon.tsx
@@ -47,7 +47,7 @@ function ProjectFaviconFallback({
   readonly className?: string | undefined;
   readonly icon: ComponentType<{ className?: string }>;
 }) {
-  return <Icon className={cn("size-3.5 shrink-0 text-muted-foreground/50", className)} />;
+  return <Icon className={cn("size-3.5 shrink-0 text-icon-muted", className)} />;
 }
 
 function ProjectFaviconImage({
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index cffab8bd577..00c9795b935 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -225,7 +225,7 @@ const PROJECT_GROUPING_MODE_LABELS: Record<SidebarProjectGroupingMode, string> =
   separate: "Keep separate",
 };
 const SIDEBAR_ICON_ACTION_BUTTON_CLASS =
-  "inline-flex h-6 min-w-6 cursor-pointer items-center justify-center rounded-md px-[calc(--spacing(1)-1px)] text-muted-foreground/60 hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring";
+  "inline-flex h-6 min-w-6 cursor-pointer items-center justify-center rounded-md px-[calc(--spacing(1)-1px)] text-icon-muted hover:text-foreground focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring";
 
 function SidebarThreadDetailPrewarmer({ threadRef }: { readonly threadRef: ScopedThreadRef }) {
   useEnvironmentThread(threadRef.environmentId, threadRef.threadId);
@@ -857,9 +857,7 @@ export const SidebarThreadRow = memo(function SidebarThreadRow(props: SidebarThr
                 ) : (
                   <span
                     className={`text-[10px] tabular-nums ${
-                      isHighlighted
-                        ? "text-foreground/72 dark:text-foreground/82"
-                        : "text-muted-foreground/40"
+                      isHighlighted ? "text-foreground" : "text-secondary-label"
                     }`}
                   >
                     {formatRelativeTimeLabel(
@@ -2245,7 +2243,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
                     }`}
                   />
                 </span>
-                <ChevronRightIcon className="absolute inset-0 m-auto size-3.5 text-muted-foreground/70 opacity-0 transition-opacity duration-150 group-hover/project-header:opacity-100" />
+                <ChevronRightIcon className="absolute inset-0 m-auto size-3.5 text-icon-muted opacity-0 transition-opacity duration-150 group-hover/project-header:opacity-100" />
               </TooltipTrigger>
               <TooltipPopup side="top">{projectStatus.label}</TooltipPopup>
             </Tooltip>
@@ -2262,7 +2260,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
               {project.displayName}
             </span>
             {project.groupedProjectCount > 1 ? (
-              <span className="shrink-0 text-[10px] text-muted-foreground/60">
+              <span className="shrink-0 text-secondary-label text-[10px]">
                 {project.groupedProjectCount} projects
               </span>
             ) : null}
@@ -2281,7 +2279,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
                       ? "Local sandbox project"
                       : "Remote project"
                   }
-                  className="pointer-events-none absolute top-1 right-1.5 inline-flex size-5 items-center justify-center rounded-md text-muted-foreground/60 transition-opacity duration-150 max-sm:right-7 group-hover/project-header:opacity-0 group-focus-within/project-header:opacity-0 max-sm:group-hover/project-header:opacity-100 max-sm:group-focus-within/project-header:opacity-100"
+                  className="pointer-events-none absolute top-1 right-1.5 inline-flex size-5 items-center justify-center rounded-md text-icon-muted transition-opacity duration-150 max-sm:right-7 group-hover/project-header:opacity-0 group-focus-within/project-header:opacity-0 max-sm:group-hover/project-header:opacity-100 max-sm:group-focus-within/project-header:opacity-100"
                 />
               }
             >
@@ -2600,7 +2598,7 @@ function ProjectSortMenu({
       <Tooltip>
         <TooltipTrigger
           render={
-            <MenuTrigger className="inline-flex h-6 min-w-6 cursor-pointer items-center justify-center rounded-md px-[calc(--spacing(1)-1px)] text-muted-foreground/60 transition-colors hover:bg-accent hover:text-foreground" />
+            <MenuTrigger className="inline-flex h-6 min-w-6 cursor-pointer items-center justify-center rounded-md px-[calc(--spacing(1)-1px)] text-icon-muted transition-colors hover:bg-accent hover:text-foreground" />
           }
         >
           <ArrowUpDownIcon className="size-3.5" />
@@ -2891,7 +2889,7 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
                     type="button"
                     aria-label="Add project"
                     data-testid="sidebar-add-project-trigger"
-                    className="inline-flex h-6 min-w-6 cursor-pointer items-center justify-center rounded-md px-[calc(--spacing(1)-1px)] text-muted-foreground/60 transition-colors hover:bg-accent hover:text-foreground"
+                    className="inline-flex h-6 min-w-6 cursor-pointer items-center justify-center rounded-md px-[calc(--spacing(1)-1px)] text-icon-muted transition-colors hover:bg-accent hover:text-foreground"
                     onClick={openAddProject}
                   />
                 }
@@ -2977,9 +2975,7 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
         )}
 
         {projectsLength === 0 && (
-          <div className="px-2 pt-4 text-center text-xs text-muted-foreground/60">
-            No projects yet
-          </div>
+          <div className="px-2 pt-4 text-center text-secondary-label text-xs">No projects yet</div>
         )}
       </SidebarGroup>
     </SidebarContent>
diff --git a/apps/web/src/components/SidebarStageBackdrop.test.tsx b/apps/web/src/components/SidebarStageBackdrop.test.tsx
index 114fd5f9241..c34eec58316 100644
--- a/apps/web/src/components/SidebarStageBackdrop.test.tsx
+++ b/apps/web/src/components/SidebarStageBackdrop.test.tsx
@@ -5,7 +5,6 @@ import {
   resolveEnvironmentIdentificationPillLabel,
   resolveSidebarStageBackdropVariant,
   StageBackdropArt,
-  StageBackdropButtonArt,
 } from "./SidebarStageBackdrop";
 
 describe("SidebarStageBackdrop", () => {
@@ -29,7 +28,7 @@ describe("SidebarStageBackdrop", () => {
       const markup = renderToStaticMarkup(
         <>
           <StageBackdropArt variant={variant} />
-          <StageBackdropButtonArt variant={variant} />
+          <StageBackdropArt variant={variant} />
         </>,
       );
       const ids = Array.from(markup.matchAll(/\sid="([^"]+)"/g), (match) => match[1]);
diff --git a/apps/web/src/components/SidebarStageBackdrop.tsx b/apps/web/src/components/SidebarStageBackdrop.tsx
index 9fb448e940d..ee669e94bd4 100644
--- a/apps/web/src/components/SidebarStageBackdrop.tsx
+++ b/apps/web/src/components/SidebarStageBackdrop.tsx
@@ -62,10 +62,6 @@ export function StageBackdropArt({ variant }: { variant: SidebarStageBackdropVar
   return variant === "nightly" ? <NightlySkyArt /> : <DevBlueprintArt />;
 }
 
-export function StageBackdropButtonArt({ variant }: { variant: SidebarStageBackdropVariant }) {
-  return variant === "nightly" ? <NightlySkyArt compact /> : <DevBlueprintArt compact />;
-}
-
 const NIGHTLY_STARS: ReadonlyArray<{
   cx: number;
   cy: number;
@@ -97,7 +93,7 @@ const NIGHTLY_SPARKLES: ReadonlyArray<{ x: number; y: number }> = [
   { x: 246, y: 26 },
 ];
 
-function NightlySkyArt({ compact = false }: { compact?: boolean }) {
+function NightlySkyArt() {
   const idPrefix = useId().replaceAll(":", "");
   const skyId = `${idPrefix}-stage-night-sky`;
   const glowId = `${idPrefix}-stage-night-glow`;
@@ -111,7 +107,7 @@ function NightlySkyArt({ compact = false }: { compact?: boolean }) {
       className="h-full w-full"
       fill="none"
       preserveAspectRatio="xMinYMin slice"
-      viewBox={compact ? "96 0 8192 96" : STAGE_BACKDROP_VIEW_BOX}
+      viewBox={STAGE_BACKDROP_VIEW_BOX}
       xmlns="http://www.w3.org/2000/svg"
     >
       <defs>
@@ -195,7 +191,7 @@ function NightlySkyArt({ compact = false }: { compact?: boolean }) {
   );
 }
 
-function DevBlueprintArt({ compact = false }: { compact?: boolean }) {
+function DevBlueprintArt() {
   const idPrefix = useId().replaceAll(":", "");
   const paperId = `${idPrefix}-stage-bp-paper`;
   const glowId = `${idPrefix}-stage-bp-glow`;
@@ -212,7 +208,7 @@ function DevBlueprintArt({ compact = false }: { compact?: boolean }) {
       className="stage-blueprint h-full w-full"
       fill="none"
       preserveAspectRatio="xMinYMin slice"
-      viewBox={compact ? "64 0 8192 96" : STAGE_BACKDROP_VIEW_BOX}
+      viewBox={STAGE_BACKDROP_VIEW_BOX}
       xmlns="http://www.w3.org/2000/svg"
     >
       <defs>
diff --git a/apps/web/src/components/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
index 9e86e5fb6b4..377c6f419ed 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -731,7 +731,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
               isUnread || isWoke
                 ? "text-foreground"
                 : shouldRecede
-                  ? "text-muted-foreground/80"
+                  ? "text-secondary-label"
                   : status === "failed"
                     ? "text-foreground/95"
                     : "text-foreground/90",
@@ -742,7 +742,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                 ? "text-foreground"
                 : isUnread
                   ? "text-muted-foreground"
-                  : "text-muted-foreground/70",
+                  : "text-secondary-label/70",
             ),
         isRegeneratingTitle && "opacity-[0.55]",
       )}
@@ -760,8 +760,8 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
           "shrink-0 font-mono text-xs hover:underline",
           variant === "slim" && variantAction === "unsettle"
             ? props.isActive
-              ? "text-muted-foreground/70"
-              : cn("text-muted-foreground/35 transition-colors", settledPrHoverClass)
+              ? "text-secondary-label"
+              : cn("text-secondary-label transition-colors", settledPrHoverClass)
             : prStatus.colorClass,
         )}
         aria-label={prStatus.tooltip}
@@ -830,7 +830,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
               the time/jump label yields to the settle affordance. */}
             {prBadge}
             <span className="relative ml-auto flex h-6 min-w-8 shrink-0 items-center justify-end">
-              <span className="inline-flex justify-end tabular-nums text-muted-foreground/55 transition-opacity group-hover/v2-row:opacity-0">
+              <span className="inline-flex justify-end tabular-nums text-secondary-label transition-opacity group-hover/v2-row:opacity-0">
                 {variantAction === "unsnooze" && props.snoozeWakeLabelText !== null ? (
                   // Snoozed rows show when they come BACK, not when they were
                   // last touched — the return ticket is the row's whole story.
@@ -928,7 +928,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
               {props.projectTitle ? (
                 <span
                   className={cn(
-                    "min-w-0 flex-1 truncate text-xs text-muted-foreground/85",
+                    "min-w-0 flex-1 truncate text-secondary-label text-xs",
                     shouldRecede ? "font-normal" : "font-medium",
                   )}
                 >
@@ -947,7 +947,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                     buttons; without it the invisible label eats their clicks. */}
                 <span
                   className={cn(
-                    "pointer-events-none self-center justify-self-end tabular-nums text-muted-foreground/65 transition-opacity group-has-[:focus-visible]/v2-status-slot:absolute group-has-[:focus-visible]/v2-status-slot:right-0 group-has-[:focus-visible]/v2-status-slot:opacity-0 group-hover/v2-row:absolute group-hover/v2-row:right-0 group-hover/v2-row:opacity-0",
+                    "pointer-events-none self-center justify-self-end tabular-nums text-secondary-label transition-opacity group-has-[:focus-visible]/v2-status-slot:absolute group-has-[:focus-visible]/v2-status-slot:right-0 group-has-[:focus-visible]/v2-status-slot:opacity-0 group-hover/v2-row:absolute group-hover/v2-row:right-0 group-hover/v2-row:opacity-0",
                     snoozeMenuOpen && "absolute right-0 opacity-0",
                   )}
                 >
@@ -1021,7 +1021,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                 </span>
               ) : null}
             </div>
-            <div className="mt-0.5 flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground/75">
+            <div className="mt-0.5 flex min-w-0 items-center gap-1.5 text-secondary-label text-xs">
               {thread.branch ? (
                 <span className="min-w-0 flex-1 truncate whitespace-nowrap">{thread.branch}</span>
               ) : (
@@ -2726,7 +2726,7 @@ export default function SidebarV2() {
                               type="button"
                               aria-label={`Project actions for ${project.displayName}`}
                               title={`Project actions for ${project.displayName}`}
-                              className="ml-auto inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground/55 outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:bg-accent focus-visible:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+                              className="ml-auto inline-flex size-6 shrink-0 cursor-pointer items-center justify-center rounded-md text-icon-muted outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:bg-accent focus-visible:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
                               onPointerDown={(event) => event.stopPropagation()}
                               onClick={(event) => {
                                 void handleProjectActions(event, project);
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index dd7da738626..51fc14cad5a 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -131,6 +131,10 @@ function normalizeComputedColor(value: string | null | undefined, fallback: stri
   return value ?? fallback;
 }
 
+function readThemeColor(styles: CSSStyleDeclaration, variable: string, fallback: string): string {
+  return normalizeComputedColor(styles.getPropertyValue(variable), fallback);
+}
+
 function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
   const isDark = document.documentElement.classList.contains("dark");
   const fallbackBackground = isDark ? "rgb(14, 18, 24)" : "rgb(255, 255, 255)";
@@ -141,6 +145,7 @@ function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
     document.body;
   const drawerStyles = getComputedStyle(drawerSurface);
   const bodyStyles = getComputedStyle(document.body);
+  const themeStyles = getComputedStyle(document.documentElement);
   const background = normalizeComputedColor(
     drawerStyles.backgroundColor,
     normalizeComputedColor(bodyStyles.backgroundColor, fallbackBackground),
@@ -149,20 +154,32 @@ function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
     drawerStyles.color,
     normalizeComputedColor(bodyStyles.color, fallbackForeground),
   );
-
+  const terminalBackground = readThemeColor(themeStyles, "--terminal-background", background);
+  const terminalForeground = readThemeColor(themeStyles, "--terminal-foreground", foreground);
+  const terminalCursor = readThemeColor(
+    themeStyles,
+    "--terminal-cursor",
+    isDark ? "rgb(180, 203, 255)" : "rgb(38, 56, 78)",
+  );
+  const terminalSelection = readThemeColor(
+    themeStyles,
+    "--terminal-selection-background",
+    isDark ? "rgba(180, 203, 255, 0.25)" : "rgba(37, 63, 99, 0.2)",
+  );
   return {
     background: parseTerminalColor(
-      background,
+      terminalBackground,
       isDark ? { r: 14, g: 18, b: 24 } : { r: 255, g: 255, b: 255 },
     ),
     foreground: parseTerminalColor(
-      foreground,
+      terminalForeground,
       isDark ? { r: 237, g: 241, b: 247 } : { r: 28, g: 33, b: 41 },
     ),
-    cursor: isDark ? { r: 180, g: 203, b: 255 } : { r: 38, g: 56, b: 78 },
-    // Matches the xterm selection overlays this renderer replaced; the text
-    // color underneath is left unchanged for contrast in both themes.
-    selectionBackground: isDark ? "rgba(180, 203, 255, 0.25)" : "rgba(37, 63, 99, 0.2)",
+    cursor: parseTerminalColor(
+      terminalCursor,
+      isDark ? { r: 180, g: 203, b: 255 } : { r: 38, g: 56, b: 78 },
+    ),
+    selectionBackground: terminalSelection,
   };
 }
 
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index c26f52cbc0c..1d931c42118 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -304,8 +304,8 @@ const ComposerFooterModeControls = memo(function ComposerFooterModeControls(prop
               className={cn(
                 "shrink-0 whitespace-nowrap",
                 props.interactionMode === "plan"
-                  ? "bg-blue-500/10 text-blue-400 hover:bg-blue-500/15 hover:text-blue-300"
-                  : "text-muted-foreground/70 hover:text-foreground/80",
+                  ? "bg-accent text-accent-foreground hover:bg-accent/80"
+                  : "text-secondary-label hover:text-foreground",
               )}
               type="button"
               onClick={props.onToggleInteractionMode}
@@ -379,8 +379,8 @@ const ComposerFooterModeControls = memo(function ComposerFooterModeControls(prop
                   className={cn(
                     "shrink-0 whitespace-nowrap",
                     props.planSidebarOpen
-                      ? "bg-blue-500/10 text-blue-400 hover:bg-blue-500/15 hover:text-blue-300"
-                      : "text-muted-foreground/70 hover:text-foreground/80",
+                      ? "bg-primary/10 text-primary hover:bg-primary/15"
+                      : "text-secondary-label hover:text-foreground",
                   )}
                   type="button"
                   onClick={props.onTogglePlanSidebar}
@@ -436,7 +436,7 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
         />
       ) : null}
       {props.isPreparingWorktree ? (
-        <span className="text-muted-foreground/70 text-xs">Preparing worktree...</span>
+        <span className="text-secondary-label text-xs">Preparing worktree...</span>
       ) : null}
       <ComposerPrimaryActions
         compact={props.compact}
@@ -2781,9 +2781,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
                     type="button"
                     className={cn(
                       "min-w-0 flex-1 truncate bg-transparent py-1.5 text-left text-sm",
-                      activePendingProgress?.customAnswer
-                        ? "text-foreground"
-                        : "text-muted-foreground/60",
+                      activePendingProgress?.customAnswer ? "text-foreground" : "text-placeholder",
                       !activePendingProgress?.activeQuestion?.multiSelect && "px-3 py-2",
                     )}
                     onPointerDown={(event) => event.preventDefault()}
@@ -2828,7 +2826,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
                   "min-w-0 flex-1 truncate bg-transparent p-0 text-left text-[14px] focus:outline-none",
                   (activePendingProgress ? activePendingProgress.customAnswer : prompt.trim())
                     ? "text-foreground"
-                    : "text-muted-foreground/35",
+                    : "text-placeholder",
                 )}
                 onPointerDown={(event) => event.preventDefault()}
                 onClick={expandMobileComposer}
@@ -2842,7 +2840,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
               </button>
               <button
                 type="button"
-                className="flex size-8 shrink-0 items-center justify-center rounded-full bg-primary/90 text-primary-foreground disabled:opacity-30"
+                className="flex size-8 shrink-0 items-center justify-center rounded-full bg-message-action text-message-action-foreground hover:bg-message-action-hover disabled:opacity-30"
                 disabled={collapsedComposerPrimaryActionDisabled}
                 aria-label={collapsedComposerPrimaryActionLabel}
                 onPointerDown={(event) => event.preventDefault()}
@@ -2992,7 +2990,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
                             />
                           </button>
                         ) : (
-                          <div className="flex h-full w-full items-center justify-center px-1 text-center text-[10px] text-muted-foreground/70">
+                          <div className="flex h-full w-full items-center justify-center px-1 text-center text-[10px] text-secondary-label">
                             {image.name}
                           </div>
                         )}
@@ -3130,7 +3128,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
                     variant="ghost"
                     disabled
                     data-chat-provider-unavailable="true"
-                    className="shrink-0 gap-2 px-2 text-muted-foreground/70 sm:px-3"
+                    className="shrink-0 gap-2 px-2 text-secondary-label sm:px-3"
                   >
                     <CircleAlertIcon className="size-4" />
                     No provider available
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
index 0adeed6ffa6..b11e2136770 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -114,7 +114,7 @@ export const ChatHeader = memo(function ChatHeader({
               </TooltipTrigger>
               <TooltipPopup side="top">New thread in {activeProjectName}</TooltipPopup>
             </Tooltip>
-            <span aria-hidden className="text-muted-foreground/40">
+            <span aria-hidden className="text-icon-muted">
               /
             </span>
           </span>
diff --git a/apps/web/src/components/chat/ComposerCommandMenu.tsx b/apps/web/src/components/chat/ComposerCommandMenu.tsx
index 73fc6348905..3ed2a9432e4 100644
--- a/apps/web/src/components/chat/ComposerCommandMenu.tsx
+++ b/apps/web/src/components/chat/ComposerCommandMenu.tsx
@@ -150,7 +150,7 @@ export const ComposerCommandMenu = memo(function ComposerCommandMenu(props: {
                 {groupIndex > 0 ? <CommandSeparator className="my-0.5" /> : null}
                 <CommandGroup>
                   {group.label ? (
-                    <CommandGroupLabel className="px-3 pt-2 pb-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/55">
+                    <CommandGroupLabel className="px-3 pt-2 pb-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-secondary-label">
                       {group.label}
                     </CommandGroupLabel>
                   ) : null}
@@ -172,10 +172,10 @@ export const ComposerCommandMenu = memo(function ComposerCommandMenu(props: {
           <div className="px-5 py-3.5">
             {props.triggerKind === "skill" ? (
               <CommandGroup>
-                <CommandGroupLabel className="px-0 pt-0 pb-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/55">
+                <CommandGroupLabel className="px-0 pt-0 pb-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-secondary-label">
                   Skills
                 </CommandGroupLabel>
-                <p className="text-muted-foreground/70 text-xs">
+                <p className="text-secondary-label text-xs">
                   {props.isLoading
                     ? "Searching workspace skills..."
                     : (props.emptyStateText ??
@@ -183,7 +183,7 @@ export const ComposerCommandMenu = memo(function ComposerCommandMenu(props: {
                 </p>
               </CommandGroup>
             ) : (
-              <p className="text-muted-foreground/70 text-xs">
+              <p className="text-secondary-label text-xs">
                 {props.isLoading
                   ? "Searching workspace files..."
                   : (props.emptyStateText ??
@@ -235,26 +235,26 @@ const ComposerCommandMenuItem = memo(function ComposerCommandMenuItem(props: {
         />
       ) : null}
       {props.item.type === "slash-command" ? (
-        <BotIcon className="size-4 shrink-0 text-muted-foreground/80" />
+        <BotIcon className="size-4 shrink-0 text-icon-muted" />
       ) : null}
       {props.item.type === "provider-slash-command" ? (
-        <span className="inline-flex size-4 shrink-0 items-center justify-center text-muted-foreground/80">
+        <span className="inline-flex size-4 shrink-0 items-center justify-center text-icon-muted">
           <SkillGlyph className="size-3.5" />
         </span>
       ) : null}
       {props.item.type === "skill" ? (
-        <span className="inline-flex size-4 shrink-0 items-center justify-center text-muted-foreground/80">
+        <span className="inline-flex size-4 shrink-0 items-center justify-center text-icon-muted">
           <SkillGlyph className="size-3.5" />
         </span>
       ) : null}
       <span className="flex min-w-0 flex-1 items-center gap-2">
         <span className="shrink-0">{props.item.label}</span>
-        <span className="min-w-0 flex-1 truncate text-muted-foreground/70 text-xs">
+        <span className="min-w-0 flex-1 truncate text-secondary-label text-xs">
           {props.item.description}
         </span>
       </span>
       {skillSourceLabel ? (
-        <span className="shrink-0 pl-2 text-muted-foreground/70 text-xs">{skillSourceLabel}</span>
+        <span className="shrink-0 pl-2 text-secondary-label text-xs">{skillSourceLabel}</span>
       ) : null}
     </CommandItem>
   );
diff --git a/apps/web/src/components/chat/ComposerControl.tsx b/apps/web/src/components/chat/ComposerControl.tsx
index 8eab75171c8..a7ba4058145 100644
--- a/apps/web/src/components/chat/ComposerControl.tsx
+++ b/apps/web/src/components/chat/ComposerControl.tsx
@@ -6,7 +6,7 @@ import { Button } from "../ui/button";
 import { SelectTrigger } from "../ui/select";
 
 const composerControlClassName =
-  "h-7 min-h-7 gap-1.5 px-2.5 text-muted-foreground/70 transition-none hover:text-foreground/80 [&_svg[data-composer-control-icon]]:mx-0 [&_svg[data-composer-control-chevron]]:-mx-0.5";
+  "h-7 min-h-7 gap-1.5 px-2.5 text-secondary-label transition-none hover:text-foreground [&_svg[data-composer-control-icon]]:mx-0 [&_svg[data-composer-control-chevron]]:-mx-0.5";
 
 export function ComposerControl({
   className,
@@ -46,7 +46,7 @@ export function ComposerControlChevron() {
   return (
     <ChevronDownIcon
       aria-hidden="true"
-      className="-mx-0.5 size-3.5 shrink-0 text-muted-foreground opacity-70"
+      className="-mx-0.5 size-3.5 shrink-0 text-icon-muted"
       data-composer-control-chevron
       strokeWidth={2.25}
     />
diff --git a/apps/web/src/components/chat/ComposerPendingUserInputPanel.tsx b/apps/web/src/components/chat/ComposerPendingUserInputPanel.tsx
index bd02a91b248..ceac45c9411 100644
--- a/apps/web/src/components/chat/ComposerPendingUserInputPanel.tsx
+++ b/apps/web/src/components/chat/ComposerPendingUserInputPanel.tsx
@@ -155,18 +155,18 @@ const ComposerPendingUserInputCard = memo(function ComposerPendingUserInputCard(
   return (
     <div className="px-4 py-3 sm:px-5">
       <div className="mb-2 flex items-center gap-3">
-        <span className="text-[11px] font-semibold tracking-widest text-muted-foreground/55 uppercase">
+        <span className="text-secondary-label text-[11px] font-semibold tracking-widest uppercase">
           {activeQuestion.header}
         </span>
         {prompt.questions.length > 1 ? (
-          <span className="flex h-5 items-center rounded-md bg-muted/60 px-1.5 text-[10px] font-medium tabular-nums text-muted-foreground/60">
+          <span className="flex h-5 items-center rounded-md bg-muted/60 px-1.5 text-secondary-label text-[10px] font-medium tabular-nums">
             {questionIndex + 1}/{prompt.questions.length}
           </span>
         ) : null}
       </div>
       <p className="text-sm text-foreground/90">{activeQuestion.question}</p>
       {activeQuestion.multiSelect ? (
-        <p className="mt-1 text-xs text-muted-foreground/65">Select one or more options.</p>
+        <p className="mt-1 text-secondary-label text-xs">Select one or more options.</p>
       ) : null}
       <div className="mt-3 space-y-1.5">
         {activeQuestion.options.map((option, index) => {
@@ -190,7 +190,7 @@ const ComposerPendingUserInputCard = memo(function ComposerPendingUserInputCard(
               <div className="min-w-0 flex-1 flex flex-col gap-0.5">
                 <span className="text-sm font-medium">{option.label}</span>
                 {option.description && option.description !== option.label ? (
-                  <span className="text-xs text-muted-foreground">{option.description}</span>
+                  <span className="text-secondary-label text-xs">{option.description}</span>
                 ) : null}
               </div>
               {isSelected ? (
@@ -199,7 +199,7 @@ const ComposerPendingUserInputCard = memo(function ComposerPendingUserInputCard(
                 <kbd
                   className={cn(
                     "flex size-5 shrink-0 items-center justify-center rounded border border-border/50 text-[11px] font-medium tabular-nums transition-colors duration-150",
-                    "bg-background/35 text-muted-foreground/70 group-hover:border-border/70 group-hover:text-muted-foreground",
+                    "bg-background/35 text-secondary-label group-hover:border-border/70 group-hover:text-foreground",
                   )}
                 >
                   {shortcutKey}
diff --git a/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx b/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx
index 602ad114464..5e9e43dcf21 100644
--- a/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx
+++ b/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx
@@ -63,13 +63,13 @@ export function ComposerPreviewAnnotationCards({
                 />
               </button>
             ) : (
-              <span className="grid size-10 shrink-0 place-items-center border-r border-border/70 text-blue-500">
+              <span className="grid size-10 shrink-0 place-items-center border-r border-border/70 text-message-action">
                 <MousePointerClick className="size-3.5" />
               </span>
             )}
             <div className="min-w-0 px-2.5 py-2 pr-8">
               {annotation.comment.trim() ? (
-                <p className="max-w-80 truncate text-xs font-medium text-foreground/90">
+                <p className="max-w-80 truncate text-foreground text-xs font-medium">
                   {annotation.comment.trim()}
                 </p>
               ) : null}
@@ -84,13 +84,13 @@ export function ComposerPreviewAnnotationCards({
                     {elementLabels.slice(0, 2).map(({ id, label }) => (
                       <span
                         key={id}
-                        className="max-w-40 truncate font-mono text-[10px] text-foreground/65"
+                        className="max-w-40 truncate font-mono text-secondary-label text-[10px]"
                       >
                         {label}
                       </span>
                     ))}
                     {elementLabels.length > 2 ? (
-                      <span className="text-[10px] text-muted-foreground">
+                      <span className="text-secondary-label text-[10px]">
                         +{elementLabels.length - 2}
                       </span>
                     ) : null}
@@ -131,7 +131,7 @@ export function ComposerPreviewAnnotationCards({
             <button
               type="button"
               aria-label="Remove preview annotation"
-              className="absolute right-1.5 top-1.5 grid size-5 place-items-center rounded text-muted-foreground/60 transition hover:bg-muted hover:text-foreground"
+              className="absolute right-1.5 top-1.5 grid size-5 place-items-center rounded text-icon-muted transition hover:bg-muted hover:text-foreground"
               onClick={() => onRemove(annotation.id)}
             >
               <X className="size-3" />
diff --git a/apps/web/src/components/chat/ComposerPrimaryActions.tsx b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
index 504b7e1cc44..cc211f318f1 100644
--- a/apps/web/src/components/chat/ComposerPrimaryActions.tsx
+++ b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
@@ -1,8 +1,6 @@
 import { memo, type PointerEventHandler } from "react";
 import { ChevronDownIcon, ChevronLeftIcon } from "lucide-react";
-import { useEnvironmentIdentificationMode } from "~/hooks/useSettings";
 import { cn } from "~/lib/utils";
-import { StageBackdropButtonArt, useSidebarStageBackdropVariant } from "../SidebarStageBackdrop";
 import { Button } from "../ui/button";
 import { Menu, MenuItem, MenuPopup, MenuTrigger } from "../ui/menu";
 import { Spinner } from "../ui/spinner";
@@ -75,11 +73,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
   const pointerFocusProps = preserveComposerFocusOnPointerDown
     ? { onPointerDown: preventPointerFocus }
     : undefined;
-  const environmentIdentificationMode = useEnvironmentIdentificationMode();
   const isSendDisabled = sendDisabledReason !== null;
-  const stageBackdropVariant = useSidebarStageBackdropVariant(
-    environmentIdentificationMode === "artwork",
-  );
 
   if (pendingAction) {
     return (
@@ -113,7 +107,10 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
         <Button
           type="submit"
           size="sm"
-          className={cn("rounded-full", compact ? "px-3" : "px-4")}
+          className={cn(
+            "rounded-full bg-message-action text-message-action-foreground hover:bg-message-action-hover",
+            compact ? "px-3" : "px-4",
+          )}
           {...pointerFocusProps}
           disabled={
             isEnvironmentUnavailable ||
@@ -154,7 +151,10 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
         <Button
           type="submit"
           size="sm"
-          className={cn("rounded-full", compact ? "h-9 px-3 sm:h-8" : "h-9 px-4 sm:h-8")}
+          className={cn(
+            "rounded-full bg-message-action text-message-action-foreground hover:bg-message-action-hover",
+            compact ? "h-9 px-3 sm:h-8" : "h-9 px-4 sm:h-8",
+          )}
           {...pointerFocusProps}
           disabled={isSendBusy || isSendDisabled || isConnecting || isEnvironmentUnavailable}
         >
@@ -168,7 +168,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
         <Button
           type="submit"
           size="sm"
-          className="h-9 rounded-l-full rounded-r-none px-4 sm:h-8"
+          className="h-9 rounded-l-full rounded-r-none bg-message-action px-4 text-message-action-foreground hover:bg-message-action-hover sm:h-8"
           {...pointerFocusProps}
           disabled={isSendBusy || isSendDisabled || isConnecting || isEnvironmentUnavailable}
         >
@@ -180,7 +180,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
               <Button
                 size="sm"
                 variant="default"
-                className="h-9 rounded-l-none rounded-r-full border-l-white/12 px-2 sm:h-8"
+                className="h-9 rounded-l-none rounded-r-full border-l-message-action-foreground/20 bg-message-action px-2 text-message-action-foreground hover:bg-message-action-hover sm:h-8"
                 aria-label="Implementation actions"
                 {...pointerFocusProps}
                 disabled={isSendBusy || isSendDisabled || isConnecting || isEnvironmentUnavailable}
@@ -206,10 +206,8 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
     <button
       type="submit"
       className={cn(
-        "relative isolate flex h-9 w-9 items-center justify-center overflow-hidden rounded-full text-primary-foreground shadow-xs transition-all duration-150 enabled:cursor-pointer enabled:inset-shadow-[0_1px_--theme(--color-white/16%)] hover:scale-105 active:inset-shadow-[0_1px_--theme(--color-black/8%)] active:shadow-none disabled:pointer-events-none disabled:opacity-30 disabled:shadow-none disabled:hover:scale-100 sm:h-8 sm:w-8",
-        stageBackdropVariant
-          ? "bg-transparent enabled:shadow-black/24 enabled:hover:brightness-110"
-          : "bg-primary/90 enabled:shadow-primary/24 hover:bg-primary",
+        "relative isolate flex h-9 w-9 items-center justify-center overflow-hidden rounded-full text-message-action-foreground shadow-xs transition-all duration-150 enabled:cursor-pointer enabled:inset-shadow-[0_1px_--theme(--color-white/16%)] hover:scale-105 active:inset-shadow-[0_1px_--theme(--color-black/8%)] active:shadow-none disabled:pointer-events-none disabled:opacity-30 disabled:shadow-none disabled:hover:scale-100 sm:h-8 sm:w-8",
+        "bg-message-action enabled:shadow-message-action/24 hover:bg-message-action-hover",
       )}
       {...pointerFocusProps}
       disabled={
@@ -233,11 +231,6 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
                   : "Send message"
       }
     >
-      {stageBackdropVariant ? (
-        <span className="absolute inset-0 -z-10" aria-hidden="true">
-          <StageBackdropButtonArt variant={stageBackdropVariant} />
-        </span>
-      ) : null}
       {isConnecting || isSendBusy ? (
         <Spinner className="size-3.5" aria-hidden="true" />
       ) : (
diff --git a/apps/web/src/components/chat/ComposerStashMenu.tsx b/apps/web/src/components/chat/ComposerStashMenu.tsx
index bfc2d88ba76..9e923851533 100644
--- a/apps/web/src/components/chat/ComposerStashMenu.tsx
+++ b/apps/web/src/components/chat/ComposerStashMenu.tsx
@@ -94,12 +94,12 @@ export const ComposerStashMenu = memo(function ComposerStashMenu(props: {
       <div className="dropdown-glass relative w-full overflow-hidden rounded-[20px]">
         <CommandList className="max-h-72">
           <CommandGroup>
-            <CommandGroupLabel className="flex items-center gap-1.5 px-3 pt-2 pb-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/55">
+            <CommandGroupLabel className="flex items-center gap-1.5 px-3 pt-2 pb-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-secondary-label">
               <BookmarkIcon className="size-3" aria-hidden="true" />
               Stashed prompts
             </CommandGroupLabel>
             {entries.length === 0 ? (
-              <p className="px-3 pb-3 pt-1 text-muted-foreground/70 text-xs">
+              <p className="px-3 pb-3 pt-1 text-secondary-label text-xs">
                 Nothing stashed yet. Press ⌘S with a prompt in the composer to stash it.
               </p>
             ) : (
@@ -134,23 +134,23 @@ export const ComposerStashMenu = memo(function ComposerStashMenu(props: {
                       ))}
                     </span>
                   ) : (
-                    <BookmarkIcon className="size-4 shrink-0 text-muted-foreground/60" />
+                    <BookmarkIcon className="size-4 shrink-0 text-icon-muted" />
                   )}
                   <span className="min-w-0 flex-1 truncate text-sm">
                     {stashEntrySnippet(entry)}
                   </span>
                   {entry.pendingImageCount ? (
-                    <span className="shrink-0 text-[10px] text-muted-foreground/60">
+                    <span className="shrink-0 text-[10px] text-secondary-label">
                       saving {entry.pendingImageCount} image
                       {entry.pendingImageCount === 1 ? "" : "s"}…
                     </span>
                   ) : missingImageCount(entry) > 0 ? (
-                    <span className="shrink-0 text-[10px] text-amber-600">
+                    <span className="shrink-0 text-[10px] text-warning-foreground">
                       {missingImageCount(entry)} image
                       {missingImageCount(entry) === 1 ? "" : "s"} dropped
                     </span>
                   ) : null}
-                  <span className="shrink-0 text-muted-foreground/60 text-xs">
+                  <span className="shrink-0 text-secondary-label text-xs">
                     {formatRelativeTimeLabel(entry.createdAt)}
                   </span>
                   <Button
diff --git a/apps/web/src/components/chat/ContextWindowMeter.tsx b/apps/web/src/components/chat/ContextWindowMeter.tsx
index d2344824705..752ec401376 100644
--- a/apps/web/src/components/chat/ContextWindowMeter.tsx
+++ b/apps/web/src/components/chat/ContextWindowMeter.tsx
@@ -26,7 +26,7 @@ export function ContextWindowMeter(props: {
   const showTotalProcessed = totalProcessedTokens !== null && totalProcessedTokens > 0;
   const isOverloaded = normalizedPercentage > 90;
   const usageColor = isOverloaded
-    ? "var(--color-red-500)"
+    ? "var(--color-error)"
     : "color-mix(in oklab, var(--color-muted-foreground) 72%, transparent)";
 
   return (
@@ -91,7 +91,7 @@ export function ContextWindowMeter(props: {
           <div className="flex items-center justify-between gap-3">
             <div className="font-medium text-muted-foreground text-xs">Context Window</div>
             {usage.maxTokens !== null && usedPercentage ? (
-              <div className="text-[11px] tabular-nums text-muted-foreground/70">
+              <div className="text-secondary-label text-[11px] tabular-nums">
                 <span>{usedPercentage}</span>
                 <span className="mx-1">·</span>
                 <span>
@@ -100,7 +100,7 @@ export function ContextWindowMeter(props: {
                 </span>
               </div>
             ) : (
-              <div className="text-[11px] tabular-nums text-muted-foreground/70">
+              <div className="text-secondary-label text-[11px] tabular-nums">
                 {formatContextWindowTokens(usage.usedTokens)}
               </div>
             )}
@@ -122,14 +122,14 @@ export function ContextWindowMeter(props: {
           ) : null}
           {showTotalProcessed ? (
             <div className="flex items-center justify-between gap-3 text-[11px] leading-4">
-              <span className="text-muted-foreground/60">Total processed</span>
-              <span className="font-medium tabular-nums text-muted-foreground/80">
+              <span className="text-secondary-label">Total processed</span>
+              <span className="font-medium tabular-nums text-secondary-label">
                 {formatContextWindowTokens(totalProcessedTokens)}
               </span>
             </div>
           ) : null}
           {usage.compactsAutomatically ? (
-            <div className="mt-1 text-pretty text-[11px] font-medium text-muted-foreground/70">
+            <div className="mt-1 text-pretty text-secondary-label text-[11px] font-medium">
               {providerDisplayName ?? "It"} automatically compacts its context when needed.
             </div>
           ) : null}
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index 83ca7d3e952..23d6a1a6698 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -434,7 +434,7 @@ describe("MessagesTimeline", () => {
 
     expect(markup).not.toContain("Show full message");
     expect(markup).toContain('data-user-message-collapsible="false"');
-    expect(markup).toContain("rounded-2xl bg-accent p-3");
+    expect(markup).toContain("rounded-2xl bg-message p-3");
   });
 
   it("renders inline terminal labels with the composer chip UI", () => {
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index a429b54deaf..c88ba8a50e9 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -473,9 +473,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
     }
     return (
       <div className="flex h-full items-center justify-center">
-        <p className="text-sm text-muted-foreground/30">
-          Send a message to start the conversation.
-        </p>
+        <p className="text-placeholder text-sm">Send a message to start the conversation.</p>
       </div>
     );
   }
@@ -890,7 +888,7 @@ function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message"
 
   return (
     <div className="group flex flex-col items-end gap-1">
-      <div className="relative max-w-[80%] rounded-2xl bg-accent p-3">
+      <div className="relative max-w-[80%] rounded-2xl bg-message p-3 text-message-foreground">
         {regularImages.length > 0 && (
           <div className="mb-2 grid max-w-[420px] grid-cols-2 gap-2">
             {regularImages.map((image: NonNullable<TimelineMessage["attachments"]>[number]) => (
@@ -916,7 +914,7 @@ function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message"
                     />
                   </button>
                 ) : (
-                  <div className="flex min-h-[72px] items-center justify-center px-2 py-3 text-center text-[11px] text-muted-foreground/70">
+                  <div className="flex min-h-[72px] items-center justify-center px-2 py-3 text-center text-secondary-label text-[11px]">
                     {image.name}
                   </div>
                 )}
@@ -1094,7 +1092,7 @@ function ProposedPlanTimelineRow({
 function WorkingTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "working" }> }) {
   return (
     <div className="py-0.5 pl-1.5">
-      <div className="flex items-center gap-2 pt-1 text-[11px] text-muted-foreground/70 tabular-nums">
+      <div className="flex items-center gap-2 pt-1 text-secondary-label text-[11px] tabular-nums">
         <span className="inline-flex items-center gap-[3px]">
           <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-status-pulse" />
           <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-status-pulse [animation-delay:200ms]" />
@@ -1170,9 +1168,7 @@ const WorkGroupSection = memo(function WorkGroupSection({
   return (
     <section className="-mx-1 space-y-0.5 px-1 py-0.5" aria-label={groupLabel}>
       {!onlyToolEntries && (
-        <p className="px-0.5 pb-0.5 font-medium text-[11px] text-muted-foreground/65">
-          {groupLabel}
-        </p>
+        <p className="px-0.5 pb-0.5 font-medium text-secondary-label text-[11px]">{groupLabel}</p>
       )}
       <div className="space-y-px">
         {nonEmptyEntries.map((workEntry) => (
@@ -1212,7 +1208,7 @@ function WorkGroupToggleTimelineRow({
         ctx.onToggleWorkGroup(row.groupId, anchorElement);
       }}
     >
-      <span className="flex size-5 shrink-0 items-center justify-center text-muted-foreground/65">
+      <span className="flex size-5 shrink-0 items-center justify-center text-icon-muted">
         <ChevronDownIcon
           className={cn(
             "size-3.5 shrink-0 opacity-70 transition-transform duration-200",
@@ -1221,11 +1217,11 @@ function WorkGroupToggleTimelineRow({
         />
       </span>
       {row.expanded ? (
-        <span className="font-medium text-foreground/82">
+        <span className="font-medium text-foreground">
           Show fewer {row.onlyToolEntries ? "tool calls" : "log entries"}
         </span>
       ) : (
-        <span className="font-medium text-foreground/82">
+        <span className="font-medium text-foreground">
           +{row.hiddenCount} previous {labelNoun}
         </span>
       )}
@@ -1330,7 +1326,7 @@ const UserMessageElementContextChip = memo(function UserMessageElementContextChi
     <Tooltip>
       <TooltipTrigger
         render={
-          <span className="inline-flex max-w-full items-center gap-1 rounded-md border border-border/70 bg-background/70 px-1.5 py-0.5 text-xs text-foreground/85">
+          <span className="inline-flex max-w-full items-center gap-1 rounded-md border border-border/70 bg-background/70 px-1.5 py-0.5 text-foreground/85 text-xs">
             <MousePointerClickIcon className="size-3 shrink-0" />
             <span className="truncate">{props.context.header}</span>
           </span>
@@ -1370,13 +1366,13 @@ function UserMessagePreviewAnnotationCard(props: {
       ) : null}
       <div className="min-w-0 px-2.5 py-2">
         {props.annotation.comment ? (
-          <div className="max-w-80 truncate text-xs font-medium text-foreground/90">
+          <div className="max-w-80 truncate text-foreground text-xs font-medium">
             {props.annotation.comment}
           </div>
         ) : null}
         <div
           className={cn(
-            "flex items-center gap-2 text-[10px] text-muted-foreground",
+            "flex items-center gap-2 text-secondary-label text-[10px]",
             props.annotation.comment && "mt-1",
           )}
         >
@@ -1465,7 +1461,7 @@ const CollapsibleUserMessageBody = memo(function CollapsibleUserMessageBody(prop
               aria-expanded={expanded}
               data-scroll-anchor-ignore
               onClick={() => setExpanded((value) => !value)}
-              className="-ml-1 h-6 rounded-md px-1.5 text-xs text-muted-foreground/72 hover:bg-muted/55 hover:text-foreground/85"
+              className="-ml-1 h-6 rounded-md px-1.5 text-secondary-label text-xs hover:bg-muted/55 hover:text-message-foreground"
             >
               {expanded ? "Show less" : "Show full message"}
             </Button>
@@ -1504,7 +1500,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
             cwd={props.markdownCwd}
             threadRef={ctx.threadRef ?? undefined}
             skills={props.skills}
-            className="text-foreground"
+            className="text-message-foreground"
             lineBreaks
           />
         ) : null}
@@ -1516,7 +1512,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
   const reviewCommentSegments = parseReviewCommentMessageSegments(props.text);
   if (reviewCommentSegments.some((segment) => segment.kind === "review-comment")) {
     return (
-      <div className="space-y-3 text-sm leading-relaxed text-foreground">
+      <div className="space-y-3 text-message-foreground text-sm leading-relaxed">
         {reviewCommentSegments.map((segment) =>
           segment.kind === "text" ? (
             segment.text.trim().length > 0 ? (
@@ -1526,7 +1522,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
                   cwd={props.markdownCwd}
                   threadRef={ctx.threadRef ?? undefined}
                   skills={props.skills}
-                  className="text-foreground"
+                  className="text-message-foreground"
                   lineBreaks
                 />
               </div>
@@ -1585,7 +1581,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
         }
 
         return (
-          <div className="whitespace-pre-wrap wrap-break-word text-sm leading-relaxed text-foreground">
+          <div className="whitespace-pre-wrap wrap-break-word text-message-foreground text-sm leading-relaxed">
             {inlineNodes}
           </div>
         );
@@ -1614,7 +1610,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
           cwd={props.markdownCwd}
           threadRef={ctx.threadRef ?? undefined}
           skills={props.skills}
-          className="text-foreground"
+          className="text-message-foreground"
           lineBreaks
         />,
       );
@@ -1623,7 +1619,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
     }
 
     return (
-      <div className="whitespace-pre-wrap wrap-break-word text-sm leading-relaxed text-foreground">
+      <div className="whitespace-pre-wrap wrap-break-word text-message-foreground text-sm leading-relaxed">
         {inlineNodes}
       </div>
     );
@@ -1639,7 +1635,7 @@ const UserMessageBody = memo(function UserMessageBody(props: {
       cwd={props.markdownCwd}
       threadRef={ctx.threadRef ?? undefined}
       skills={props.skills}
-      className="text-foreground"
+      className="text-message-foreground"
       lineBreaks
     />
   );
@@ -1656,10 +1652,10 @@ function UserMessageReviewCommentCard({ comment }: { comment: ReviewCommentConte
   return (
     <div className="space-y-2 rounded-lg border border-border/70 bg-background/70 p-3">
       <div className="space-y-1">
-        <div className="text-xs font-medium text-foreground">
+        <div className="text-message-foreground text-xs font-medium">
           {formatWorkspaceRelativePath(comment.filePath, ctx.workspaceRoot)}
         </div>
-        <div className="text-[11px] text-muted-foreground">
+        <div className="text-secondary-label text-[11px]">
           {comment.sectionTitle} · {comment.rangeLabel}
         </div>
       </div>
@@ -1674,7 +1670,7 @@ function UserMessageReviewCommentCard({ comment }: { comment: ReviewCommentConte
           cwd={ctx.markdownCwd}
           threadRef={ctx.threadRef ?? undefined}
           skills={ctx.skills}
-          className="text-foreground"
+          className="text-message-foreground"
         />
       )}
       {renderablePatch?.kind === "files" &&
@@ -1799,24 +1795,24 @@ function workToneIcon(tone: TimelineWorkEntry["tone"]): {
   if (tone === "error") {
     return {
       iconName: "circle-alert",
-      className: "text-foreground/92",
+      className: "text-foreground",
     };
   }
   if (tone === "thinking") {
     return {
       iconName: "bot",
-      className: "text-foreground/92",
+      className: "text-foreground",
     };
   }
   if (tone === "info") {
     return {
       iconName: "check",
-      className: "text-muted-foreground",
+      className: "text-icon-muted",
     };
   }
   return {
     iconName: "zap",
-    className: "text-foreground/92",
+    className: "text-foreground",
   };
 }
 
@@ -1953,14 +1949,14 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
       : showDestructiveRowStyle
         ? "text-destructive"
         : workEntry.tone === "tool" || showFailedIndicator
-          ? "text-muted-foreground/65"
+          ? "text-icon-muted"
           : iconConfig.className,
   );
   const headingClass = showWarningIndicator
     ? "font-medium text-warning"
     : showDestructiveRowStyle
       ? "font-medium text-destructive"
-      : "font-medium text-foreground/82";
+      : "font-medium text-foreground";
   const turnSettled = !activity.activeTurnInProgress;
   const showNeutralIndicator = !turnSettled && workEntryIndicatesToolNeutralStatus(workEntry);
   const showSuccessIndicator =
@@ -2002,11 +1998,11 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
             <p className="flex min-w-0 w-full items-baseline gap-1.5 text-[12px] leading-5">
               <span className={cn("min-w-0 shrink truncate", headingClass)}>{heading}</span>
               {preview && (
-                <span className="min-w-0 flex-1 truncate text-muted-foreground/55">{preview}</span>
+                <span className="min-w-0 flex-1 truncate text-secondary-label">{preview}</span>
               )}
             </p>
           </div>
-          <div className="flex shrink-0 items-center gap-px text-muted-foreground/55">
+          <div className="flex shrink-0 items-center gap-px text-icon-muted">
             <span
               className="flex size-4 shrink-0 items-center justify-center"
               aria-hidden={!canExpand}
@@ -2071,7 +2067,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
           onClick={stopRowToggle}
           onPointerDown={stopRowToggle}
         >
-          <pre className="max-h-64 cursor-text overflow-auto whitespace-pre-wrap break-words font-mono text-[11px] leading-relaxed text-muted-foreground select-text">
+          <pre className="max-h-64 cursor-text overflow-auto whitespace-pre-wrap break-words font-mono text-secondary-label text-[11px] leading-relaxed select-text">
             {expandedBody}
           </pre>
         </div>
diff --git a/apps/web/src/components/chat/ModelListRow.tsx b/apps/web/src/components/chat/ModelListRow.tsx
index a74a4ebf8c2..70475ffd038 100644
--- a/apps/web/src/components/chat/ModelListRow.tsx
+++ b/apps/web/src/components/chat/ModelListRow.tsx
@@ -69,7 +69,7 @@ export const ModelListRow = memo(function ModelListRow(props: {
           </div>
           {props.showNewBadge ? (
             <span
-              className="shrink-0 rounded border border-amber-500/35 bg-amber-500/15 px-0.5 py-px text-[10px] font-bold uppercase leading-none tracking-wide text-amber-800 dark:border-amber-400/30 dark:bg-amber-400/12 dark:text-amber-200"
+              className="shrink-0 rounded border border-update/35 bg-update/15 px-0.5 py-px text-[10px] font-bold uppercase leading-none tracking-wide text-update-foreground"
               aria-label="New model"
             >
               New
diff --git a/apps/web/src/components/chat/ModelPickerSidebar.tsx b/apps/web/src/components/chat/ModelPickerSidebar.tsx
index 24ec66cd614..82ee33615b0 100644
--- a/apps/web/src/components/chat/ModelPickerSidebar.tsx
+++ b/apps/web/src/components/chat/ModelPickerSidebar.tsx
@@ -29,7 +29,7 @@ const SELECTED_INDICATOR_CLASS =
   "pointer-events-none absolute -right-1 top-1/2 z-10 h-5 w-0.75 -translate-y-1/2 rounded-l-full bg-primary";
 const BADGE_BASE_CLASS =
   "pointer-events-none absolute -right-0.5 top-0.5 z-10 flex size-3.5 items-center justify-center rounded-full bg-transparent shadow-sm ";
-const NEW_BADGE_CLASS = `${BADGE_BASE_CLASS} text-amber-600  dark:text-amber-300 `;
+const NEW_BADGE_CLASS = `${BADGE_BASE_CLASS} text-update `;
 
 /** Opens toward the rail so the list stays readable (not over the model names). */
 const PICKER_TOOLTIP_SIDE = "left" as const;
diff --git a/apps/web/src/components/chat/PierreEntryIcon.tsx b/apps/web/src/components/chat/PierreEntryIcon.tsx
index 17dfa8362af..df41adb7dd5 100644
--- a/apps/web/src/components/chat/PierreEntryIcon.tsx
+++ b/apps/web/src/components/chat/PierreEntryIcon.tsx
@@ -73,9 +73,9 @@ export const PierreEntryIcon = memo(function PierreEntryIcon(props: {
 
   if (!icon) {
     return props.kind === "directory" ? (
-      <FolderIcon className={cn("size-4 text-muted-foreground/80", props.className)} />
+      <FolderIcon className={cn("size-4 text-icon-muted", props.className)} />
     ) : (
-      <FileIcon className={cn("size-4 text-muted-foreground/80", props.className)} />
+      <FileIcon className={cn("size-4 text-icon-muted", props.className)} />
     );
   }
 
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index a736cf96cd3..f9b0999ca72 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -84,6 +84,14 @@ const RENDER_MARKDOWN_STORAGE_KEY = "t3code.renderMarkdown";
 const FILE_SAVE_DEBOUNCE_MS = 500;
 const FILE_LINK_REVEAL_ATTRIBUTE = "data-file-link-reveal";
 const FILE_LINK_REVEAL_UNSAFE_CSS = `
+  diffs-container {
+    --diffs-bg: var(--code-background, var(--background)) !important;
+    --diffs-light-bg: var(--code-background, var(--background)) !important;
+    --diffs-dark-bg: var(--code-background, var(--background)) !important;
+    background-color: var(--code-background, var(--background)) !important;
+    color: var(--code-foreground, var(--foreground)) !important;
+  }
+
   [${FILE_LINK_REVEAL_ATTRIBUTE}][data-line] {
     background-color: light-dark(
       color-mix(
@@ -959,7 +967,7 @@ export default function FilePreviewPanel({
         </div>
       ) : null}
       {relativePath && file.data?.truncated ? (
-        <div className="shrink-0 border-b border-amber-500/20 bg-amber-500/8 px-3 py-1.5 text-[11px] text-amber-700 dark:text-amber-300">
+        <div className="shrink-0 border-b border-warning/20 bg-warning-surface px-3 py-1.5 text-[11px] text-warning-foreground">
           Preview limited to the first 1 MB of a {file.data.byteLength.toLocaleString()} byte file.
         </div>
       ) : null}
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index 2a691943df4..17b1ebdf33d 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -619,7 +619,7 @@ export function ProviderInstanceCard({
                           "size-5 rounded-sm p-0",
                           versionAdvisory.emphasis === "strong"
                             ? "text-warning hover:text-warning"
-                            : "text-primary hover:text-primary",
+                            : "text-update hover:text-update",
                         )}
                         aria-label="Update available — view details"
                       >
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 31ac4bba66e..45d53e49893 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -63,6 +63,7 @@ import {
 } from "../SidebarStageBackdrop";
 import { isElectron } from "../../env";
 import { buildHostedChannelSelectionUrl, type HostedAppChannel } from "../../hostedPairing";
+import { useCustomThemes } from "../../hooks/useCustomThemes";
 import { useTheme } from "../../hooks/useTheme";
 import { usePrimarySettings, useUpdatePrimarySettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
@@ -109,6 +110,7 @@ import { Switch } from "../ui/switch";
 import { stackedThreadToast, toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
+import { ThemeLibrary } from "./ThemeSettings";
 import {
   canOneClickUpdateProviderCandidate,
   collectProviderUpdateCandidates,
@@ -140,21 +142,6 @@ import { searchableSetting } from "./settingsSearch";
 import { ProjectFavicon } from "../ProjectFavicon";
 import { useAtomCommand } from "../../state/use-atom-command";
 
-const THEME_OPTIONS = [
-  {
-    value: "system",
-    label: "System",
-  },
-  {
-    value: "light",
-    label: "Light",
-  },
-  {
-    value: "dark",
-    label: "Dark",
-  },
-] as const;
-
 const ENVIRONMENT_IDENTIFICATION_LABELS: Record<EnvironmentIdentificationMode, string> = {
   artwork: "Artwork",
   pill: "Version pill",
@@ -557,7 +544,7 @@ function AboutVersionSection() {
 }
 
 export function useSettingsRestore(onRestored?: () => void) {
-  const { theme, setTheme } = useTheme();
+  const { theme, setTheme, followSystem, setFollowSystem } = useTheme();
   const settings = usePrimarySettings();
   const updateSettings = useUpdatePrimarySettings();
 
@@ -570,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
   const changedSettingLabels = useMemo(
     () => [
       ...(theme !== "system" ? ["Theme"] : []),
+      ...(!followSystem ? ["Follow system"] : []),
       ...(settings.glassOpacity !== DEFAULT_UNIFIED_SETTINGS.glassOpacity ? ["Glass opacity"] : []),
       ...(settings.environmentIdentificationMode !==
       DEFAULT_UNIFIED_SETTINGS.environmentIdentificationMode
@@ -636,6 +624,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.sidebarThreadPreviewCount,
       settings.timestampFormat,
       settings.wordWrap,
+      followSystem,
       theme,
     ],
   );
@@ -651,6 +640,7 @@ export function useSettingsRestore(onRestored?: () => void) {
     if (!confirmed) return;
 
     setTheme("system");
+    setFollowSystem(true);
     updateSettings({
       timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
       wordWrap: DEFAULT_UNIFIED_SETTINGS.wordWrap,
@@ -674,7 +664,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
     });
     onRestored?.();
-  }, [changedSettingLabels, onRestored, setTheme, updateSettings]);
+  }, [changedSettingLabels, onRestored, setFollowSystem, setTheme, updateSettings]);
 
   return {
     changedSettingLabels,
@@ -949,7 +939,9 @@ function BackgroundActivityAdvancedDialog({
 }
 
 export function AppearanceSettingsPanel() {
-  const { theme, setTheme } = useTheme();
+  const { theme, setTheme, setFollowSystem, refreshTheme, followSystem, resolvedTheme } =
+    useTheme();
+  const customThemes = useCustomThemes();
   const settings = usePrimarySettings();
   const updateSettings = useUpdatePrimarySettings();
   const environmentStageLabel = useEnvironmentStageLabel();
@@ -964,38 +956,15 @@ export function AppearanceSettingsPanel() {
 
   return (
     <SettingsPageContainer>
-      <SettingsSection id="appearance" title="Appearance">
-        <SettingsRow
-          {...searchableSetting("theme")}
-          description="Choose how T3 Code looks across the app."
-          resetAction={
-            theme !== "system" ? (
-              <SettingResetButton label="theme" onClick={() => setTheme("system")} />
-            ) : null
-          }
-          control={
-            <Select
-              value={theme}
-              onValueChange={(value) => {
-                if (value === "system" || value === "light" || value === "dark") {
-                  setTheme(value);
-                }
-              }}
-            >
-              <SelectTrigger className="w-full sm:w-40" aria-label="Theme preference">
-                <SelectValue>
-                  {THEME_OPTIONS.find((option) => option.value === theme)?.label ?? "System"}
-                </SelectValue>
-              </SelectTrigger>
-              <SelectPopup align="end" alignItemWithTrigger={false}>
-                {THEME_OPTIONS.map((option) => (
-                  <SelectItem hideIndicator key={option.value} value={option.value}>
-                    {option.label}
-                  </SelectItem>
-                ))}
-              </SelectPopup>
-            </Select>
-          }
+      <SettingsSection {...searchableSetting("theme")} title="Appearance">
+        <ThemeLibrary
+          customThemes={customThemes}
+          followSystem={followSystem}
+          initialAppearance={resolvedTheme}
+          refreshTheme={refreshTheme}
+          setFollowSystem={setFollowSystem}
+          setTheme={setTheme}
+          theme={theme}
         />
 
         <SettingsRow
diff --git a/apps/web/src/components/settings/ThemeSettings.tsx b/apps/web/src/components/settings/ThemeSettings.tsx
new file mode 100644
index 00000000000..4370e6a1d14
--- /dev/null
+++ b/apps/web/src/components/settings/ThemeSettings.tsx
@@ -0,0 +1,1647 @@
+import {
+  DownloadIcon,
+  MoonIcon,
+  PenLineIcon,
+  PlusIcon,
+  SunIcon,
+  Trash2Icon,
+  UploadIcon,
+} from "lucide-react";
+import type { ChangeEvent, KeyboardEvent, PointerEvent, UIEvent } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { cn } from "../../lib/utils";
+import {
+  THEME_COLOR_ROLES,
+  THEME_FILE_VERSION,
+  createManagedThemeColors,
+  getDefaultThemeColors,
+  getThemeColorsForMode,
+  getThemeDefinition,
+  getThemeModes,
+  getThemePreferenceMode,
+  installCustomTheme,
+  isThemeColor,
+  parseThemeFile,
+  removeCustomTheme,
+  serializeThemeFile,
+  themePreferenceForMode,
+  updateCustomTheme,
+  type ThemeAppearance,
+  type ThemeColorRole,
+  type ThemeDefinition,
+  T3_CHAT_THEME,
+  T3_GROVE_THEME,
+} from "../../themePalette";
+import { Alert } from "../ui/alert";
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogPopup,
+  AlertDialogTitle,
+} from "../ui/alert-dialog";
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
+import { Switch } from "../ui/switch";
+import { stackedThreadToast, toastManager } from "../ui/toast";
+
+const THEME_PREVIEW_ROLES = [
+  "sidebar",
+  "canvas",
+  "surface",
+  "accentSurface",
+  "accent",
+  "messageSurface",
+  "messageAction",
+] as const;
+type ThemePreviewRole = (typeof THEME_PREVIEW_ROLES)[number];
+type ThemeCardPreview = {
+  mode: ThemeAppearance;
+  colors: Readonly<Record<ThemePreviewRole, string>>;
+};
+type ThemeCardDefinition = {
+  id: string;
+  label: string;
+  previews: ReadonlyArray<ThemeCardPreview>;
+};
+
+const STANDARD_THEME_PREVIEW_COLORS: Record<
+  ThemeAppearance,
+  Readonly<Record<ThemePreviewRole, string>>
+> = {
+  light: {
+    sidebar: "#fafafa",
+    canvas: "#fcfcfc",
+    surface: "#ffffff",
+    accentSurface: "#f4f4f5",
+    accent: "#f4f4f5",
+    messageSurface: "#e4e4e7",
+    messageAction: "#4f46e5",
+  },
+  dark: {
+    sidebar: "#0f0f10",
+    canvas: "#0a0a0a",
+    surface: "#121212",
+    accentSurface: "#27272a",
+    accent: "#1c1c1f",
+    messageSurface: "#27272a",
+    messageAction: "#8b9cff",
+  },
+};
+
+function getStandardThemeCards(): ReadonlyArray<ThemeCardDefinition> {
+  return [
+    {
+      id: "default",
+      label: "Default",
+      previews: (["light", "dark"] as const).map((mode) => ({
+        mode,
+        colors: STANDARD_THEME_PREVIEW_COLORS[mode],
+      })),
+    },
+  ];
+}
+
+function getThemeCardDefinition(theme: ThemeDefinition): ThemeCardDefinition {
+  return {
+    id: theme.id,
+    label: theme.label,
+    previews: getThemeModes(theme).map((mode) => {
+      const colors = getThemeColorsForMode(theme, mode) ?? theme.colors;
+      return {
+        mode,
+        colors: {
+          sidebar: colors.sidebar,
+          canvas: colors.canvas,
+          surface: colors.surface,
+          accentSurface: colors.accentSurface,
+          accent: colors.accent,
+          messageSurface: colors.messageSurface,
+          messageAction: colors.messageAction,
+        },
+      };
+    }),
+  };
+}
+
+const THEME_EDITOR_PRIMARY_ROLES: ReadonlyArray<ThemeColorRole> = [
+  "canvas",
+  "chrome",
+  "sidebar",
+  "surface",
+  "text",
+  "textMuted",
+  "placeholder",
+  "secondaryLabel",
+  "iconMuted",
+  "accent",
+  "messageSurface",
+  "messageAction",
+];
+
+const THEME_EDITOR_SIMPLE_ROLES: ReadonlyArray<ThemeColorRole> = ["canvas", "accent"];
+
+const THEME_EDITOR_STATUS_ROLES: ReadonlyArray<ThemeColorRole> = [
+  "error",
+  "errorForeground",
+  "errorSurface",
+  "warning",
+  "warningForeground",
+  "warningSurface",
+  "update",
+  "updateForeground",
+  "updateSurface",
+];
+
+const THEME_EDITOR_ADVANCED_ROLES = THEME_COLOR_ROLES.filter(
+  (role) => !THEME_EDITOR_PRIMARY_ROLES.includes(role) && !THEME_EDITOR_STATUS_ROLES.includes(role),
+);
+
+type ThemeEditorColors = Record<ThemeColorRole, string>;
+type ThemeEditorModeSelection = "single" | "both";
+type ThemeEditorColorsByAppearance = Record<ThemeAppearance, ThemeEditorColors>;
+
+function getThemeEditorDefaults(appearance: ThemeAppearance): ThemeEditorColors {
+  return { ...getDefaultThemeColors(appearance) };
+}
+
+function getThemeEditorColorsByAppearance(): ThemeEditorColorsByAppearance {
+  return {
+    light: getThemeEditorDefaults("light"),
+    dark: getThemeEditorDefaults("dark"),
+  };
+}
+
+function isThemeEditorColor(value: string): boolean {
+  return isThemeColor(value.trim());
+}
+
+function getManagedEditorColors(
+  appearance: ThemeAppearance,
+  colors: ThemeEditorColors,
+): ThemeEditorColors {
+  const defaults = getDefaultThemeColors(appearance);
+  return createManagedThemeColors(
+    appearance,
+    isThemeEditorColor(colors.canvas) ? colors.canvas : defaults.canvas,
+    isThemeEditorColor(colors.accent) ? colors.accent : defaults.accent,
+  );
+}
+
+/**
+ * Whether a palette matches what the guided editor would generate from its
+ * canvas and accent, allowing one step of hex rounding drift per channel.
+ * Hand-tuned palettes must open in advanced mode so guided regeneration does
+ * not silently discard them.
+ */
+function areThemeEditorColorsManaged(
+  appearance: ThemeAppearance,
+  colors: ThemeEditorColors,
+): boolean {
+  const managed = getManagedEditorColors(appearance, colors);
+  return THEME_COLOR_ROLES.every((role) => {
+    const actual = themeHexToRgb(colors[role]);
+    const expected = themeHexToRgb(managed[role]);
+    return actual.every((channel, index) => Math.abs(channel - (expected[index] ?? 0)) <= 2);
+  });
+}
+
+function getThemeRoleLabel(role: ThemeColorRole): string {
+  const labels: Partial<Record<ThemeColorRole, string>> = {
+    canvas: "Background",
+    accent: "Accent color",
+    errorForeground: "Error text",
+    errorSurface: "Error background",
+    warningForeground: "Warning text",
+    warningSurface: "Warning background",
+    updateForeground: "Update text",
+    updateSurface: "Update background",
+  };
+  const label = labels[role];
+  if (label) return label;
+  return role.replace(/([A-Z])/g, " $1").replace(/^./, (character) => character.toUpperCase());
+}
+
+type ThemeColorHsv = {
+  h: number;
+  s: number;
+  v: number;
+};
+
+function clampThemeColor(value: number, min = 0, max = 1) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function normalizeThemePickerColor(value: string): string {
+  const trimmed = value.trim();
+  if (/^#[0-9a-f]{3}$/i.test(trimmed)) {
+    return `#${trimmed
+      .slice(1)
+      .split("")
+      .map((character) => `${character}${character}`)
+      .join("")}`;
+  }
+  if (/^#[0-9a-f]{4}$/i.test(trimmed)) {
+    return `#${trimmed
+      .slice(1, 4)
+      .split("")
+      .map((character) => `${character}${character}`)
+      .join("")}`;
+  }
+  if (/^#[0-9a-f]{6}$/i.test(trimmed)) return trimmed;
+  if (/^#[0-9a-f]{8}$/i.test(trimmed)) return trimmed.slice(0, 7);
+  return "#000000";
+}
+
+function themeHexToHsv(hex: string): ThemeColorHsv {
+  const normalized = normalizeThemePickerColor(hex);
+  const numeric = Number.parseInt(normalized.slice(1), 16);
+  const red = ((numeric >> 16) & 255) / 255;
+  const green = ((numeric >> 8) & 255) / 255;
+  const blue = (numeric & 255) / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+
+  let hue = 0;
+  if (delta !== 0) {
+    if (max === red) {
+      hue = ((green - blue) / delta) % 6;
+    } else if (max === green) {
+      hue = (blue - red) / delta + 2;
+    } else {
+      hue = (red - green) / delta + 4;
+    }
+    hue *= 60;
+    if (hue < 0) hue += 360;
+  }
+
+  return {
+    h: hue,
+    s: max === 0 ? 0 : delta / max,
+    v: max,
+  };
+}
+
+function themeHsvToHex(hue: number, saturation: number, value: number) {
+  const normalizedHue = ((hue % 360) + 360) % 360;
+  const chroma = value * saturation;
+  const x = chroma * (1 - Math.abs(((normalizedHue / 60) % 2) - 1));
+  const match = value - chroma;
+  const [red, green, blue] =
+    normalizedHue < 60
+      ? [chroma, x, 0]
+      : normalizedHue < 120
+        ? [x, chroma, 0]
+        : normalizedHue < 180
+          ? [0, chroma, x]
+          : normalizedHue < 240
+            ? [0, x, chroma]
+            : normalizedHue < 300
+              ? [x, 0, chroma]
+              : [chroma, 0, x];
+
+  return `#${[red, green, blue]
+    .map((channel) =>
+      Math.round((channel + match) * 255)
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+}
+
+function themeHexToRgb(hex: string) {
+  const numeric = Number.parseInt(normalizeThemePickerColor(hex).slice(1), 16);
+  return [numeric >> 16, (numeric >> 8) & 255, numeric & 255] as const;
+}
+
+function themeRgbToHex(value: string): string | null {
+  const normalized = value
+    .trim()
+    .replace(/^rgb\(\s*/i, "")
+    .replace(/\s*\)$/, "");
+  const channels = normalized
+    .split(/[,\s]+/)
+    .filter(Boolean)
+    .map(Number);
+  if (
+    channels.length !== 3 ||
+    channels.some((channel) => !Number.isInteger(channel) || channel < 0 || channel > 255)
+  ) {
+    return null;
+  }
+
+  return `#${channels.map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function themeRgbValue(hex: string) {
+  return themeHexToRgb(hex).join(", ");
+}
+
+function ThemeColorPickerPanel({
+  label,
+  value,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const normalizedValue = normalizeThemePickerColor(value);
+  const [hsv, setHsv] = useState(() => themeHexToHsv(normalizedValue));
+  const [hexDraft, setHexDraft] = useState(normalizedValue);
+  const [rgbDraft, setRgbDraft] = useState(() => themeRgbValue(normalizedValue));
+  const currentColor = themeHsvToHex(hsv.h, hsv.s, hsv.v);
+  const currentRgb = themeRgbValue(currentColor);
+
+  useEffect(() => {
+    setHexDraft(normalizedValue);
+    setRgbDraft(themeRgbValue(normalizedValue));
+    // Keep the current hue/saturation when the incoming value is just our own
+    // change echoed back; hex → HSV is lossy for greys, white, and black.
+    setHsv((current) =>
+      themeHsvToHex(current.h, current.s, current.v) === normalizedValue
+        ? current
+        : themeHexToHsv(normalizedValue),
+    );
+  }, [normalizedValue]);
+
+  const commitHsv = useCallback(
+    (nextHsv: ThemeColorHsv) => {
+      setHsv(nextHsv);
+      const nextColor = themeHsvToHex(nextHsv.h, nextHsv.s, nextHsv.v);
+      setHexDraft(nextColor);
+      setRgbDraft(themeRgbValue(nextColor));
+      onChange(nextColor);
+    },
+    [onChange],
+  );
+
+  const updateFromPlane = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      const bounds = event.currentTarget.getBoundingClientRect();
+      const saturation = clampThemeColor((event.clientX - bounds.left) / bounds.width);
+      const value = 1 - clampThemeColor((event.clientY - bounds.top) / bounds.height);
+      commitHsv({ ...hsv, s: saturation, v: value });
+    },
+    [commitHsv, hsv],
+  );
+
+  const updateFromHue = useCallback(
+    (event: PointerEvent<HTMLDivElement>) => {
+      const bounds = event.currentTarget.getBoundingClientRect();
+      const hue = clampThemeColor((event.clientX - bounds.left) / bounds.width) * 360;
+      commitHsv({ ...hsv, h: hue });
+    },
+    [commitHsv, hsv],
+  );
+
+  const handleHueKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const step = event.shiftKey ? 10 : 1;
+    const direction = event.key === "ArrowRight" || event.key === "ArrowUp" ? 1 : -1;
+    if (!["ArrowDown", "ArrowLeft", "ArrowRight", "ArrowUp"].includes(event.key)) return;
+    event.preventDefault();
+    commitHsv({ ...hsv, h: (hsv.h + direction * step + 360) % 360 });
+  };
+
+  const handlePointerDown = (handler: (event: PointerEvent<HTMLDivElement>) => void) => {
+    return (event: PointerEvent<HTMLDivElement>) => {
+      event.currentTarget.setPointerCapture(event.pointerId);
+      handler(event);
+    };
+  };
+
+  const handleHexChange = (nextValue: string) => {
+    setHexDraft(nextValue);
+    if (!/^#[0-9a-f]{6}$/i.test(nextValue)) return;
+    const nextHsv = themeHexToHsv(nextValue);
+    setHsv(nextHsv);
+    setRgbDraft(themeRgbValue(nextValue));
+    onChange(nextValue.toLowerCase());
+  };
+
+  const handleRgbChange = (nextValue: string) => {
+    setRgbDraft(nextValue);
+    const nextColor = themeRgbToHex(nextValue);
+    if (!nextColor) return;
+    setHsv(themeHexToHsv(nextColor));
+    setHexDraft(nextColor);
+    onChange(nextColor);
+  };
+
+  return (
+    <div className="w-64 bg-popover">
+      <div className="flex items-center justify-between border-b border-border/70 px-4 py-3">
+        <div className="min-w-0">
+          <p className="truncate text-xs font-semibold text-foreground">{label}</p>
+          <p className="text-[11px] text-muted-foreground">Choose a color</p>
+        </div>
+        <span
+          className="size-7 shrink-0 rounded-full border border-border shadow-sm"
+          style={{ backgroundColor: currentColor }}
+        />
+      </div>
+      <div className="grid gap-3 px-3 pb-3 pt-3">
+        <div
+          className="relative h-32 cursor-crosshair touch-none overflow-hidden rounded-lg"
+          style={{
+            backgroundColor: `hsl(${hsv.h} 100% 50%)`,
+            backgroundImage:
+              "linear-gradient(to top, #000, transparent), linear-gradient(to right, #fff, transparent)",
+          }}
+          onPointerDown={handlePointerDown(updateFromPlane)}
+          onPointerMove={(event) => {
+            if (event.currentTarget.hasPointerCapture(event.pointerId)) updateFromPlane(event);
+          }}
+        >
+          <span
+            className="pointer-events-none absolute size-3 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_0_0_1px_rgb(0_0_0/0.4)]"
+            style={{ left: `${hsv.s * 100}%`, top: `${(1 - hsv.v) * 100}%` }}
+          />
+        </div>
+        <div
+          aria-label={`${label} hue`}
+          aria-valuemax={360}
+          aria-valuemin={0}
+          aria-valuenow={Math.round(hsv.h)}
+          className="relative h-2.5 cursor-pointer touch-none rounded-full shadow-[inset_0_0_0_1px_rgb(0_0_0_/_12%)]"
+          role="slider"
+          style={{
+            background: "linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f, #f0f, #f00)",
+          }}
+          tabIndex={0}
+          onKeyDown={handleHueKeyDown}
+          onPointerDown={handlePointerDown(updateFromHue)}
+          onPointerMove={(event) => {
+            if (event.currentTarget.hasPointerCapture(event.pointerId)) updateFromHue(event);
+          }}
+        >
+          <span
+            className="pointer-events-none absolute top-1/2 size-4 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_0_0_1px_rgb(0_0_0/0.4)]"
+            style={{ left: `${(hsv.h / 360) * 100}%`, backgroundColor: currentColor }}
+          />
+        </div>
+        <div className="grid grid-cols-2 gap-2">
+          <label className="grid min-w-0 gap-1">
+            <span className="px-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+              HEX
+            </span>
+            <span className="flex min-w-0 items-center gap-2 rounded-lg border border-input bg-background px-2 focus-within:border-ring">
+              <span
+                className="size-3.5 shrink-0 rounded-full"
+                style={{ backgroundColor: currentColor }}
+              />
+              <input
+                aria-label={`${label} picker hex value`}
+                className="h-8 min-w-0 flex-1 bg-transparent font-mono text-xs text-foreground outline-none"
+                onBlur={() => {
+                  setHexDraft(currentColor);
+                  setRgbDraft(currentRgb);
+                }}
+                onChange={(event) => handleHexChange(event.currentTarget.value)}
+                spellCheck={false}
+                value={hexDraft}
+              />
+            </span>
+          </label>
+          <label className="grid min-w-0 gap-1">
+            <span className="px-1 text-[10px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+              RGB
+            </span>
+            <span className="flex min-w-0 items-center rounded-lg border border-input bg-background px-2 focus-within:border-ring">
+              <input
+                aria-label={`${label} picker RGB value`}
+                className="h-8 min-w-0 flex-1 bg-transparent font-mono text-xs text-foreground outline-none"
+                onBlur={() => {
+                  setHexDraft(currentColor);
+                  setRgbDraft(currentRgb);
+                }}
+                onChange={(event) => handleRgbChange(event.currentTarget.value)}
+                spellCheck={false}
+                value={rgbDraft}
+              />
+            </span>
+          </label>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ThemeColorPicker({
+  label,
+  value,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  return (
+    <Popover>
+      <PopoverTrigger
+        render={
+          <button
+            aria-label={`Choose ${label} color`}
+            className="relative flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-full border border-border transition-transform hover:scale-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+            title={`Choose ${label} color`}
+            type="button"
+          >
+            <span
+              className="absolute inset-0.5 rounded-full shadow-[inset_0_0_0_1px_rgb(255_255_255_/_28%),0_1px_2px_rgb(0_0_0_/_14%)] dark:shadow-[inset_0_0_0_1px_rgb(255_255_255_/_18%),0_1px_2px_rgb(0_0_0_/_30%)]"
+              style={{ backgroundColor: value }}
+            />
+          </button>
+        }
+      />
+      <PopoverPopup
+        align="start"
+        className="overflow-hidden rounded-2xl border border-border/70 p-0 shadow-2xl [--viewport-inline-padding:0px] [&_[data-slot=popover-viewport]]:p-0"
+        side="bottom"
+        sideOffset={10}
+      >
+        <ThemeColorPickerPanel label={label} onChange={onChange} value={value} />
+      </PopoverPopup>
+    </Popover>
+  );
+}
+
+const ThemeColorField = memo(function ThemeColorField({
+  role,
+  value,
+  onChange,
+  label: customLabel,
+}: {
+  role: ThemeColorRole;
+  value: string;
+  onChange: (role: ThemeColorRole, value: string) => void;
+  label?: string;
+}) {
+  const label = customLabel ?? getThemeRoleLabel(role);
+  const isColorValue = isThemeColor(value);
+  const swatchValue = isColorValue ? value : "#000000";
+
+  return (
+    <div className="group flex min-h-11 min-w-0 items-center gap-2 border-b border-border/70 px-1.5 py-1.5 transition-colors hover:bg-accent/40">
+      <ThemeColorPicker
+        label={label}
+        onChange={(nextValue) => onChange(role, nextValue)}
+        value={swatchValue}
+      />
+      <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{label}</span>
+      <Input
+        aria-invalid={!isColorValue}
+        aria-label={`${label} hex value`}
+        className="w-28 shrink-0 rounded-none border-0 border-b border-input bg-transparent font-mono text-xs text-foreground shadow-none focus-within:border-ring focus-within:ring-0"
+        id={`${role}-hex`}
+        nativeInput
+        onChange={(event) => onChange(role, event.currentTarget.value)}
+        size="sm"
+        unstyled
+        value={value}
+      />
+    </div>
+  );
+});
+
+function ThemeEditorDialog({
+  open,
+  onOpenChange,
+  onSaved,
+  editingTheme,
+  initialAppearance,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onSaved: (theme: ThemeDefinition) => void;
+  editingTheme: ThemeDefinition | null;
+  initialAppearance: ThemeAppearance;
+}) {
+  const isEditing = editingTheme !== null;
+  const [name, setName] = useState("");
+  const [modeSelection, setModeSelection] = useState<ThemeEditorModeSelection>("single");
+  const [activeAppearance, setActiveAppearance] = useState<ThemeAppearance>(initialAppearance);
+  const [isAdvanced, setIsAdvanced] = useState(false);
+  const [colorsByAppearance, setColorsByAppearance] = useState<ThemeEditorColorsByAppearance>(() =>
+    getThemeEditorColorsByAppearance(),
+  );
+  const [simpleColorsDirtyByAppearance, setSimpleColorsDirtyByAppearance] = useState<
+    Record<ThemeAppearance, boolean>
+  >({ light: false, dark: false });
+  const [error, setError] = useState<string | null>(null);
+  const previousOpenRef = useRef(false);
+
+  useEffect(() => {
+    if (open && !previousOpenRef.current) {
+      const nextColors = getThemeEditorColorsByAppearance();
+      const nextAppearance = editingTheme
+        ? getThemeColorsForMode(editingTheme, initialAppearance)
+          ? initialAppearance
+          : editingTheme.appearance
+        : initialAppearance;
+      if (editingTheme) {
+        nextColors[editingTheme.appearance] = { ...editingTheme.colors };
+        for (const appearance of ["light", "dark"] as const) {
+          const variantColors = editingTheme.variants?.[appearance];
+          if (variantColors) nextColors[appearance] = { ...variantColors };
+        }
+      }
+
+      setName(editingTheme?.label ?? "");
+      setModeSelection(editingTheme && getThemeModes(editingTheme).length > 1 ? "both" : "single");
+      setActiveAppearance(nextAppearance);
+      setIsAdvanced(
+        editingTheme !== null &&
+          getThemeModes(editingTheme).some(
+            (mode) => !areThemeEditorColorsManaged(mode, nextColors[mode]),
+          ),
+      );
+      setSimpleColorsDirtyByAppearance({ light: false, dark: false });
+      setColorsByAppearance(nextColors);
+      setError(null);
+    }
+    previousOpenRef.current = open;
+  }, [editingTheme, initialAppearance, open]);
+
+  const updateColor = useCallback(
+    (role: ThemeColorRole, value: string) => {
+      setColorsByAppearance((current) => {
+        const nextColors = { ...current[activeAppearance], [role]: value };
+        const shouldManageColors =
+          !isAdvanced && THEME_EDITOR_SIMPLE_ROLES.includes(role) && isThemeEditorColor(value);
+
+        return {
+          ...current,
+          [activeAppearance]: shouldManageColors
+            ? getManagedEditorColors(activeAppearance, nextColors)
+            : nextColors,
+        };
+      });
+      if (!isAdvanced && THEME_EDITOR_SIMPLE_ROLES.includes(role) && isThemeEditorColor(value)) {
+        setSimpleColorsDirtyByAppearance((current) => ({
+          ...current,
+          [activeAppearance]: true,
+        }));
+      }
+    },
+    [activeAppearance, isAdvanced],
+  );
+
+  const handleAdvancedChange = useCallback(
+    (checked: boolean) => {
+      setIsAdvanced(checked);
+      if (checked) return;
+
+      // Regenerate every appearance the theme will save, not just the visible
+      // one, so the palettes shown after toggling match what gets saved.
+      const managedAppearances: ReadonlyArray<ThemeAppearance> =
+        modeSelection === "both" ? ["light", "dark"] : [activeAppearance];
+      setSimpleColorsDirtyByAppearance((current) => {
+        const next = { ...current };
+        for (const appearance of managedAppearances) next[appearance] = true;
+        return next;
+      });
+      setColorsByAppearance((current) => {
+        const next = { ...current };
+        for (const appearance of managedAppearances) {
+          next[appearance] = getManagedEditorColors(appearance, current[appearance]);
+        }
+        return next;
+      });
+    },
+    [activeAppearance, modeSelection],
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (!name.trim()) {
+      setError("Give your theme a name before saving it.");
+      return;
+    }
+
+    try {
+      const baseAppearance =
+        editingTheme && modeSelection === "both" ? editingTheme.appearance : activeAppearance;
+      const variantAppearance = baseAppearance === "light" ? "dark" : "light";
+      // Only regenerate palettes the user actually touched in guided mode, so
+      // untouched appearances save exactly what the editor displayed.
+      const colorsForSave = !isAdvanced
+        ? {
+            light: simpleColorsDirtyByAppearance.light
+              ? getManagedEditorColors("light", colorsByAppearance.light)
+              : colorsByAppearance.light,
+            dark: simpleColorsDirtyByAppearance.dark
+              ? getManagedEditorColors("dark", colorsByAppearance.dark)
+              : colorsByAppearance.dark,
+          }
+        : colorsByAppearance;
+      const variants =
+        modeSelection === "both"
+          ? { [variantAppearance]: colorsForSave[variantAppearance] }
+          : undefined;
+      const themeFile = {
+        version: THEME_FILE_VERSION,
+        ...(editingTheme ? { id: editingTheme.id } : {}),
+        name,
+        appearance: baseAppearance,
+        colors: colorsForSave[baseAppearance],
+        ...(variants ? { variants } : {}),
+      };
+      const savedTheme = editingTheme
+        ? updateCustomTheme(parseThemeFile(themeFile))
+        : installCustomTheme(parseThemeFile(themeFile));
+      onSaved(savedTheme);
+      onOpenChange(false);
+    } catch (cause) {
+      setError(
+        cause instanceof Error
+          ? cause.message
+          : isEditing
+            ? "Could not save the theme."
+            : "Could not create the theme.",
+      );
+    }
+  }, [
+    activeAppearance,
+    colorsByAppearance,
+    editingTheme,
+    isAdvanced,
+    isEditing,
+    modeSelection,
+    name,
+    onOpenChange,
+    onSaved,
+    simpleColorsDirtyByAppearance,
+  ]);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen) setError(null);
+        onOpenChange(nextOpen);
+      }}
+    >
+      <DialogPopup className="max-w-3xl overflow-hidden">
+        <DialogHeader>
+          <DialogTitle>{isEditing ? "Edit theme" : "Create theme"}</DialogTitle>
+          <DialogDescription>
+            {isEditing
+              ? "Update the name and colors for this personal theme."
+              : "Pick a palette for T3 Code. Add a dark version if you need one."}
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="space-y-5">
+          <label className="block space-y-2">
+            <span className="text-sm font-medium">Theme name</span>
+            <Input
+              autoFocus
+              onChange={(event) => setName(event.currentTarget.value)}
+              placeholder={isEditing ? "Theme name" : "e.g. Aurora"}
+              value={name}
+            />
+          </label>
+
+          <div className="space-y-2">
+            <span className="text-sm font-medium">Modes</span>
+            <div aria-label="Modes" className="grid grid-cols-2 gap-2" role="group">
+              <Button
+                aria-pressed={modeSelection === "single"}
+                variant={modeSelection === "single" ? "secondary" : "outline"}
+                onClick={() => setModeSelection("single")}
+              >
+                One mode
+              </Button>
+              <Button
+                aria-pressed={modeSelection === "both"}
+                variant={modeSelection === "both" ? "secondary" : "outline"}
+                onClick={() => setModeSelection("both")}
+              >
+                Light + dark
+              </Button>
+            </div>
+            <p className="text-xs leading-relaxed text-muted-foreground">
+              {modeSelection === "both"
+                ? "Use a separate palette for light and dark mode."
+                : "Use the same palette in both modes."}
+            </p>
+          </div>
+
+          <div className="space-y-2">
+            <span className="text-sm font-medium">
+              {modeSelection === "both" ? "Colors" : "Appearance"}
+            </span>
+            <div aria-label="Theme appearance" className="grid grid-cols-2 gap-2" role="group">
+              <Button
+                aria-pressed={activeAppearance === "light"}
+                variant={activeAppearance === "light" ? "secondary" : "outline"}
+                onClick={() => setActiveAppearance("light")}
+              >
+                <SunIcon />
+                Light
+              </Button>
+              <Button
+                aria-pressed={activeAppearance === "dark"}
+                variant={activeAppearance === "dark" ? "secondary" : "outline"}
+                onClick={() => setActiveAppearance("dark")}
+              >
+                <MoonIcon />
+                Dark
+              </Button>
+            </div>
+          </div>
+
+          <div className="space-y-3">
+            <div className="flex items-start justify-between gap-3">
+              <div>
+                <h3 className="text-sm font-medium">
+                  {isAdvanced ? "Theme colors" : "Guided colors"}
+                </h3>
+                <p className="text-xs leading-relaxed text-muted-foreground">
+                  {isAdvanced
+                    ? "Customize every color role used by T3 Code."
+                    : "Choose the mood. T3 Code keeps the palette balanced and readable."}
+                </p>
+              </div>
+              <label className="flex shrink-0 cursor-pointer items-center gap-2 pt-0.5 text-sm font-medium">
+                <span>Advanced</span>
+                <Switch
+                  aria-label="Use advanced theme colors"
+                  checked={isAdvanced}
+                  onCheckedChange={(checked) => handleAdvancedChange(Boolean(checked))}
+                />
+              </label>
+            </div>
+
+            {isAdvanced ? (
+              <>
+                <div className="space-y-2">
+                  <div>
+                    <h4 className="text-sm font-medium">Main colors</h4>
+                    <p className="text-xs leading-relaxed text-muted-foreground">
+                      Surfaces, text, accents, and message actions.
+                    </p>
+                  </div>
+                  <div className="grid gap-2 sm:grid-cols-2">
+                    {THEME_EDITOR_PRIMARY_ROLES.map((role) => (
+                      <ThemeColorField
+                        key={role}
+                        onChange={updateColor}
+                        role={role}
+                        value={colorsByAppearance[activeAppearance][role]}
+                      />
+                    ))}
+                  </div>
+                </div>
+
+                <div className="space-y-2">
+                  <div>
+                    <h4 className="text-sm font-medium">Status colors</h4>
+                    <p className="text-xs leading-relaxed text-muted-foreground">
+                      Errors, warnings, and update notices.
+                    </p>
+                  </div>
+                  <div className="grid gap-2 sm:grid-cols-2">
+                    {THEME_EDITOR_STATUS_ROLES.map((role) => (
+                      <ThemeColorField
+                        key={role}
+                        onChange={updateColor}
+                        role={role}
+                        value={colorsByAppearance[activeAppearance][role]}
+                      />
+                    ))}
+                  </div>
+                </div>
+
+                <div className="space-y-2">
+                  <div>
+                    <h4 className="text-sm font-medium">Additional colors</h4>
+                    <p className="text-xs leading-relaxed text-muted-foreground">
+                      Fine-tune the remaining interface, code, and terminal roles.
+                    </p>
+                  </div>
+                  <div className="grid gap-2 sm:grid-cols-2">
+                    {THEME_EDITOR_ADVANCED_ROLES.map((role) => (
+                      <ThemeColorField
+                        key={role}
+                        onChange={updateColor}
+                        role={role}
+                        value={colorsByAppearance[activeAppearance][role]}
+                      />
+                    ))}
+                  </div>
+                </div>
+              </>
+            ) : (
+              <>
+                <div className="grid gap-2 sm:grid-cols-2">
+                  {THEME_EDITOR_SIMPLE_ROLES.map((role) => (
+                    <ThemeColorField
+                      key={role}
+                      onChange={updateColor}
+                      role={role}
+                      label={role === "canvas" ? "Background tint" : "Accent color"}
+                      value={colorsByAppearance[activeAppearance][role]}
+                    />
+                  ))}
+                </div>
+              </>
+            )}
+          </div>
+
+          {error ? (
+            <Alert aria-live="polite" variant="error">
+              {error}
+            </Alert>
+          ) : null}
+        </DialogPanel>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button disabled={!name.trim()} onClick={handleSubmit}>
+            {isEditing ? (
+              "Save changes"
+            ) : (
+              <>
+                <PlusIcon />
+                Create theme
+              </>
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogPopup>
+    </Dialog>
+  );
+}
+
+function escapeJsonHtml(value: string): string {
+  return value.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+      })[character] ?? character,
+  );
+}
+
+function highlightJson(value: string): string {
+  const tokenPattern =
+    /"(?:\\.|[^"\\])*"|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null/g;
+  let highlighted = "";
+  let cursor = 0;
+
+  for (const match of value.matchAll(tokenPattern)) {
+    const token = match[0];
+    const index = match.index ?? 0;
+    highlighted += escapeJsonHtml(value.slice(cursor, index));
+
+    let tokenClass = "theme-json-number";
+    if (token.startsWith('"')) {
+      tokenClass = /^\s*:/.test(value.slice(index + token.length))
+        ? "theme-json-key"
+        : "theme-json-string";
+    } else if (token === "true" || token === "false" || token === "null") {
+      tokenClass = "theme-json-constant";
+    }
+    highlighted += `<span class="${tokenClass}">${escapeJsonHtml(token)}</span>`;
+    cursor = index + token.length;
+  }
+
+  return highlighted + escapeJsonHtml(value.slice(cursor));
+}
+
+function ThemeJsonEditor({
+  id,
+  value,
+  onChange,
+}: {
+  id: string;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const highlightRef = useRef<HTMLPreElement>(null);
+  const highlightedJson = useMemo(() => highlightJson(value), [value]);
+
+  const syncScroll = useCallback((event: UIEvent<HTMLTextAreaElement>) => {
+    const highlightElement = highlightRef.current;
+    if (!highlightElement) return;
+    highlightElement.scrollTop = event.currentTarget.scrollTop;
+    highlightElement.scrollLeft = event.currentTarget.scrollLeft;
+  }, []);
+
+  return (
+    <div className="relative overflow-hidden rounded-xl border border-input bg-background shadow-xs/5 focus-within:border-ring focus-within:ring-[3px] focus-within:ring-ring/24">
+      <pre
+        ref={highlightRef}
+        aria-hidden
+        className="pointer-events-none absolute inset-0 m-0 overflow-hidden whitespace-pre-wrap break-words p-3 font-mono text-[12px] leading-5 text-foreground"
+      >
+        <code dangerouslySetInnerHTML={{ __html: highlightedJson }} />
+      </pre>
+      <textarea
+        aria-label="Theme JSON"
+        className="relative z-10 block min-h-72 w-full resize-y overflow-auto bg-transparent p-3 font-mono text-[12px] leading-5 text-transparent caret-foreground outline-none placeholder:text-muted-foreground selection:bg-accent/30 selection:text-transparent"
+        id={id}
+        onChange={(event) => onChange(event.currentTarget.value)}
+        onScroll={syncScroll}
+        placeholder={
+          '{\n  "version": 1,\n  "name": "Aurora",\n  "appearance": "light",\n  "colors": { ... }\n}'
+        }
+        spellCheck={false}
+        value={value}
+      />
+    </div>
+  );
+}
+
+function ThemeImportDialog({
+  open,
+  onOpenChange,
+  onImported,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onImported: (theme: ThemeDefinition) => void;
+}) {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [json, setJson] = useState("");
+  const [fileName, setFileName] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [isReading, setIsReading] = useState(false);
+  const importRequestRef = useRef(0);
+
+  useEffect(() => {
+    importRequestRef.current += 1;
+    if (!open) return;
+    setJson("");
+    setFileName(null);
+    setError(null);
+    setIsReading(false);
+  }, [open]);
+
+  const handleFileChange = useCallback(async (event: ChangeEvent<HTMLInputElement>) => {
+    const file = event.currentTarget.files?.[0];
+    event.currentTarget.value = "";
+    if (!file) return;
+
+    const requestId = ++importRequestRef.current;
+    setIsReading(true);
+    try {
+      const fileText = await file.text();
+      if (requestId !== importRequestRef.current) return;
+      setJson(fileText);
+      setFileName(file.name);
+      setError(null);
+    } catch {
+      if (requestId !== importRequestRef.current) return;
+      setError("Could not read that file. Paste the JSON below instead.");
+    } finally {
+      if (requestId === importRequestRef.current) setIsReading(false);
+    }
+  }, []);
+
+  const handleSubmit = useCallback(() => {
+    try {
+      const installedTheme = installCustomTheme(parseThemeFile(JSON.parse(json)));
+      onImported(installedTheme);
+      onOpenChange(false);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : "That theme file is invalid.");
+    }
+  }, [json, onImported, onOpenChange]);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen) setError(null);
+        onOpenChange(nextOpen);
+      }}
+    >
+      <DialogPopup className="max-w-3xl overflow-hidden">
+        <DialogHeader>
+          <DialogTitle>Add a theme</DialogTitle>
+          <DialogDescription>
+            Choose a JSON file or paste one below. Both options use the same theme format.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="space-y-4">
+          <div className="flex flex-wrap items-center justify-between gap-3 rounded-xl border border-dashed border-border/80 bg-muted/20 px-3 py-3">
+            <div className="min-w-0">
+              <p className="text-sm font-medium">Theme file</p>
+              <p className="truncate text-xs text-muted-foreground">
+                {fileName ?? "Upload a .json file, or paste the contents below."}
+              </p>
+            </div>
+            <Button
+              disabled={isReading}
+              size="sm"
+              variant="outline"
+              onClick={() => fileInputRef.current?.click()}
+            >
+              <UploadIcon />
+              {isReading ? "Reading…" : "Choose JSON file"}
+            </Button>
+            <input
+              ref={fileInputRef}
+              accept=".json,application/json"
+              className="sr-only"
+              onChange={handleFileChange}
+              type="file"
+            />
+          </div>
+
+          <div className="space-y-2">
+            <div className="flex items-baseline justify-between gap-3">
+              <label className="text-sm font-medium" htmlFor="theme-json-editor">
+                Paste theme JSON
+              </label>
+              <span className="text-xs text-muted-foreground">JSON</span>
+            </div>
+            <ThemeJsonEditor id="theme-json-editor" onChange={setJson} value={json} />
+            <p className="text-xs leading-relaxed text-muted-foreground">
+              Export a theme from T3 Code to get a complete file, then edit the colors you want.
+            </p>
+          </div>
+
+          {error ? (
+            <Alert aria-live="polite" variant="error">
+              {error}
+            </Alert>
+          ) : null}
+        </DialogPanel>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button disabled={!json.trim() || isReading} onClick={handleSubmit}>
+            <PlusIcon />
+            Add theme
+          </Button>
+        </DialogFooter>
+      </DialogPopup>
+    </Dialog>
+  );
+}
+
+function downloadThemeFile(filename: string, contents: string): void {
+  const url = URL.createObjectURL(new Blob([contents], { type: "application/json" }));
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+function ThemePreviewCircle({ colors }: { colors: ThemeCardPreview["colors"] }) {
+  const gradient = [
+    `radial-gradient(circle at 14% 18%, ${colors.sidebar} 0%, color-mix(in srgb, ${colors.sidebar} 68%, transparent) 28%, transparent 66%)`,
+    `radial-gradient(circle at 86% 20%, ${colors.accentSurface} 0%, color-mix(in srgb, ${colors.accentSurface} 70%, transparent) 30%, transparent 68%)`,
+    `radial-gradient(circle at 82% 84%, ${colors.messageAction} 0%, color-mix(in srgb, ${colors.messageAction} 62%, transparent) 24%, transparent 62%)`,
+    `radial-gradient(circle at 18% 84%, ${colors.messageSurface} 0%, color-mix(in srgb, ${colors.messageSurface} 66%, transparent) 28%, transparent 66%)`,
+    `linear-gradient(145deg, ${colors.canvas} 0%, ${colors.surface} 100%)`,
+  ].join(", ");
+  return (
+    <span
+      aria-hidden
+      className="block size-14 shrink-0 rounded-full border-2 border-background shadow-sm"
+      style={{ backgroundColor: colors.canvas, backgroundImage: gradient }}
+    />
+  );
+}
+
+function ThemePreviewCircles({
+  activeMode,
+  label,
+  onSelectMode,
+  previews,
+}: {
+  activeMode: ThemeAppearance | null;
+  label: string;
+  onSelectMode: ((mode: ThemeAppearance) => void) | undefined;
+  previews: ThemeCardDefinition["previews"];
+}) {
+  return (
+    <div className="flex min-h-16 items-center justify-center gap-2.5 px-3 pt-3">
+      {previews.map((preview) => {
+        const isActive = activeMode === preview.mode;
+        const circle = <ThemePreviewCircle colors={preview.colors} />;
+        if (!onSelectMode) {
+          return (
+            <span
+              className="flex size-[68px] shrink-0 items-center justify-center"
+              key={preview.mode}
+            >
+              {circle}
+            </span>
+          );
+        }
+
+        return (
+          <button
+            aria-label={`Use ${label} ${preview.mode} mode`}
+            aria-pressed={isActive}
+            className={cn(
+              "relative flex size-[68px] shrink-0 cursor-pointer items-center justify-center rounded-full p-1 outline-none transition-transform focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card",
+              !isActive && "hover:scale-105",
+            )}
+            key={preview.mode}
+            onClick={(event) => {
+              event.stopPropagation();
+              onSelectMode(preview.mode);
+            }}
+            style={isActive ? { boxShadow: "inset 0 0 0 2px var(--ring)" } : undefined}
+            type="button"
+          >
+            {circle}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+function ThemeLibraryCard({
+  theme,
+  isActive,
+  isPersonal,
+  onUse,
+  onUseMode,
+  activeMode,
+  onEdit,
+  onDownload,
+  onRemove,
+}: {
+  theme: ThemeCardDefinition;
+  isActive: boolean;
+  isPersonal: boolean;
+  onUse: () => void;
+  onUseMode?: ((mode: ThemeAppearance) => void) | undefined;
+  activeMode?: ThemeAppearance | null;
+  onEdit?: () => void;
+  onDownload?: () => void;
+  onRemove?: () => void;
+}) {
+  return (
+    // The card surface stays a plain div (buttons cannot nest inside a button
+    // role); the title button and mode circles carry the accessible actions,
+    // while the card click is a pointer-only convenience.
+    <div
+      className={cn(
+        "cursor-pointer overflow-hidden rounded-xl border border-border/70 bg-card/60 transition-colors hover:bg-accent/10",
+        isActive && "bg-accent/30",
+      )}
+      data-theme-library-card={theme.id}
+      onClick={onUse}
+      style={isActive ? { boxShadow: "inset 0 0 0 1px var(--ring)" } : undefined}
+    >
+      <ThemePreviewCircles
+        activeMode={isActive ? (activeMode ?? theme.previews[0]?.mode ?? null) : null}
+        label={theme.label}
+        onSelectMode={onUseMode}
+        previews={theme.previews}
+      />
+      <div className="flex items-center gap-2 px-3 pb-3 pt-2">
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-1.5">
+            <button
+              aria-label={`Use ${theme.label} theme${isActive ? ", currently active" : ""}`}
+              aria-pressed={isActive}
+              className="min-w-0 cursor-pointer truncate rounded-sm text-left text-sm font-medium text-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card"
+              type="button"
+              onClick={(event) => {
+                event.stopPropagation();
+                onUse();
+              }}
+            >
+              {theme.label}
+            </button>
+            {isPersonal ? (
+              <span className="shrink-0 rounded-full bg-accent px-1.5 py-0.5 text-[10px] font-medium text-accent-foreground">
+                Personal
+              </span>
+            ) : null}
+          </div>
+        </div>
+        {onEdit || onDownload || onRemove ? (
+          <div className="flex shrink-0 items-center gap-1">
+            {onEdit ? (
+              <Button
+                aria-label={`Edit ${theme.label}`}
+                size="icon-xs"
+                variant="ghost"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onEdit();
+                }}
+              >
+                <PenLineIcon />
+              </Button>
+            ) : null}
+            {onDownload ? (
+              <Button
+                aria-label={`Export ${theme.label}`}
+                size="icon-xs"
+                variant="ghost"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onDownload();
+                }}
+              >
+                <DownloadIcon />
+              </Button>
+            ) : null}
+            {onRemove ? (
+              <Button
+                aria-label={`Remove ${theme.label}`}
+                size="icon-xs"
+                variant="ghost"
+                className="text-muted-foreground hover:text-destructive"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onRemove();
+                }}
+              >
+                <Trash2Icon />
+              </Button>
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+export function ThemeLibrary({
+  theme,
+  setTheme,
+  followSystem,
+  setFollowSystem,
+  customThemes,
+  initialAppearance,
+  refreshTheme,
+}: {
+  theme: string;
+  setTheme: (theme: string) => boolean;
+  followSystem: boolean;
+  setFollowSystem: (followSystem: boolean) => boolean;
+  customThemes: ReadonlyArray<ThemeDefinition>;
+  initialAppearance: ThemeAppearance;
+  refreshTheme: () => void;
+}) {
+  const [isImportOpen, setIsImportOpen] = useState(false);
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const [themeToEdit, setThemeToEdit] = useState<ThemeDefinition | null>(null);
+  const [themeToRemove, setThemeToRemove] = useState<ThemeDefinition | null>(null);
+  // Keep the last removal target so the dialog title stays populated while the
+  // close animation plays after confirming.
+  const lastThemeToRemoveRef = useRef<ThemeDefinition | null>(null);
+  if (themeToRemove) lastThemeToRemoveRef.current = themeToRemove;
+  const removeDialogTheme = themeToRemove ?? lastThemeToRemoveRef.current;
+  const activeTheme = getThemeDefinition(theme);
+  const standardThemes = getStandardThemeCards();
+  const maintainerThemes = [T3_CHAT_THEME, T3_GROVE_THEME];
+
+  const handleFollowSystemChange = useCallback(
+    (checked: boolean) => {
+      // Keep the theme preference untouched when the follow-system write
+      // fails, so the two stored values cannot drift apart.
+      if (!setFollowSystem(checked)) return;
+      setTheme(
+        checked
+          ? (activeTheme?.id ?? "system")
+          : activeTheme
+            ? themePreferenceForMode(activeTheme, initialAppearance)
+            : initialAppearance,
+      );
+    },
+    [activeTheme, initialAppearance, setFollowSystem, setTheme],
+  );
+
+  const handleRemoveTheme = useCallback((customTheme: ThemeDefinition) => {
+    setThemeToRemove(customTheme);
+  }, []);
+
+  const handleConfirmRemoveTheme = useCallback(() => {
+    if (!themeToRemove) return;
+    // Keep the theme installed if we cannot move the selection off it; the
+    // dialog stays open so the user can retry or cancel.
+    if (
+      getThemeDefinition(theme)?.id === themeToRemove.id &&
+      !setTheme(followSystem ? "system" : initialAppearance)
+    ) {
+      return;
+    }
+    removeCustomTheme(themeToRemove.id);
+    setThemeToRemove(null);
+  }, [followSystem, initialAppearance, setTheme, theme, themeToRemove]);
+
+  const handleCreatedTheme = useCallback(
+    (createdTheme: ThemeDefinition) => {
+      setTheme(createdTheme.id);
+      toastManager.add(
+        stackedThreadToast({
+          type: "success",
+          title: `${createdTheme.label} created`,
+          description: "It’s now active.",
+        }),
+      );
+    },
+    [setTheme],
+  );
+
+  const handleEditedTheme = useCallback(
+    (updatedTheme: ThemeDefinition) => {
+      const wasActive = getThemeDefinition(theme)?.id === updatedTheme.id;
+      if (wasActive) {
+        const selectedMode = followSystem ? null : getThemePreferenceMode(theme);
+        const nextTheme =
+          selectedMode && getThemeColorsForMode(updatedTheme, selectedMode)
+            ? themePreferenceForMode(updatedTheme, selectedMode)
+            : updatedTheme.id;
+        setTheme(nextTheme);
+        refreshTheme();
+      }
+      setThemeToEdit(null);
+      toastManager.add(
+        stackedThreadToast({
+          type: "success",
+          title: `${updatedTheme.label} saved`,
+          description: wasActive ? "Your changes are now active." : "Your changes are saved.",
+        }),
+      );
+    },
+    [followSystem, refreshTheme, setTheme, theme],
+  );
+
+  return (
+    <div className="space-y-3 pt-2">
+      <div className="flex min-h-8 flex-wrap items-center justify-between gap-3 px-3 sm:px-4">
+        <h3 className="text-sm font-medium tracking-[-0.005em] text-foreground">Themes</h3>
+        <div className="flex flex-wrap items-center justify-end gap-3">
+          <label className="flex cursor-pointer items-center gap-2 text-xs text-muted-foreground">
+            <span>Follow system</span>
+            <Switch
+              aria-label="Follow system appearance"
+              checked={followSystem}
+              onCheckedChange={(checked) => handleFollowSystemChange(Boolean(checked))}
+            />
+          </label>
+          <Button size="xs" variant="outline" onClick={() => setIsCreateOpen(true)}>
+            <PlusIcon />
+            Create theme
+          </Button>
+          <Button size="xs" variant="ghost" onClick={() => setIsImportOpen(true)}>
+            <UploadIcon />
+            Import JSON
+          </Button>
+        </div>
+      </div>
+      <p className="px-3 text-[13px] leading-[1.45] text-muted-foreground/80 sm:px-4">
+        Choose how T3 Code looks. Use a built-in theme or make your own.
+      </p>
+      <div
+        className="mx-auto grid w-full max-w-[56rem] gap-2 px-3 sm:px-4"
+        style={{ gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 17rem), 1fr))" }}
+      >
+        {standardThemes.map((standardTheme) => (
+          <ThemeLibraryCard
+            activeMode={
+              theme === "system" || theme === "light" || theme === "dark"
+                ? (getThemePreferenceMode(theme) ?? initialAppearance)
+                : null
+            }
+            isActive={theme === "system" || theme === "light" || theme === "dark"}
+            isPersonal={false}
+            key={standardTheme.id}
+            onUse={() => setTheme(followSystem ? "system" : initialAppearance)}
+            onUseMode={followSystem ? undefined : setTheme}
+            theme={standardTheme}
+          />
+        ))}
+        {maintainerThemes.map((maintainerTheme) => {
+          const isActive = getThemeDefinition(theme)?.id === maintainerTheme.id;
+          const mode = isActive
+            ? followSystem
+              ? initialAppearance
+              : (getThemePreferenceMode(theme) ?? maintainerTheme.appearance)
+            : maintainerTheme.appearance;
+          return (
+            <ThemeLibraryCard
+              activeMode={isActive ? mode : null}
+              isActive={isActive}
+              isPersonal={false}
+              key={maintainerTheme.id}
+              onUse={() => setTheme(maintainerTheme.id)}
+              onUseMode={
+                followSystem
+                  ? undefined
+                  : (nextMode: ThemeAppearance) =>
+                      setTheme(themePreferenceForMode(maintainerTheme.id, nextMode))
+              }
+              theme={getThemeCardDefinition(maintainerTheme)}
+            />
+          );
+        })}
+        {customThemes.map((customTheme) => {
+          const isActive = getThemeDefinition(theme)?.id === customTheme.id;
+          const mode = isActive
+            ? followSystem
+              ? initialAppearance
+              : (getThemePreferenceMode(theme) ?? customTheme.appearance)
+            : customTheme.appearance;
+          return (
+            <ThemeLibraryCard
+              activeMode={isActive ? mode : null}
+              isActive={isActive}
+              isPersonal
+              key={customTheme.id}
+              onEdit={() => setThemeToEdit(customTheme)}
+              onDownload={() =>
+                downloadThemeFile(`${customTheme.id}.json`, serializeThemeFile(customTheme))
+              }
+              onRemove={() => handleRemoveTheme(customTheme)}
+              onUse={() => setTheme(customTheme.id)}
+              onUseMode={
+                followSystem
+                  ? undefined
+                  : (nextMode: ThemeAppearance) =>
+                      setTheme(themePreferenceForMode(customTheme.id, nextMode))
+              }
+              theme={getThemeCardDefinition(customTheme)}
+            />
+          );
+        })}
+      </div>
+      {customThemes.length === 0 ? (
+        <div className="mx-3 rounded-xl border border-dashed border-border/80 bg-muted/20 px-4 py-3 text-xs text-muted-foreground sm:mx-4">
+          Your themes will show up here.
+        </div>
+      ) : null}
+      <ThemeEditorDialog
+        editingTheme={themeToEdit}
+        initialAppearance={initialAppearance}
+        onSaved={themeToEdit ? handleEditedTheme : handleCreatedTheme}
+        onOpenChange={(open) => {
+          if (!open) {
+            setIsCreateOpen(false);
+            setThemeToEdit(null);
+          }
+        }}
+        open={isCreateOpen || themeToEdit !== null}
+      />
+      <ThemeImportDialog
+        onImported={(importedTheme) => {
+          setTheme(importedTheme.id);
+          toastManager.add(
+            stackedThreadToast({
+              type: "success",
+              title: `${importedTheme.label} added`,
+              description: "It’s now active.",
+            }),
+          );
+        }}
+        onOpenChange={setIsImportOpen}
+        open={isImportOpen}
+      />
+      <AlertDialog
+        open={themeToRemove !== null}
+        onOpenChange={(open) => {
+          if (!open) setThemeToRemove(null);
+        }}
+      >
+        <AlertDialogPopup>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Remove “{removeDialogTheme?.label}”?</AlertDialogTitle>
+            <AlertDialogDescription>
+              This removes the theme from your saved themes. You can add it again by importing its
+              JSON file.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogClose render={<Button variant="outline" />}>Cancel</AlertDialogClose>
+            <Button variant="destructive" onClick={handleConfirmRemoveTheme}>
+              Remove theme
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogPopup>
+      </AlertDialog>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
index b28b967eefa..6e490f4352c 100644
--- a/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
+++ b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
@@ -13,7 +13,7 @@ import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 
 const PROVIDER_UPDATE_PILL_STYLES = {
   loading:
-    "bg-primary/15 text-primary group-has-[button.provider-update-main:hover]/provider-update:bg-primary/22",
+    "bg-update-surface text-update group-has-[button.provider-update-main:hover]/provider-update:bg-update/22",
   success:
     "bg-success/12 text-success group-has-[button.provider-update-main:hover]/provider-update:bg-success/18",
   warning:
diff --git a/apps/web/src/components/sidebar/SidebarUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
index fb95dc11a4c..177ac01a613 100644
--- a/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
+++ b/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
@@ -150,11 +150,11 @@ export function SidebarUpdatePill() {
       )}
       {visible && (
         <div
-          className={`group/update relative flex h-7 w-full items-center rounded-lg bg-primary/15 text-xs font-medium text-primary ${
+          className={`group/update relative flex h-7 w-full items-center rounded-lg bg-update-surface text-xs font-medium text-update ${
             disabled ? " cursor-not-allowed opacity-60" : ""
           }`}
         >
-          <div className="pointer-events-none absolute inset-0 rounded-lg transition-colors group-has-[button.update-main:hover]/update:bg-primary/22" />
+          <div className="pointer-events-none absolute inset-0 rounded-lg transition-colors group-has-[button.update-main:hover]/update:bg-update/12" />
           <Tooltip>
             <TooltipTrigger
               render={
@@ -213,7 +213,7 @@ export function SidebarUpdatePill() {
                   <button
                     type="button"
                     aria-label="Dismiss update"
-                    className="mr-1 inline-flex size-5 items-center justify-center rounded-md text-primary/60 transition-colors hover:text-primary"
+                    className="mr-1 inline-flex size-5 items-center justify-center rounded-md text-update/60 transition-colors hover:text-update"
                     onClick={() => setDismissed(true)}
                   >
                     <XIcon className="size-3.5" />
diff --git a/apps/web/src/components/ui/alert.tsx b/apps/web/src/components/ui/alert.tsx
index 20be44dd3e5..02ef932e9f5 100644
--- a/apps/web/src/components/ui/alert.tsx
+++ b/apps/web/src/components/ui/alert.tsx
@@ -12,10 +12,11 @@ const alertVariants = cva("relative rounded-xl border px-3.5 py-3 text-card-fore
     variant: {
       default: "bg-transparent dark:bg-input/32 [&_svg]:text-muted-foreground",
       error:
-        "border-destructive/32 bg-destructive/4 text-destructive-foreground [&_[data-slot=alert-description]]:text-destructive-foreground/80 [&_svg]:text-destructive",
+        "border-error/32 bg-error-surface text-error-foreground [&_[data-slot=alert-description]]:text-error-foreground/80 [&_svg]:text-error",
       info: "border-info/32 bg-info/4 [&_svg]:text-info",
       success: "border-success/32 bg-success/4 [&_svg]:text-success",
-      warning: "border-warning/32 bg-warning/4 [&_svg]:text-warning",
+      warning:
+        "border-warning/32 bg-warning-surface text-warning-foreground [&_[data-slot=alert-description]]:text-warning-foreground/80 [&_svg]:text-warning",
     },
   },
 });
diff --git a/apps/web/src/components/ui/command.tsx b/apps/web/src/components/ui/command.tsx
index 0a713b769ec..06ce8d0b2d5 100644
--- a/apps/web/src/components/ui/command.tsx
+++ b/apps/web/src/components/ui/command.tsx
@@ -112,12 +112,12 @@ function CommandInput({
       <AutocompleteInput
         autoFocus
         className={cn(
-          "border-transparent! bg-transparent! shadow-none before:hidden has-focus-visible:ring-0 placeholder:text-muted-foreground/80 *:data-[slot=autocomplete-input]:ps-9! sm:*:data-[slot=autocomplete-input]:ps-[calc(var(--command-shell-inset)+1.5rem)]!",
+          "border-transparent! bg-transparent! shadow-none before:hidden has-focus-visible:ring-0 placeholder:text-placeholder *:data-[slot=autocomplete-input]:ps-9! sm:*:data-[slot=autocomplete-input]:ps-[calc(var(--command-shell-inset)+1.5rem)]!",
           className,
         )}
         placeholder={placeholder}
         size="lg"
-        startAddon={<SearchIcon className="translate-x-0.5 text-muted-foreground" />}
+        startAddon={<SearchIcon className="translate-x-0.5 text-icon-muted" />}
         {...props}
       />
     </div>
@@ -203,7 +203,7 @@ function CommandShortcut({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd
       className={cn(
-        "ms-auto font-medium font-sans text-muted-foreground/70 text-xs tracking-widest",
+        "ms-auto font-medium font-sans text-secondary-label text-xs tracking-widest",
         className,
       )}
       data-slot="command-shortcut"
diff --git a/apps/web/src/components/ui/input.tsx b/apps/web/src/components/ui/input.tsx
index 7ab7eb6cea0..6edc8d4a62f 100644
--- a/apps/web/src/components/ui/input.tsx
+++ b/apps/web/src/components/ui/input.tsx
@@ -19,7 +19,7 @@ function Input({
   ...props
 }: InputProps) {
   const inputClassName = cn(
-    "h-8.5 w-full min-w-0 rounded-[inherit] px-[calc(--spacing(3)-1px)] leading-8.5 outline-none placeholder:text-muted-foreground/72 sm:h-7.5 sm:leading-7.5 [transition:background-color_5000000s_ease-in-out_0s]",
+    "h-8.5 w-full min-w-0 rounded-[inherit] px-[calc(--spacing(3)-1px)] leading-8.5 outline-none placeholder:text-placeholder sm:h-7.5 sm:leading-7.5 [transition:background-color_5000000s_ease-in-out_0s]",
     size === "sm" && "h-7.5 px-[calc(--spacing(2.5)-1px)] leading-7.5 sm:h-6.5 sm:leading-6.5",
     size === "lg" && "h-9.5 leading-9.5 sm:h-8.5 sm:leading-8.5",
     props.type === "search" &&
diff --git a/apps/web/src/components/ui/menu.tsx b/apps/web/src/components/ui/menu.tsx
index c2b130e51ac..efd7af8800d 100644
--- a/apps/web/src/components/ui/menu.tsx
+++ b/apps/web/src/components/ui/menu.tsx
@@ -203,7 +203,7 @@ function MenuShortcut({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd
       className={cn(
-        "ms-auto font-medium font-sans text-muted-foreground/72 text-xs tracking-widest",
+        "ms-auto font-medium font-sans text-secondary-label text-xs tracking-widest",
         className,
       )}
       data-slot="menu-shortcut"
diff --git a/apps/web/src/components/ui/select.tsx b/apps/web/src/components/ui/select.tsx
index 949beddd05c..9a589c8d8df 100644
--- a/apps/web/src/components/ui/select.tsx
+++ b/apps/web/src/components/ui/select.tsx
@@ -21,9 +21,9 @@ const selectTriggerVariants = cva(
     variants: {
       variant: {
         default:
-          "w-full min-w-36 border-input bg-background not-dark:bg-clip-padding text-foreground shadow-xs/5 ring-ring/24 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] not-data-disabled:not-focus-visible:not-aria-invalid:not-data-pressed:before:shadow-[0_1px_--theme(--color-black/4%)] pointer-coarse:after:absolute pointer-coarse:after:size-full pointer-coarse:after:min-h-11 focus-visible:border-ring focus-visible:ring-[3px] aria-invalid:border-destructive/36 focus-visible:aria-invalid:border-destructive/64 focus-visible:aria-invalid:ring-destructive/16 dark:bg-input/32 dark:aria-invalid:ring-destructive/24 dark:not-data-disabled:not-focus-visible:not-aria-invalid:not-data-pressed:before:shadow-[0_-1px_--theme(--color-white/6%)] [&_svg:not([class*='opacity-'])]:opacity-80 [&_svg:not([class*='text-'])]:text-muted-foreground [[data-disabled],:focus-visible,[aria-invalid],[data-pressed]]:shadow-none",
+          "w-full min-w-36 border-input bg-background not-dark:bg-clip-padding text-foreground shadow-xs/5 ring-ring/24 before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] not-data-disabled:not-focus-visible:not-aria-invalid:not-data-pressed:before:shadow-[0_1px_--theme(--color-black/4%)] pointer-coarse:after:absolute pointer-coarse:after:size-full pointer-coarse:after:min-h-11 focus-visible:border-ring focus-visible:ring-[3px] aria-invalid:border-destructive/36 focus-visible:aria-invalid:border-destructive/64 focus-visible:aria-invalid:ring-destructive/16 dark:bg-input/32 dark:aria-invalid:ring-destructive/24 dark:not-data-disabled:not-focus-visible:not-aria-invalid:not-data-pressed:before:shadow-[0_-1px_--theme(--color-white/6%)] [&_svg:not([class*='opacity-'])]:opacity-80 [&_svg:not([class*='text-'])]:text-icon-muted [[data-disabled],:focus-visible,[aria-invalid],[data-pressed]]:shadow-none",
         ghost:
-          "border-transparent text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring data-pressed:bg-accent [:hover,[data-pressed]]:bg-accent [:hover,[data-pressed]]:text-foreground/80",
+          "border-transparent text-secondary-label focus-visible:ring-2 focus-visible:ring-ring data-pressed:bg-accent [:hover,[data-pressed]]:bg-accent [:hover,[data-pressed]]:text-foreground",
       },
       size: {
         default: "min-h-9 px-[calc(--spacing(3)-1px)] sm:min-h-8",
@@ -50,9 +50,7 @@ function SelectButton({ className, size, variant, render, children, ...props }:
   const defaultProps = {
     children: (
       <>
-        <span className="flex-1 truncate in-data-placeholder:text-muted-foreground/72">
-          {children}
-        </span>
+        <span className="flex-1 truncate in-data-placeholder:text-placeholder">{children}</span>
         {variant === "ghost" ? (
           <ChevronDownIcon className="-me-1 size-3 opacity-50" />
         ) : (
@@ -98,7 +96,7 @@ function SelectTrigger({
 function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
   return (
     <SelectPrimitive.Value
-      className={cn("flex-1 truncate data-placeholder:text-muted-foreground", className)}
+      className={cn("flex-1 truncate data-placeholder:text-placeholder", className)}
       data-slot="select-value"
       {...props}
     />
diff --git a/apps/web/src/hooks/useCustomThemes.ts b/apps/web/src/hooks/useCustomThemes.ts
new file mode 100644
index 00000000000..a8b351fa0ee
--- /dev/null
+++ b/apps/web/src/hooks/useCustomThemes.ts
@@ -0,0 +1,9 @@
+import { useSyncExternalStore } from "react";
+
+import { getCustomThemes, subscribeToCustomThemes } from "../themePalette";
+
+const EMPTY_CUSTOM_THEMES: readonly [] = [];
+
+export function useCustomThemes() {
+  return useSyncExternalStore(subscribeToCustomThemes, getCustomThemes, () => EMPTY_CUSTOM_THEMES);
+}
diff --git a/apps/web/src/hooks/useTheme.test.ts b/apps/web/src/hooks/useTheme.test.ts
index 6c814e30165..ab87388ff29 100644
--- a/apps/web/src/hooks/useTheme.test.ts
+++ b/apps/web/src/hooks/useTheme.test.ts
@@ -70,6 +70,18 @@ describe("theme failure handling", () => {
     }
   });
 
+  it("reads the persisted T3 Chat theme preference", async () => {
+    vi.stubGlobal("window", {
+      localStorage: createStorage({
+        getItem: () => "t3-chat",
+      }),
+    });
+
+    const { readThemePreference } = await import("./useTheme");
+
+    expect(readThemePreference()).toBe("t3-chat");
+  });
+
   it("falls back during initial theme application and logs only safe attributes", async () => {
     const cause = new Error("private browsing storage failure");
     const errorLog = vi.spyOn(console, "error").mockImplementation(() => {});
@@ -104,9 +116,10 @@ describe("theme failure handling", () => {
 
   it("retries a failed storage read only after a relevant storage event", async () => {
     const cause = new Error("persistent storage failure");
-    const getItem = vi.fn(() => {
+    const themeGetItem = vi.fn((): string | null => {
       throw cause;
     });
+    const getItem = vi.fn((key: string) => (key === "t3code:theme" ? themeGetItem() : null));
     const errorLog = vi.spyOn(console, "error").mockImplementation(() => {});
     let readSnapshot: (() => unknown) | undefined;
     let subscribeToTheme: ((listener: () => void) => () => void) | undefined;
@@ -141,14 +154,14 @@ describe("theme failure handling", () => {
     readSnapshot?.();
     readSnapshot?.();
 
-    expect(getItem).toHaveBeenCalledTimes(1);
+    expect(themeGetItem).toHaveBeenCalledTimes(1);
     expect(errorLog).toHaveBeenCalledTimes(1);
 
     const unsubscribe = subscribeToTheme?.(() => undefined);
     storageHandler?.({ key: "t3code:theme" } as StorageEvent);
     readSnapshot?.();
 
-    expect(getItem).toHaveBeenCalledTimes(2);
+    expect(themeGetItem).toHaveBeenCalledTimes(2);
     expect(errorLog).toHaveBeenCalledTimes(2);
     unsubscribe?.();
   });
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index bdaf37f099d..de5c1674653 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -2,12 +2,23 @@ import type { DesktopBridge } from "@t3tools/contracts";
 import { safeErrorLogAttributes } from "@t3tools/client-runtime/errors";
 import * as Schema from "effect/Schema";
 import { useCallback, useEffect, useSyncExternalStore } from "react";
-
-const ThemePreference = Schema.Literals(["light", "dark", "system"]);
-type Theme = typeof ThemePreference.Type;
+import {
+  applyThemePalette,
+  CUSTOM_THEMES_STORAGE_KEY,
+  invalidateCustomThemes,
+  isKnownThemePreference,
+  isThemeFollowingSystem,
+  resolveDesktopTheme,
+  resolveThemeAppearance,
+  THEME_FOLLOW_SYSTEM_STORAGE_KEY,
+  ThemePreference,
+} from "../themePalette";
+
+type Theme = ThemePreference;
 type ThemeSnapshot = {
   theme: Theme;
   systemDark: boolean;
+  followSystem: boolean;
 };
 
 type DesktopThemeBridge = Pick<DesktopBridge, "setTheme">;
@@ -17,6 +28,7 @@ const MEDIA_QUERY = "(prefers-color-scheme: dark)";
 const DEFAULT_THEME_SNAPSHOT: ThemeSnapshot = {
   theme: "system",
   systemDark: false,
+  followSystem: true,
 };
 const THEME_COLOR_META_NAME = "theme-color";
 const DYNAMIC_THEME_COLOR_SELECTOR = `meta[name="${THEME_COLOR_META_NAME}"][data-dynamic-theme-color="true"]`;
@@ -53,11 +65,13 @@ export const isDesktopThemeSyncError = Schema.is(DesktopThemeSyncError);
 
 let listeners: Array<() => void> = [];
 let lastSnapshot: ThemeSnapshot | null = null;
-let lastDesktopTheme: Theme | null = null;
+let snapshotStale = true;
+let lastDesktopTheme: "light" | "dark" | "system" | null = null;
 let lastAppliedTheme: ThemeSnapshot | null = null;
 let themeStorageReadFailure: ThemeStorageError | null = null;
 
 function emitChange() {
+  snapshotStale = true;
   for (const listener of listeners) listener();
 }
 
@@ -69,6 +83,33 @@ function getSystemDark() {
   );
 }
 
+function readStoredFollowSystem(theme: Theme): boolean {
+  if (typeof window === "undefined") return theme === "system" || isThemeFollowingSystem(theme);
+
+  try {
+    const raw = window.localStorage.getItem(THEME_FOLLOW_SYSTEM_STORAGE_KEY);
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+  } catch {
+    // Fall back to the legacy theme value when the separate preference is unavailable.
+  }
+
+  return theme === "system" || isThemeFollowingSystem(theme);
+}
+
+function writeFollowSystemPreference(followSystem: boolean): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(THEME_FOLLOW_SYSTEM_STORAGE_KEY, String(followSystem));
+  } catch (cause) {
+    throw new ThemeStorageError({
+      operation: "write",
+      storageKey: THEME_FOLLOW_SYSTEM_STORAGE_KEY,
+      cause,
+    });
+  }
+}
+
 export function readThemePreference(): Theme {
   if (typeof window === "undefined") return DEFAULT_THEME_SNAPSHOT.theme;
   let raw: string | null;
@@ -81,7 +122,9 @@ export function readThemePreference(): Theme {
       cause,
     });
   }
-  if (raw === "light" || raw === "dark" || raw === "system") return raw;
+  if (raw !== null && isKnownThemePreference(raw)) {
+    return raw;
+  }
   return DEFAULT_THEME_SNAPSHOT.theme;
 }
 
@@ -161,34 +204,56 @@ function resolveBrowserChromeSurface(): HTMLElement {
 
 export function syncBrowserChromeTheme() {
   if (typeof document === "undefined" || typeof getComputedStyle === "undefined") return;
+  const rootStyles = getComputedStyle(document.documentElement);
+  const themeChromeColor = document.documentElement.dataset.themeId
+    ? normalizeThemeColor(rootStyles.getPropertyValue("--app-chrome-background"))
+    : null;
   const surfaceColor = normalizeThemeColor(
     getComputedStyle(resolveBrowserChromeSurface()).backgroundColor,
   );
   const fallbackColor = normalizeThemeColor(getComputedStyle(document.body).backgroundColor);
-  const backgroundColor = surfaceColor ?? fallbackColor;
+  const backgroundColor = themeChromeColor ?? surfaceColor ?? fallbackColor;
   if (!backgroundColor) return;
 
   document.documentElement.style.backgroundColor = backgroundColor;
   document.body.style.backgroundColor = backgroundColor;
-  ensureThemeColorMetaTag().setAttribute("content", backgroundColor);
+  // Update every theme-color meta: the browser reads whichever media-scoped
+  // element matches the OS, so mutating a single element is not enough.
+  const themeColorMetas = document.querySelectorAll<HTMLMetaElement>(
+    `meta[name="${THEME_COLOR_META_NAME}"]`,
+  );
+  if (themeColorMetas.length === 0) {
+    ensureThemeColorMetaTag().setAttribute("content", backgroundColor);
+    return;
+  }
+  for (const element of themeColorMetas) {
+    element.setAttribute("content", backgroundColor);
+  }
 }
 
 function applyTheme(theme: Theme, suppressTransitions = false) {
   if (typeof document === "undefined" || typeof window === "undefined") return;
-  const systemDark = theme === "system" ? getSystemDark() : false;
-  if (lastAppliedTheme?.theme === theme && lastAppliedTheme.systemDark === systemDark) {
-    syncDesktopTheme(theme);
+  const followSystem = readStoredFollowSystem(theme);
+  const systemDark = followSystem ? getSystemDark() : false;
+  if (
+    lastAppliedTheme?.theme === theme &&
+    lastAppliedTheme.systemDark === systemDark &&
+    lastAppliedTheme.followSystem === followSystem
+  ) {
+    syncDesktopTheme(theme, followSystem);
     return;
   }
 
   if (suppressTransitions) {
     document.documentElement.classList.add("no-transitions");
   }
-  const isDark = theme === "dark" || (theme === "system" && systemDark);
+  const resolvedAppearance = resolveThemeAppearance(theme, systemDark, followSystem);
+  applyThemePalette(theme, resolvedAppearance);
+  const isDark = resolvedAppearance === "dark";
   document.documentElement.classList.toggle("dark", isDark);
-  lastAppliedTheme = { theme, systemDark };
+  lastAppliedTheme = { theme, systemDark, followSystem };
   syncBrowserChromeTheme();
-  syncDesktopTheme(theme);
+  syncDesktopTheme(theme, followSystem);
   if (suppressTransitions) {
     // Force a reflow so the no-transitions class takes effect before removal
     // oxlint-disable-next-line no-unused-expressions
@@ -202,23 +267,25 @@ function applyTheme(theme: Theme, suppressTransitions = false) {
 export async function syncDesktopThemePreference(
   bridge: DesktopThemeBridge,
   theme: Theme,
+  followSystem?: boolean,
 ): Promise<void> {
   try {
-    await bridge.setTheme(theme);
+    await bridge.setTheme(resolveDesktopTheme(theme, followSystem));
   } catch (cause) {
     throw new DesktopThemeSyncError({ theme, cause });
   }
 }
 
-export function syncDesktopTheme(theme: Theme) {
+export function syncDesktopTheme(theme: Theme, followSystem?: boolean) {
   if (typeof window === "undefined") return;
   const bridge = window.desktopBridge;
-  if (!bridge || typeof bridge.setTheme !== "function" || lastDesktopTheme === theme) {
+  const desktopTheme = resolveDesktopTheme(theme, followSystem);
+  if (!bridge || typeof bridge.setTheme !== "function" || lastDesktopTheme === desktopTheme) {
     return;
   }
 
-  lastDesktopTheme = theme;
-  void syncDesktopThemePreference(bridge, theme).catch((cause: unknown) => {
+  lastDesktopTheme = desktopTheme;
+  void syncDesktopThemePreference(bridge, theme, followSystem).catch((cause: unknown) => {
     const error = isDesktopThemeSyncError(cause)
       ? cause
       : new DesktopThemeSyncError({ theme, cause });
@@ -226,7 +293,7 @@ export function syncDesktopTheme(theme: Theme) {
       theme: error.theme,
       ...safeErrorLogAttributes(error),
     });
-    if (lastDesktopTheme === theme) {
+    if (lastDesktopTheme === desktopTheme) {
       lastDesktopTheme = null;
     }
   });
@@ -239,14 +306,24 @@ if (typeof document !== "undefined" && typeof window !== "undefined") {
 
 function getSnapshot(): ThemeSnapshot {
   if (typeof window === "undefined") return DEFAULT_THEME_SNAPSHOT;
+  // Reading the preference hits localStorage, so only recompute after a
+  // change was signalled; useTheme consumers call this on every render.
+  if (!snapshotStale && lastSnapshot) return lastSnapshot;
+  snapshotStale = false;
   const theme = getStored();
-  const systemDark = theme === "system" ? getSystemDark() : false;
+  const followSystem = readStoredFollowSystem(theme);
+  const systemDark = followSystem ? getSystemDark() : false;
 
-  if (lastSnapshot && lastSnapshot.theme === theme && lastSnapshot.systemDark === systemDark) {
+  if (
+    lastSnapshot &&
+    lastSnapshot.theme === theme &&
+    lastSnapshot.systemDark === systemDark &&
+    lastSnapshot.followSystem === followSystem
+  ) {
     return lastSnapshot;
   }
 
-  lastSnapshot = { theme, systemDark };
+  lastSnapshot = { theme, systemDark, followSystem };
   return lastSnapshot;
 }
 
@@ -254,32 +331,53 @@ function getServerSnapshot() {
   return DEFAULT_THEME_SNAPSHOT;
 }
 
+function handleSystemAppearanceChange() {
+  const storedTheme = getStored();
+  if (readStoredFollowSystem(storedTheme)) applyTheme(storedTheme, true);
+  emitChange();
+}
+
+function handleStorageChange(e: StorageEvent) {
+  if (e.key === STORAGE_KEY) {
+    themeStorageReadFailure = null;
+    applyTheme(getStored(), true);
+    emitChange();
+  } else if (e.key === THEME_FOLLOW_SYSTEM_STORAGE_KEY) {
+    applyTheme(getStored(), true);
+    emitChange();
+  } else if (e.key === CUSTOM_THEMES_STORAGE_KEY || e.key === null) {
+    if (e.key === null) themeStorageReadFailure = null;
+    invalidateCustomThemes();
+    lastAppliedTheme = null;
+    applyTheme(getStored(), true);
+    emitChange();
+  }
+}
+
+let removeWindowListeners: (() => void) | null = null;
+
 function subscribe(listener: () => void): () => void {
   if (typeof window === "undefined") return () => {};
   listeners.push(listener);
 
-  // Listen for system preference changes
-  const mq = typeof window.matchMedia === "function" ? window.matchMedia(MEDIA_QUERY) : null;
-  const handleChange = () => {
-    if (getStored() === "system") applyTheme("system", true);
-    emitChange();
-  };
-  mq?.addEventListener("change", handleChange);
-
-  // Listen for storage changes from other tabs
-  const handleStorage = (e: StorageEvent) => {
-    if (e.key === STORAGE_KEY) {
-      themeStorageReadFailure = null;
-      applyTheme(getStored(), true);
-      emitChange();
-    }
-  };
-  window.addEventListener("storage", handleStorage);
+  // The system-preference and cross-tab listeners are shared by all
+  // subscribers; each event applies the theme once and notifies everyone.
+  if (!removeWindowListeners) {
+    const mq = typeof window.matchMedia === "function" ? window.matchMedia(MEDIA_QUERY) : null;
+    mq?.addEventListener("change", handleSystemAppearanceChange);
+    window.addEventListener("storage", handleStorageChange);
+    removeWindowListeners = () => {
+      mq?.removeEventListener("change", handleSystemAppearanceChange);
+      window.removeEventListener("storage", handleStorageChange);
+    };
+  }
 
   return () => {
     listeners = listeners.filter((l) => l !== listener);
-    mq?.removeEventListener("change", handleChange);
-    window.removeEventListener("storage", handleStorage);
+    if (listeners.length === 0) {
+      removeWindowListeners?.();
+      removeWindowListeners = null;
+    }
   };
 }
 
@@ -287,11 +385,14 @@ export function useTheme() {
   const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
   const theme = snapshot.theme;
 
-  const resolvedTheme: "light" | "dark" =
-    theme === "system" ? (snapshot.systemDark ? "dark" : "light") : theme;
+  const resolvedTheme: "light" | "dark" = resolveThemeAppearance(
+    theme,
+    snapshot.systemDark,
+    snapshot.followSystem,
+  );
 
-  const setTheme = useCallback((next: Theme) => {
-    if (typeof window === "undefined") return;
+  const setTheme = useCallback((next: Theme): boolean => {
+    if (typeof window === "undefined") return false;
     try {
       writeThemePreference(next);
     } catch (cause) {
@@ -309,16 +410,56 @@ export function useTheme() {
         theme: next,
         ...safeErrorLogAttributes(error),
       });
-      return;
+      return false;
     }
     applyTheme(next, true);
     emitChange();
+    return true;
+  }, []);
+
+  const setFollowSystem = useCallback((nextFollowSystem: boolean): boolean => {
+    if (typeof window === "undefined") return false;
+    try {
+      writeFollowSystemPreference(nextFollowSystem);
+    } catch (cause) {
+      const error = isThemeStorageError(cause)
+        ? cause
+        : new ThemeStorageError({
+            operation: "write",
+            storageKey: THEME_FOLLOW_SYSTEM_STORAGE_KEY,
+            cause,
+          });
+      console.error(error.message, {
+        operation: error.operation,
+        storageKey: error.storageKey,
+        ...safeErrorLogAttributes(error),
+      });
+      return false;
+    }
+    themeStorageReadFailure = null;
+    applyTheme(getStored(), true);
+    emitChange();
+    return true;
+  }, []);
+
+  const refreshTheme = useCallback(() => {
+    if (typeof window === "undefined") return;
+    lastAppliedTheme = null;
+    applyTheme(getStored(), true);
+    emitChange();
   }, []);
 
   // Keep DOM in sync on mount/change
   useEffect(() => {
     applyTheme(theme);
-  }, [theme]);
-
-  return { theme, setTheme, resolvedTheme } as const;
+  }, [snapshot.followSystem, theme]);
+
+  return {
+    theme,
+    setTheme,
+    setFollowSystem,
+    refreshTheme,
+    followSystem: snapshot.followSystem,
+    resolvedTheme,
+  } as const;
 }
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index b1ca197149a..3509590aa45 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -145,6 +145,13 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
     "SF Mono", "SFMono-Regular", "JetBrains Mono", Consolas, "Liberation Mono", Menlo, monospace;
   --color-warning-foreground: var(--warning-foreground);
   --color-warning: var(--warning);
+  --color-warning-surface: var(--warning-surface);
+  --color-error-foreground: var(--error-foreground);
+  --color-error: var(--error);
+  --color-error-surface: var(--error-surface);
+  --color-update-foreground: var(--update-foreground);
+  --color-update: var(--update);
+  --color-update-surface: var(--update-surface);
   --color-success-foreground: var(--success-foreground);
   --color-success: var(--success);
   --color-info-foreground: var(--info-foreground);
@@ -158,6 +165,9 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --color-accent: var(--accent);
   --color-muted-foreground: var(--muted-foreground);
   --color-muted: var(--muted);
+  --color-placeholder: var(--placeholder);
+  --color-secondary-label: var(--secondary-label);
+  --color-icon-muted: var(--icon-muted);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-secondary: var(--secondary);
   --color-primary-foreground: var(--primary-foreground);
@@ -169,6 +179,11 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --color-foreground: var(--foreground);
   --color-background: var(--background);
   --color-surface-raised: var(--surface-raised);
+  --color-message: var(--message-surface);
+  --color-message-foreground: var(--message-foreground);
+  --color-message-action: var(--message-action);
+  --color-message-action-foreground: var(--message-action-foreground);
+  --color-message-action-hover: var(--message-action-hover);
   --color-sidebar: var(--sidebar);
   --color-sidebar-foreground: var(--sidebar-foreground);
   --color-sidebar-muted-foreground: var(--sidebar-muted-foreground);
@@ -867,19 +882,34 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --secondary-foreground: var(--color-zinc-800);
   --muted: var(--color-zinc-50);
   --muted-foreground: var(--color-zinc-500);
+  --placeholder: var(--muted-foreground);
+  --secondary-label: var(--muted-foreground);
+  --icon-muted: var(--muted-foreground);
+  --message-surface: var(--accent);
+  --message-foreground: var(--foreground);
+  --message-action: var(--primary);
+  --message-action-foreground: var(--primary-foreground);
+  --message-action-hover: color-mix(in srgb, var(--primary) 90%, var(--background));
   --accent: var(--color-zinc-100);
   --accent-foreground: var(--color-zinc-900);
-  --destructive: var(--color-red-500);
+  --error: var(--color-red-500);
+  --error-foreground: var(--color-red-700);
+  --error-surface: color-mix(in srgb, var(--error) 8%, transparent);
+  --destructive: var(--error);
   --border: var(--color-zinc-200);
   --input: var(--color-zinc-300);
   --ring: oklch(0.488 0.217 264);
-  --destructive-foreground: var(--color-red-700);
+  --destructive-foreground: var(--error-foreground);
   --info: var(--color-blue-500);
   --info-foreground: var(--color-blue-700);
   --success: var(--color-emerald-500);
   --success-foreground: var(--color-emerald-700);
   --warning: var(--color-amber-500);
   --warning-foreground: var(--color-amber-700);
+  --warning-surface: color-mix(in srgb, var(--warning) 8%, transparent);
+  --update: var(--primary);
+  --update-foreground: var(--primary);
+  --update-surface: color-mix(in srgb, var(--update) 12%, transparent);
   /* Keep every sidebar primitive on the same light surface hierarchy, including
      portaled mobile sheets and settings navigation outside the app sidebar. */
   --sidebar: var(--color-zinc-50);
@@ -891,6 +921,14 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --sidebar-row-selected: var(--color-white);
   --sidebar-border: var(--border);
   --sidebar-stage-fade: var(--sidebar);
+  --code-background: color-mix(in srgb, var(--card) 90%, var(--background));
+  --code-foreground: var(--foreground);
+  --terminal-background: var(--background);
+  --terminal-foreground: var(--foreground);
+  --terminal-cursor: rgb(38 56 78);
+  --terminal-selection-background: rgb(37 63 99 / 20%);
+  --terminal-scrollbar: rgb(0 0 0 / 15%);
+  --terminal-scrollbar-hover: rgb(0 0 0 / 25%);
 
   @variant dark {
     color-scheme: dark;
@@ -910,19 +948,34 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
     --secondary-foreground: var(--color-neutral-100);
     --muted: --alpha(var(--color-white) / 4%);
     --muted-foreground: color-mix(in srgb, var(--color-neutral-500) 90%, var(--color-white));
+    --placeholder: var(--muted-foreground);
+    --secondary-label: var(--muted-foreground);
+    --icon-muted: var(--muted-foreground);
+    --message-surface: var(--accent);
+    --message-foreground: var(--foreground);
+    --message-action: var(--primary);
+    --message-action-foreground: var(--primary-foreground);
+    --message-action-hover: color-mix(in srgb, var(--primary) 90%, var(--background));
     --accent: --alpha(var(--color-white) / 4%);
     --accent-foreground: var(--color-neutral-100);
-    --destructive: color-mix(in srgb, var(--color-red-500) 90%, var(--color-white));
+    --error: color-mix(in srgb, var(--color-red-500) 90%, var(--color-white));
+    --error-foreground: var(--color-red-400);
+    --error-surface: color-mix(in srgb, var(--error) 16%, transparent);
+    --destructive: var(--error);
     --border: --alpha(var(--color-white) / 6%);
     --input: --alpha(var(--color-white) / 8%);
     --ring: oklch(0.588 0.217 264);
-    --destructive-foreground: var(--color-red-400);
+    --destructive-foreground: var(--error-foreground);
     --info: var(--color-blue-500);
     --info-foreground: var(--color-blue-400);
     --success: var(--color-emerald-500);
     --success-foreground: var(--color-emerald-400);
     --warning: var(--color-amber-500);
     --warning-foreground: var(--color-amber-400);
+    --warning-surface: color-mix(in srgb, var(--warning) 16%, transparent);
+    --update: var(--primary);
+    --update-foreground: var(--primary);
+    --update-surface: color-mix(in srgb, var(--update) 18%, transparent);
     --sidebar: var(--card);
     --sidebar-foreground: var(--foreground);
     --sidebar-muted-foreground: var(--muted-foreground);
@@ -932,6 +985,12 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
     --sidebar-row-selected: var(--muted);
     --sidebar-border: var(--border);
     --sidebar-stage-fade: var(--card);
+    --terminal-background: var(--background);
+    --terminal-foreground: var(--foreground);
+    --terminal-cursor: rgb(180 203 255);
+    --terminal-selection-background: rgb(180 203 255 / 25%);
+    --terminal-scrollbar: rgb(255 255 255 / 10%);
+    --terminal-scrollbar-hover: rgb(255 255 255 / 18%);
   }
 }
 
@@ -989,6 +1048,123 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --sidebar-stage-fade: var(--card);
 }
 
+/* Theme files are expressed in app color roles and mapped to the existing
+   semantic surface tokens here. Keep this block after the sidebar-version
+   compatibility overrides so both navigation implementations receive the
+   same palette. Success, info, provider, and channel identity colors remain
+   independent; error, warning, and update roles are themeable below. */
+html[data-theme-id],
+html.dark[data-theme-id] {
+  --background: var(--app-theme-canvas);
+  --app-chrome-background: var(--app-theme-chrome);
+  --surface-raised: var(--app-theme-surface-raised);
+  --foreground: var(--app-theme-text);
+  --card: var(--app-theme-surface);
+  --card-foreground: var(--app-theme-text);
+  --popover: var(--app-theme-surface-overlay);
+  --popover-foreground: var(--app-theme-text);
+  --primary: var(--app-theme-accent);
+  --primary-foreground: var(--app-theme-accent-foreground);
+  --secondary: var(--app-theme-secondary);
+  --secondary-foreground: var(--app-theme-secondary-foreground);
+  --muted: var(--app-theme-muted);
+  --muted-foreground: var(--app-theme-text-muted);
+  --placeholder: var(--app-theme-placeholder);
+  --secondary-label: var(--app-theme-secondary-label);
+  --icon-muted: var(--app-theme-icon-muted);
+  --accent: var(--app-theme-accent-surface);
+  --accent-foreground: var(--app-theme-accent-surface-foreground);
+  --message-surface: var(--app-theme-message-surface);
+  --message-foreground: var(--app-theme-message-foreground);
+  --message-action: var(--app-theme-message-action);
+  --message-action-foreground: var(--app-theme-message-action-foreground);
+  --message-action-hover: var(--app-theme-message-action-hover);
+  --error: var(--app-theme-error);
+  --error-foreground: var(--app-theme-error-foreground);
+  --error-surface: var(--app-theme-error-surface);
+  --destructive: var(--error);
+  --destructive-foreground: var(--error-foreground);
+  --warning: var(--app-theme-warning);
+  --warning-foreground: var(--app-theme-warning-foreground);
+  --warning-surface: var(--app-theme-warning-surface);
+  --update: var(--app-theme-update);
+  --update-foreground: var(--app-theme-update-foreground);
+  --update-surface: var(--app-theme-update-surface);
+  --border: var(--app-theme-border);
+  --input: var(--app-theme-input);
+  --ring: var(--app-theme-focus);
+  --sidebar: var(--app-theme-sidebar);
+  --sidebar-foreground: var(--app-theme-sidebar-foreground);
+  --sidebar-muted-foreground: var(--app-theme-sidebar-muted-foreground);
+  --sidebar-control-surface: var(--app-theme-sidebar-control-surface);
+  --sidebar-row-hover: var(--app-theme-sidebar-row-hover);
+  --sidebar-row-active: var(--app-theme-sidebar-row-active);
+  --sidebar-row-selected: var(--app-theme-sidebar-row-selected);
+  --sidebar-border: var(--app-theme-sidebar-border);
+  --sidebar-stage-fade: var(--app-theme-sidebar);
+  --code-background: var(--app-theme-code-background);
+  --code-foreground: var(--app-theme-code-foreground);
+  --terminal-background: var(--app-theme-terminal-background);
+  --terminal-foreground: var(--app-theme-terminal-foreground);
+  --terminal-cursor: var(--app-theme-terminal-cursor);
+  --terminal-selection-background: var(--app-theme-terminal-selection-background);
+  --terminal-scrollbar: var(--app-theme-terminal-scrollbar);
+  --terminal-scrollbar-hover: var(--app-theme-terminal-scrollbar-hover);
+}
+
+html[data-theme-id]:not(.dark) {
+  color-scheme: light;
+}
+
+html.dark[data-theme-id] {
+  color-scheme: dark;
+}
+
+html[data-theme-id] body {
+  background-color: var(--app-chrome-background);
+  color: var(--foreground);
+}
+
+html[data-theme-id] [data-sidebar-version="v1"],
+html[data-theme-id] [data-sidebar-version="v2"] {
+  --background: var(--app-theme-canvas);
+  --foreground: var(--app-theme-text);
+  --card: var(--app-theme-surface);
+  --card-foreground: var(--app-theme-text);
+  --accent: var(--app-theme-accent-surface);
+  --accent-foreground: var(--app-theme-accent-surface-foreground);
+  --muted: var(--app-theme-muted);
+  --muted-foreground: var(--app-theme-text-muted);
+  --border: var(--app-theme-border);
+  --input: var(--app-theme-input);
+  --sidebar: var(--app-theme-sidebar);
+  --sidebar-foreground: var(--app-theme-sidebar-foreground);
+  --sidebar-muted-foreground: var(--app-theme-sidebar-muted-foreground);
+  --sidebar-control-surface: var(--app-theme-sidebar-control-surface);
+  --sidebar-row-hover: var(--app-theme-sidebar-row-hover);
+  --sidebar-row-active: var(--app-theme-sidebar-row-active);
+  --sidebar-row-selected: var(--app-theme-sidebar-row-selected);
+  --sidebar-border: var(--app-theme-sidebar-border);
+  --sidebar-stage-fade: var(--app-theme-sidebar);
+  background-color: var(--sidebar);
+}
+
+.theme-json-key {
+  color: var(--app-theme-accent, var(--color-blue-600));
+}
+
+.theme-json-string {
+  color: var(--app-theme-message-action, var(--color-emerald-600));
+}
+
+.theme-json-number {
+  color: var(--app-theme-secondary-foreground, var(--color-amber-600));
+}
+
+.theme-json-constant {
+  color: var(--app-theme-accent-surface-foreground, var(--color-violet-600));
+}
+
 body {
   font-family:
     "DM Sans Variable",
@@ -1569,7 +1745,18 @@ label:has(> select#reasoning-effort) select {
   border: 1px solid var(--border);
   border-radius: 0.5rem;
   overflow: clip;
-  background: color-mix(in srgb, var(--card) 92%, var(--background));
+  background: var(--code-background);
+  color: var(--code-foreground);
+}
+
+/* Pierre's file renderer owns its own surface tokens. Keep the root of a file
+   preview on the same themeable code surface as the diff panel. */
+.file-preview-virtualizer diffs-container {
+  --diffs-bg: var(--code-background) !important;
+  --diffs-light-bg: var(--code-background) !important;
+  --diffs-dark-bg: var(--code-background) !important;
+  background-color: var(--code-background) !important;
+  color: var(--code-foreground) !important;
 }
 
 @keyframes ultrathink-rainbow {
diff --git a/apps/web/src/themeBoot.test.ts b/apps/web/src/themeBoot.test.ts
new file mode 100644
index 00000000000..01195aaafe5
--- /dev/null
+++ b/apps/web/src/themeBoot.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import indexHtml from "../index.html?raw";
+import {
+  CUSTOM_THEMES_STORAGE_KEY,
+  invalidateCustomThemes,
+  isKnownThemePreference,
+  isThemeFollowingSystem,
+  resolveThemeAppearance,
+  THEME_FOLLOW_SYSTEM_STORAGE_KEY,
+} from "./themePalette";
+
+const THEME_STORAGE_KEY = "t3code:theme";
+
+const bootScript = (() => {
+  const match = indexHtml.match(/<script>([\s\S]*?)<\/script>/);
+  if (!match?.[1]) throw new Error("Could not find the inline boot script in index.html");
+  return match[1];
+})();
+
+type BootResult = {
+  isDark: boolean;
+  themeId: string | undefined;
+  themeSelected: string | undefined;
+  backgroundColor: string;
+  bootVariables: Record<string, string>;
+  metaContent: string | null;
+};
+
+function runBootScript(options: {
+  storage?: Record<string, string>;
+  storageThrows?: boolean;
+  prefersDark: boolean;
+}): BootResult {
+  const classes = new Set<string>();
+  const bootVariables: Record<string, string> = {};
+  const meta = {
+    content: null as string | null,
+    setAttribute(_name: string, value: string) {
+      this.content = value;
+    },
+  };
+  const documentElement = {
+    dataset: {} as Record<string, string | undefined>,
+    classList: {
+      add: (name: string) => void classes.add(name),
+      remove: (name: string) => void classes.delete(name),
+      toggle: (name: string, force?: boolean) => {
+        const next = force ?? !classes.has(name);
+        if (next) classes.add(name);
+        else classes.delete(name);
+        return next;
+      },
+    },
+    style: {
+      backgroundColor: "",
+      setProperty: (name: string, value: string) => {
+        bootVariables[name] = value;
+      },
+    },
+  };
+  const fakeDocument = {
+    documentElement,
+    querySelectorAll: (selector: string) => (selector === 'meta[name="theme-color"]' ? [meta] : []),
+  };
+  const fakeWindow = {
+    localStorage: {
+      getItem: (key: string): string | null => {
+        if (options.storageThrows) throw new Error("storage blocked");
+        return options.storage?.[key] ?? null;
+      },
+    },
+    matchMedia: () => ({ matches: options.prefersDark }),
+  };
+
+  new Function("window", "document", bootScript)(fakeWindow, fakeDocument);
+
+  return {
+    isDark: classes.has("dark"),
+    themeId: documentElement.dataset.themeId,
+    themeSelected: documentElement.dataset.themeSelected,
+    backgroundColor: documentElement.style.backgroundColor,
+    bootVariables,
+    metaContent: meta.content,
+  };
+}
+
+/** Mirrors getStored + readStoredFollowSystem + resolveThemeAppearance from the runtime. */
+function runtimeResolvedAppearance(
+  storage: Record<string, string>,
+  prefersDark: boolean,
+): "light" | "dark" {
+  vi.stubGlobal("window", {
+    localStorage: { getItem: (key: string) => storage[key] ?? null },
+    matchMedia: () => ({ matches: prefersDark }),
+  });
+  invalidateCustomThemes();
+  try {
+    const raw = storage[THEME_STORAGE_KEY] ?? null;
+    const theme = raw !== null && isKnownThemePreference(raw) ? raw : "system";
+    const followRaw = storage[THEME_FOLLOW_SYSTEM_STORAGE_KEY] ?? null;
+    const followSystem =
+      followRaw === "true"
+        ? true
+        : followRaw === "false"
+          ? false
+          : theme === "system" || isThemeFollowingSystem(theme);
+    return resolveThemeAppearance(theme, prefersDark, followSystem);
+  } finally {
+    vi.unstubAllGlobals();
+    invalidateCustomThemes();
+  }
+}
+
+const AURORA_DUAL = {
+  id: "aurora",
+  label: "Aurora",
+  appearance: "light",
+  colors: { canvas: "#f8fbff", text: "#10243d", accent: "#5b6cff" },
+  variants: { dark: { canvas: "#101827", text: "#eef5ff", accent: "#7c93ff" } },
+};
+const EMBER_DARK_ONLY = {
+  id: "ember",
+  label: "Ember",
+  appearance: "dark",
+  colors: { canvas: "#1c1210", text: "#ffe8d9", accent: "#ff7a45" },
+};
+
+describe("index.html boot script", () => {
+  const parityCases: ReadonlyArray<{
+    name: string;
+    storage: Record<string, string>;
+    prefersDark: boolean;
+  }> = [
+    { name: "no stored preference on a dark OS", storage: {}, prefersDark: true },
+    {
+      name: "T3 Chat clamps follow-system to its light-only palette",
+      storage: { [THEME_STORAGE_KEY]: "t3-chat", [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "true" },
+      prefersDark: true,
+    },
+    {
+      name: "T3 Grove follows a dark OS",
+      storage: { [THEME_STORAGE_KEY]: "t3-grove", [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "true" },
+      prefersDark: true,
+    },
+    {
+      name: "legacy t3-chat-dark resolves to light T3 Chat",
+      storage: { [THEME_STORAGE_KEY]: "t3-chat-dark" },
+      prefersDark: true,
+    },
+    {
+      name: "a dual-mode custom theme follows the OS",
+      storage: {
+        [THEME_STORAGE_KEY]: "aurora",
+        [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "true",
+        [CUSTOM_THEMES_STORAGE_KEY]: JSON.stringify([AURORA_DUAL]),
+      },
+      prefersDark: true,
+    },
+    {
+      name: "a dark-only custom theme stays dark on a light OS",
+      storage: {
+        [THEME_STORAGE_KEY]: "ember",
+        [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "true",
+        [CUSTOM_THEMES_STORAGE_KEY]: JSON.stringify([EMBER_DARK_ONLY]),
+      },
+      prefersDark: false,
+    },
+    {
+      name: "a stale mode suffix for a single-mode theme falls back to system",
+      storage: {
+        [THEME_STORAGE_KEY]: "aurora:dark",
+        [CUSTOM_THEMES_STORAGE_KEY]: JSON.stringify([{ ...AURORA_DUAL, variants: undefined }]),
+      },
+      prefersDark: true,
+    },
+    {
+      name: "a removed custom theme falls back to system",
+      storage: { [THEME_STORAGE_KEY]: "gone-theme" },
+      prefersDark: true,
+    },
+    {
+      name: "a corrupted follow-system value falls back to inference",
+      storage: { [THEME_STORAGE_KEY]: "system", [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "1" },
+      prefersDark: true,
+    },
+    {
+      name: "a system-suffixed theme follows the OS while follow-system is unset",
+      storage: {
+        [THEME_STORAGE_KEY]: "aurora:system",
+        [CUSTOM_THEMES_STORAGE_KEY]: JSON.stringify([AURORA_DUAL]),
+      },
+      prefersDark: true,
+    },
+    {
+      name: "follow-system off overrides a stale system suffix",
+      storage: {
+        [THEME_STORAGE_KEY]: "aurora:system",
+        [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "false",
+        [CUSTOM_THEMES_STORAGE_KEY]: JSON.stringify([AURORA_DUAL]),
+      },
+      prefersDark: true,
+    },
+    {
+      name: "follow-system off keeps an explicit light preference on a dark OS",
+      storage: { [THEME_STORAGE_KEY]: "light", [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "false" },
+      prefersDark: true,
+    },
+  ];
+
+  it.each(parityCases)("matches the runtime appearance: $name", ({ storage, prefersDark }) => {
+    const boot = runBootScript({ storage, prefersDark });
+    expect(boot.isDark).toBe(runtimeResolvedAppearance(storage, prefersDark) === "dark");
+  });
+
+  it("marks built-in and custom themes on the document element", () => {
+    const chat = runBootScript({
+      storage: { [THEME_STORAGE_KEY]: "t3-chat", [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "true" },
+      prefersDark: true,
+    });
+    expect(chat.themeId).toBe("t3-chat");
+    expect(chat.themeSelected).toBe("true");
+    expect(chat.isDark).toBe(false);
+
+    const aurora = runBootScript({
+      storage: {
+        [THEME_STORAGE_KEY]: "aurora",
+        [THEME_FOLLOW_SYSTEM_STORAGE_KEY]: "true",
+        [CUSTOM_THEMES_STORAGE_KEY]: JSON.stringify([AURORA_DUAL]),
+      },
+      prefersDark: true,
+    });
+    expect(aurora.themeId).toBe("aurora");
+    expect(aurora.isDark).toBe(true);
+    expect(aurora.backgroundColor).toBe(AURORA_DUAL.variants.dark.canvas);
+    expect(aurora.bootVariables["--boot-background"]).toBe(AURORA_DUAL.variants.dark.canvas);
+    expect(aurora.metaContent).toBe(AURORA_DUAL.variants.dark.canvas);
+  });
+
+  it("leaves unknown preferences unthemed so the runtime default applies", () => {
+    const boot = runBootScript({
+      storage: { [THEME_STORAGE_KEY]: "gone-theme" },
+      prefersDark: true,
+    });
+    expect(boot.themeId).toBeUndefined();
+    expect(boot.themeSelected).toBeUndefined();
+    expect(boot.isDark).toBe(true);
+  });
+
+  it("follows the OS appearance when storage is unavailable", () => {
+    const light = runBootScript({ storageThrows: true, prefersDark: false });
+    expect(light.isDark).toBe(false);
+    expect(light.themeId).toBeUndefined();
+
+    const dark = runBootScript({ storageThrows: true, prefersDark: true });
+    expect(dark.isDark).toBe(true);
+  });
+});
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
new file mode 100644
index 00000000000..3ecd3001c66
--- /dev/null
+++ b/apps/web/src/themePalette.test.ts
@@ -0,0 +1,322 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  getThemeColorsForMode,
+  getThemeDefinition,
+  getThemeModes,
+  getThemePreferenceMode,
+  isKnownThemePreference,
+  getCustomThemes,
+  invalidateCustomThemes,
+  installCustomTheme,
+  isThemeFollowingSystem,
+  parseThemeFile,
+  resolveDesktopTheme,
+  resolveThemeAppearance,
+  serializeThemeFile,
+  subscribeToCustomThemes,
+  T3_CHAT_THEME,
+  T3_GROVE_THEME,
+  themePreferenceForMode,
+  updateCustomTheme,
+  CUSTOM_THEMES_STORAGE_KEY,
+  createManagedThemeColors,
+  getDefaultThemeColors,
+  THEME_FILE_VERSION,
+} from "./themePalette";
+
+function contrastRatio(first: string, second: string): number {
+  const toRgb = (value: string) => {
+    const hex = value.slice(1);
+    return [0, 1, 2].map(
+      (channel) => Number.parseInt(hex.slice(channel * 2, channel * 2 + 2), 16) / 255,
+    );
+  };
+  const luminance = (value: string) =>
+    toRgb(value)
+      .map((channel) => (channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4))
+      .reduce((sum, channel, index) => sum + channel * [0.2126, 0.7152, 0.0722][index]!, 0);
+  const lighter = Math.max(luminance(first), luminance(second));
+  const darker = Math.min(luminance(first), luminance(second));
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+describe("theme files", () => {
+  it("derives a readable palette from extreme simple-editor colors", () => {
+    const light = createManagedThemeColors("light", "#111827", "#ffff00");
+    const dark = createManagedThemeColors("dark", "#ffffff", "#ffff00");
+    const lightDefaults = getDefaultThemeColors("light");
+    const darkDefaults = getDefaultThemeColors("dark");
+
+    expect(light.canvas).not.toBe("#111827");
+    expect(dark.canvas).not.toBe("#ffffff");
+    expect(contrastRatio(light.accent, light.canvas)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(dark.accent, dark.canvas)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(light.textMuted, light.canvas)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(dark.textMuted, dark.canvas)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(light.accentForeground, light.accent)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(dark.accentForeground, dark.accent)).toBeGreaterThanOrEqual(4.5);
+    expect(light.error).toBe(lightDefaults.error);
+    expect(dark.warning).toBe(darkDefaults.warning);
+  });
+
+  it("merges a small user file onto the matching contrast-safe base palette", () => {
+    const theme = parseThemeFile({
+      version: THEME_FILE_VERSION,
+      name: "Ocean dusk",
+      appearance: "dark",
+      colors: {
+        canvas: "#07152f",
+        accent: "#67c2ff",
+      },
+    });
+
+    expect(theme).toMatchObject({
+      id: "ocean-dusk",
+      label: "Ocean dusk",
+      appearance: "dark",
+      colors: {
+        canvas: "#07152f",
+        accent: "#67c2ff",
+        placeholder: "#b88cb5",
+      },
+    });
+  });
+
+  it("rejects unknown roles and invalid color values", () => {
+    expect(() =>
+      parseThemeFile({
+        version: THEME_FILE_VERSION,
+        name: "Broken",
+        appearance: "light",
+        colors: { background: "#ffffff" },
+      }),
+    ).toThrow('"background" is not a supported theme color role.');
+
+    expect(() =>
+      parseThemeFile({
+        version: THEME_FILE_VERSION,
+        name: "Broken",
+        appearance: "light",
+        colors: { accent: "var(--danger)" },
+      }),
+    ).toThrow('The color for "accent" must be a hex color');
+  });
+
+  it("serializes a theme back into the importable file shape", () => {
+    const serialized = serializeThemeFile(T3_CHAT_THEME);
+    expect(JSON.parse(serialized)).toMatchObject({
+      version: THEME_FILE_VERSION,
+      id: T3_CHAT_THEME.id,
+      name: T3_CHAT_THEME.label,
+      appearance: "light",
+    });
+  });
+
+  it("keeps optional light and dark palettes under one theme id", () => {
+    const theme = parseThemeFile({
+      version: THEME_FILE_VERSION,
+      id: "aurora",
+      name: "Aurora",
+      appearance: "light",
+      colors: { canvas: "#f8fbff", text: "#10243d" },
+      variants: {
+        dark: { canvas: "#101827", text: "#eef5ff" },
+      },
+    });
+
+    expect(getThemeModes(theme)).toEqual(["light", "dark"]);
+    expect(getThemeColorsForMode(theme, "dark")).toMatchObject({
+      canvas: "#101827",
+      text: "#eef5ff",
+    });
+    expect(themePreferenceForMode(theme, "dark")).toBe("aurora:dark");
+    expect(isThemeFollowingSystem("aurora:system")).toBe(true);
+    expect(isThemeFollowingSystem("aurora:dark")).toBe(false);
+    expect(getThemeModes(T3_CHAT_THEME)).toEqual(["light"]);
+    expect(resolveThemeAppearance(T3_CHAT_THEME.id, true, true)).toBe("light");
+    expect(resolveDesktopTheme(T3_CHAT_THEME.id, true)).toBe("light");
+    expect(resolveThemeAppearance("aurora:dark", false, true)).toBe("light");
+    expect(resolveDesktopTheme("aurora:dark", true)).toBe("system");
+    expect(JSON.parse(serializeThemeFile(theme)).variants.dark).toMatchObject({
+      canvas: "#101827",
+      text: "#eef5ff",
+    });
+  });
+
+  it("keeps the T3 Chat palette readable", () => {
+    const colors = T3_CHAT_THEME.colors;
+    expect(contrastRatio(colors.text, colors.canvas)).toBeGreaterThanOrEqual(7);
+    expect(contrastRatio(colors.textMuted, colors.canvas)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(colors.accentForeground, colors.accent)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(colors.messageForeground, colors.messageSurface)).toBeGreaterThanOrEqual(
+      4.5,
+    );
+    expect(contrastRatio(colors.secondaryForeground, colors.secondary)).toBeGreaterThanOrEqual(4.5);
+    expect(contrastRatio(colors.sidebarForeground, colors.sidebar)).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it("includes the T3 Grove maintainer theme with both modes", () => {
+    expect(getThemeDefinition(T3_GROVE_THEME.id)).toBe(T3_GROVE_THEME);
+    expect(getThemeModes(T3_GROVE_THEME)).toEqual(["light", "dark"]);
+    expect(T3_GROVE_THEME.colors.accent).toMatch(/^#[0-9a-f]{6}$/i);
+    expect(T3_GROVE_THEME.variants?.dark?.accent).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  it("rejects a variant that repeats the base appearance", () => {
+    expect(() =>
+      parseThemeFile({
+        version: THEME_FILE_VERSION,
+        name: "Duplicate light",
+        appearance: "light",
+        colors: { canvas: "#f8fbff" },
+        variants: { light: { canvas: "#101827" } },
+      }),
+    ).toThrow('Theme variants must not repeat the base appearance "light".');
+  });
+
+  it("keeps a single-mode theme on its only palette", () => {
+    const theme = parseThemeFile({
+      version: THEME_FILE_VERSION,
+      id: "midnight-slate",
+      name: "Midnight Slate",
+      appearance: "dark",
+      colors: { canvas: "#111827", messageAction: "#2563eb" },
+    });
+
+    expect(getThemeModes(theme)).toEqual(["dark"]);
+    expect(getThemeColorsForMode(theme, "dark")).toMatchObject({ canvas: "#111827" });
+    expect(getThemeColorsForMode(theme, "light")).toBeNull();
+  });
+
+  it("invalidates cached themes when another tab clears localStorage", () => {
+    let storedThemes: string | null = JSON.stringify([
+      {
+        id: "ocean-dusk",
+        label: "Ocean dusk",
+        appearance: "dark",
+        colors: { canvas: "#07152f" },
+      },
+    ]);
+    let storageHandler: ((event: StorageEvent) => void) | undefined;
+    vi.stubGlobal("window", {
+      addEventListener: (type: string, listener: (event: StorageEvent) => void) => {
+        if (type === "storage") storageHandler = listener;
+      },
+      removeEventListener: vi.fn(),
+      localStorage: {
+        getItem: (key: string) => (key === CUSTOM_THEMES_STORAGE_KEY ? storedThemes : null),
+      },
+    });
+
+    invalidateCustomThemes();
+    expect(getCustomThemes()).toHaveLength(1);
+    const listener = vi.fn();
+    const unsubscribe = subscribeToCustomThemes(listener);
+
+    storedThemes = null;
+    storageHandler?.({ key: null } as StorageEvent);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(getCustomThemes()).toEqual([]);
+    unsubscribe();
+    invalidateCustomThemes();
+    vi.unstubAllGlobals();
+  });
+
+  it("updates a personal theme without changing its id", () => {
+    const stored = new Map<string, string>();
+    vi.stubGlobal("window", {
+      localStorage: {
+        getItem: (key: string) => stored.get(key) ?? null,
+        setItem: (key: string, value: string) => stored.set(key, value),
+      },
+    });
+
+    invalidateCustomThemes();
+    const createdTheme = installCustomTheme(
+      parseThemeFile({
+        version: THEME_FILE_VERSION,
+        id: "aurora",
+        name: "Aurora",
+        appearance: "light",
+        colors: { canvas: "#f8fbff", accent: "#5b6cff" },
+      }),
+    );
+    const updatedTheme = updateCustomTheme({
+      ...createdTheme,
+      label: "Aurora Night",
+      colors: { ...createdTheme.colors, accent: "#7c3aed" },
+    });
+
+    expect(updatedTheme).toMatchObject({ id: "aurora", label: "Aurora Night" });
+    expect(getCustomThemes()).toEqual([updatedTheme]);
+    expect(JSON.parse(stored.get(CUSTOM_THEMES_STORAGE_KEY) ?? "[]")[0]).toMatchObject({
+      id: "aurora",
+      label: "Aurora Night",
+    });
+
+    vi.unstubAllGlobals();
+    invalidateCustomThemes();
+  });
+});
+
+describe("stored theme preferences", () => {
+  it("resolves the legacy t3-chat-dark preference to light T3 Chat", () => {
+    expect(getThemeDefinition("t3-chat-dark")).toBe(T3_CHAT_THEME);
+    expect(getThemePreferenceMode("t3-chat-dark")).toBe("light");
+    expect(resolveThemeAppearance("t3-chat-dark", true, false)).toBe("light");
+    expect(resolveDesktopTheme("t3-chat-dark", false)).toBe("light");
+    expect(isKnownThemePreference("t3-chat-dark")).toBe(true);
+  });
+
+  it("recognizes only preferences the runtime can render", () => {
+    for (const preference of [
+      "light",
+      "dark",
+      "system",
+      T3_CHAT_THEME.id,
+      `${T3_GROVE_THEME.id}:dark`,
+    ]) {
+      expect(isKnownThemePreference(preference)).toBe(true);
+    }
+    expect(isKnownThemePreference("aurora:blah")).toBe(false);
+    expect(isKnownThemePreference("missing-theme")).toBe(false);
+    expect(isKnownThemePreference(`${T3_CHAT_THEME.id}:dark`)).toBe(false);
+  });
+
+  it("keeps stored themes with unknown roles and drops invalid entries", () => {
+    vi.stubGlobal("window", {
+      localStorage: {
+        getItem: (key: string) =>
+          key === CUSTOM_THEMES_STORAGE_KEY
+            ? JSON.stringify([
+                {
+                  id: "aurora",
+                  label: "Aurora",
+                  appearance: "light",
+                  colors: { canvas: "#f8fbff", futureRole: "#123456", accent: "not-a-color" },
+                  variants: { light: { canvas: "#101827" } },
+                },
+                { id: "light", label: "Reserved", appearance: "light", colors: {} },
+                { id: "aurora", label: "Duplicate", appearance: "dark", colors: {} },
+              ])
+            : null,
+      },
+    });
+    invalidateCustomThemes();
+
+    const themes = getCustomThemes();
+    expect(themes).toHaveLength(1);
+    expect(themes[0]).toMatchObject({
+      id: "aurora",
+      colors: { canvas: "#f8fbff", accent: getDefaultThemeColors("light").accent },
+    });
+    // The variant shadowing the base appearance is dropped so the theme
+    // round-trips through parseThemeFile on export.
+    expect(getThemeModes(themes[0]!)).toEqual(["light"]);
+
+    vi.unstubAllGlobals();
+    invalidateCustomThemes();
+  });
+});
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
new file mode 100644
index 00000000000..771d14c18a1
--- /dev/null
+++ b/apps/web/src/themePalette.ts
@@ -0,0 +1,1027 @@
+import * as Schema from "effect/Schema";
+
+export const T3_CHAT_THEME_ID = "t3-chat" as const;
+export const T3_CHAT_THEME_LABEL = "T3 Chat";
+export const T3_GROVE_THEME_ID = "t3-grove" as const;
+export const T3_GROVE_THEME_LABEL = "T3 Grove";
+export const THEME_FILE_VERSION = 1 as const;
+export const CUSTOM_THEMES_STORAGE_KEY = "t3code:themes:v1";
+export const THEME_FOLLOW_SYSTEM_STORAGE_KEY = "t3code:theme-follow-system";
+
+const LEGACY_T3_CHAT_DARK_THEME_ID = "t3-chat-dark";
+
+export const ThemePreference = Schema.String;
+export type ThemePreference = typeof ThemePreference.Type;
+
+export const THEME_COLOR_ROLES = [
+  "canvas",
+  "chrome",
+  "surface",
+  "surfaceRaised",
+  "surfaceOverlay",
+  "text",
+  "textMuted",
+  "border",
+  "input",
+  "focus",
+  "accent",
+  "accentForeground",
+  "secondary",
+  "secondaryForeground",
+  "muted",
+  "mutedForeground",
+  "placeholder",
+  "secondaryLabel",
+  "iconMuted",
+  "error",
+  "errorForeground",
+  "errorSurface",
+  "warning",
+  "warningForeground",
+  "warningSurface",
+  "update",
+  "updateForeground",
+  "updateSurface",
+  "accentSurface",
+  "accentSurfaceForeground",
+  "messageSurface",
+  "messageForeground",
+  "messageAction",
+  "messageActionForeground",
+  "messageActionHover",
+  "codeBackground",
+  "codeForeground",
+  "sidebar",
+  "sidebarForeground",
+  "sidebarMutedForeground",
+  "sidebarControlSurface",
+  "sidebarRowHover",
+  "sidebarRowActive",
+  "sidebarRowSelected",
+  "sidebarBorder",
+  "terminalBackground",
+  "terminalForeground",
+  "terminalCursor",
+  "terminalSelection",
+  "terminalScrollbar",
+  "terminalScrollbarHover",
+] as const;
+
+export type ThemeColorRole = (typeof THEME_COLOR_ROLES)[number];
+const THEME_COLOR_ROLE_SET: ReadonlySet<string> = new Set(THEME_COLOR_ROLES);
+export type ThemeAppearance = "light" | "dark";
+
+export type ThemeColors = Readonly<Record<ThemeColorRole, string>>;
+export type ThemeColorOverrides = Readonly<Partial<Record<ThemeColorRole, string>>>;
+export type ThemeVariants = Readonly<Partial<Record<ThemeAppearance, ThemeColors>>>;
+export type ThemeVariantOverrides = Readonly<Partial<Record<ThemeAppearance, ThemeColorOverrides>>>;
+export type ThemePreferenceMode = ThemeAppearance | "system";
+export type ThemeDefinition = Readonly<{
+  id: string;
+  label: string;
+  appearance: ThemeAppearance;
+  colors: ThemeColors;
+  variants?: ThemeVariants;
+}>;
+export type ThemeFile = Readonly<{
+  version: typeof THEME_FILE_VERSION;
+  id: string;
+  name: string;
+  appearance: ThemeAppearance;
+  colors: ThemeColorOverrides;
+  variants?: ThemeVariantOverrides;
+}>;
+
+const RESERVED_THEME_IDS = new Set([
+  "system",
+  "light",
+  "dark",
+  T3_CHAT_THEME_ID,
+  T3_GROVE_THEME_ID,
+  LEGACY_T3_CHAT_DARK_THEME_ID,
+]);
+
+const customThemeListeners = new Set<() => void>();
+let customThemesSnapshot: ReadonlyArray<ThemeDefinition> | null = null;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isThemeAppearance(value: unknown): value is ThemeAppearance {
+  return value === "light" || value === "dark";
+}
+
+export function isThemeColor(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)
+  );
+}
+
+function isThemeId(value: unknown): value is string {
+  return typeof value === "string" && /^[a-z0-9](?:[a-z0-9-]{0,47})$/.test(value);
+}
+
+function isThemeLabel(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.trim().length <= 48;
+}
+
+function parseStoredThemeColors(value: unknown, appearance: ThemeAppearance): ThemeColors | null {
+  if (!isRecord(value)) return null;
+
+  const colors: Partial<Record<ThemeColorRole, string>> = {
+    ...getDefaultThemeColors(appearance),
+  };
+  // Tolerate unknown roles and malformed values so themes saved by other
+  // builds (for example one that adds a new role) keep their remaining colors.
+  for (const [role, color] of Object.entries(value)) {
+    if (THEME_COLOR_ROLE_SET.has(role) && isThemeColor(color)) {
+      colors[role as ThemeColorRole] = color;
+    }
+  }
+  return colors as ThemeColors;
+}
+
+function parseStoredThemeVariants(
+  value: unknown,
+  baseAppearance: ThemeAppearance,
+): ThemeVariants | null | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) return null;
+
+  const variants: Partial<Record<ThemeAppearance, ThemeColors>> = {};
+  for (const [appearance, colors] of Object.entries(value)) {
+    if (!isThemeAppearance(appearance)) return null;
+    // A variant matching the base appearance would be shadowed by the base
+    // colors; drop it so the theme round-trips through parseThemeFile.
+    if (appearance === baseAppearance) continue;
+    const parsedColors = parseStoredThemeColors(colors, appearance);
+    if (!parsedColors) return null;
+    variants[appearance] = parsedColors;
+  }
+  return Object.keys(variants).length > 0 ? variants : undefined;
+}
+
+function parseStoredTheme(value: unknown): ThemeDefinition | null {
+  if (!isRecord(value)) return null;
+  if (!isThemeId(value.id) || RESERVED_THEME_IDS.has(value.id)) return null;
+  if (!isThemeLabel(value.label) || !isThemeAppearance(value.appearance)) return null;
+  const colors = parseStoredThemeColors(value.colors, value.appearance);
+  if (!colors) return null;
+  const variants = parseStoredThemeVariants(value.variants, value.appearance);
+  if (value.variants !== undefined && variants === null) return null;
+
+  return {
+    id: value.id,
+    label: value.label.trim(),
+    appearance: value.appearance,
+    colors,
+    ...(variants ? { variants } : {}),
+  };
+}
+
+function readCustomThemesFromStorage(): ReadonlyArray<ThemeDefinition> {
+  if (typeof window === "undefined") return [];
+
+  try {
+    const raw = window.localStorage.getItem(CUSTOM_THEMES_STORAGE_KEY);
+    if (!raw) return [];
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+
+    const themes: ThemeDefinition[] = [];
+    for (const value of parsed) {
+      const theme = parseStoredTheme(value);
+      if (theme && !themes.some((existing) => existing.id === theme.id)) {
+        themes.push(theme);
+      }
+    }
+    return themes;
+  } catch {
+    return [];
+  }
+}
+
+function notifyCustomThemeListeners() {
+  for (const listener of customThemeListeners) listener();
+}
+
+export function invalidateCustomThemes() {
+  customThemesSnapshot = null;
+  notifyCustomThemeListeners();
+}
+
+export function getCustomThemes(): ReadonlyArray<ThemeDefinition> {
+  if (customThemesSnapshot === null) {
+    customThemesSnapshot = readCustomThemesFromStorage();
+  }
+  return customThemesSnapshot;
+}
+
+export function subscribeToCustomThemes(listener: () => void): () => void {
+  customThemeListeners.add(listener);
+  if (typeof window === "undefined") {
+    return () => customThemeListeners.delete(listener);
+  }
+  const handleStorage = (event: StorageEvent) => {
+    if (event.key === CUSTOM_THEMES_STORAGE_KEY || event.key === null) {
+      invalidateCustomThemes();
+    }
+  };
+  window.addEventListener("storage", handleStorage);
+
+  return () => {
+    customThemeListeners.delete(listener);
+    window.removeEventListener("storage", handleStorage);
+  };
+}
+
+const THEME_PREFERENCE_SEPARATOR = ":";
+
+type ThemePreferenceParts = {
+  id: string;
+  mode: ThemePreferenceMode | null;
+  invalidMode: boolean;
+};
+
+function isThemePreferenceMode(value: unknown): value is ThemePreferenceMode {
+  return value === "light" || value === "dark" || value === "system";
+}
+
+function splitThemePreference(theme: ThemePreference): ThemePreferenceParts {
+  const separatorIndex = theme.lastIndexOf(THEME_PREFERENCE_SEPARATOR);
+  if (separatorIndex <= 0) return { id: theme, mode: null, invalidMode: false };
+
+  const rawMode = theme.slice(separatorIndex + 1);
+  return {
+    id: theme.slice(0, separatorIndex),
+    mode: isThemePreferenceMode(rawMode) ? rawMode : null,
+    invalidMode: !isThemePreferenceMode(rawMode),
+  };
+}
+
+function normalizeThemeId(themeId: string): string {
+  return themeId === LEGACY_T3_CHAT_DARK_THEME_ID ? T3_CHAT_THEME_ID : themeId;
+}
+
+function themeIdFromPreference(theme: ThemePreference): string {
+  return normalizeThemeId(splitThemePreference(theme).id);
+}
+
+function explicitThemeMode(theme: ThemePreference): ThemeAppearance | null {
+  const parts = splitThemePreference(theme);
+  // Older builds stored the dark T3 Chat palette as a separate theme. Keep
+  // those preferences readable, but resolve them to the remaining light-only
+  // T3 Chat theme instead of reviving a removed option.
+  if (parts.id === LEGACY_T3_CHAT_DARK_THEME_ID) return null;
+  return parts.mode === "light" || parts.mode === "dark" ? parts.mode : null;
+}
+
+/**
+ * Maintainer palettes use product color roles rather than Tailwind or component
+ * names so the same definitions can feed other clients and native surfaces.
+ */
+// Anchored to the t3.chat light palette: #a84370 primary, #db2777 ring,
+// #501854 foreground, and its pink-tinted surface family.
+const T3_CHAT_LIGHT_COLORS: ThemeColors = {
+  canvas: "#faf5fa",
+  chrome: "#f3e4f6",
+  surface: "#faf5fa",
+  surfaceRaised: "#fdfafd",
+  surfaceOverlay: "#ffffff",
+  text: "#501854",
+  textMuted: "#834588",
+  border: "#efbdeb",
+  input: "#e7c1dc",
+  focus: "#db2777",
+  accent: "#a84370",
+  accentForeground: "#ffffff",
+  secondary: "#f1c4e6",
+  secondaryForeground: "#77347c",
+  muted: "#f6e5f3",
+  mutedForeground: "#834588",
+  placeholder: "#955a99",
+  secondaryLabel: "#7c4181",
+  iconMuted: "#8d4f92",
+  error: "#ab4347",
+  errorForeground: "#7f2f33",
+  errorSurface: "#f9e2e3",
+  warning: "#a65f19",
+  warningForeground: "#7d4510",
+  warningSurface: "#fff0d7",
+  update: "#a84370",
+  updateForeground: "#7c2f5c",
+  updateSurface: "#f6d9ec",
+  accentSurface: "#f1c4e6",
+  accentSurfaceForeground: "#77347c",
+  messageSurface: "#f1c4e6",
+  messageForeground: "#501854",
+  messageAction: "#a84370",
+  messageActionForeground: "#ffffff",
+  messageActionHover: "#933a63",
+  codeBackground: "#f5ecf5",
+  codeForeground: "#501854",
+  sidebar: "#f3e4f6",
+  sidebarForeground: "#8f2a70",
+  sidebarMutedForeground: "#a5619e",
+  sidebarControlSurface: "#edd7ee",
+  sidebarRowHover: "#f7e8f7",
+  sidebarRowActive: "#eed3ee",
+  sidebarRowSelected: "#f0d7f0",
+  sidebarBorder: "#efbdeb",
+  terminalBackground: "#faf5fa",
+  terminalForeground: "#501854",
+  terminalCursor: "#db2777",
+  terminalSelection: "#f1c4e6",
+  terminalScrollbar: "#ddaed8",
+  terminalScrollbarHover: "#c98cc2",
+};
+
+const DEFAULT_DARK_THEME_COLORS: ThemeColors = {
+  canvas: "#180f1b",
+  chrome: "#241329",
+  surface: "#221323",
+  surfaceRaised: "#2a182b",
+  surfaceOverlay: "#2c192d",
+  text: "#faeaf9",
+  textMuted: "#c99cc4",
+  border: "#5c345b",
+  input: "#6e3a6a",
+  focus: "#f06cab",
+  accent: "#df4c96",
+  accentForeground: "#2a1022",
+  secondary: "#3a2040",
+  secondaryForeground: "#f1c9ed",
+  muted: "#321b35",
+  mutedForeground: "#c99cc4",
+  placeholder: "#b88cb5",
+  secondaryLabel: "#c49bc0",
+  iconMuted: "#c99cc4",
+  error: "#f0719d",
+  errorForeground: "#ffdbe8",
+  errorSurface: "#4a1d31",
+  warning: "#efb56b",
+  warningForeground: "#ffe3b5",
+  warningSurface: "#493018",
+  update: "#f06cab",
+  updateForeground: "#ffd8f4",
+  updateSurface: "#4c2042",
+  accentSurface: "#492244",
+  accentSurfaceForeground: "#ffd8f4",
+  messageSurface: "#522447",
+  messageForeground: "#ffe9fa",
+  messageAction: "#df4c96",
+  messageActionForeground: "#2a1022",
+  messageActionHover: "#f06cab",
+  codeBackground: "#120d14",
+  codeForeground: "#faeaf9",
+  sidebar: "#241329",
+  sidebarForeground: "#f4d8f0",
+  sidebarMutedForeground: "#c49bc0",
+  sidebarControlSurface: "#342039",
+  sidebarRowHover: "#35203a",
+  sidebarRowActive: "#42243f",
+  sidebarRowSelected: "#3e203b",
+  sidebarBorder: "#5c345b",
+  terminalBackground: "#180f1b",
+  terminalForeground: "#faeaf9",
+  terminalCursor: "#f06cab",
+  terminalSelection: "#6b2f5d",
+  terminalScrollbar: "#6b3b6d",
+  terminalScrollbarHover: "#875083",
+};
+
+type ThemeRgbColor = {
+  r: number;
+  g: number;
+  b: number;
+};
+
+type ThemeHslColor = {
+  h: number;
+  s: number;
+  l: number;
+};
+
+const THEME_LIGHT_FOREGROUND: ThemeRgbColor = { r: 255, g: 250, b: 255 };
+const THEME_DARK_FOREGROUND: ThemeRgbColor = { r: 36, g: 21, b: 35 };
+const THEME_WHITE_FOREGROUND: ThemeRgbColor = { r: 255, g: 255, b: 255 };
+const THEME_BLACK_FOREGROUND: ThemeRgbColor = { r: 0, g: 0, b: 0 };
+
+function parseThemeRgbColor(value: string, fallback: ThemeRgbColor): ThemeRgbColor {
+  const match = value.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+  if (!match) return fallback;
+
+  const raw = match[1];
+  if (!raw) return fallback;
+  const hex =
+    raw.length <= 4
+      ? raw
+          .slice(0, 3)
+          .split("")
+          .map((part) => part.repeat(2))
+          .join("")
+      : raw.slice(0, 6);
+  if (hex.length !== 6) return fallback;
+
+  return {
+    r: Number.parseInt(hex.slice(0, 2), 16),
+    g: Number.parseInt(hex.slice(2, 4), 16),
+    b: Number.parseInt(hex.slice(4, 6), 16),
+  };
+}
+
+function themeRgbToHexColor(color: ThemeRgbColor): string {
+  return `#${[color.r, color.g, color.b]
+    .map((channel) =>
+      Math.round(Math.min(255, Math.max(0, channel)))
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+}
+
+function themeRgbToHsl(color: ThemeRgbColor): ThemeHslColor {
+  const red = color.r / 255;
+  const green = color.g / 255;
+  const blue = color.b / 255;
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+  const lightness = (max + min) / 2;
+
+  if (delta === 0) return { h: 0, s: 0, l: lightness };
+
+  const saturation = delta / (1 - Math.abs(2 * lightness - 1));
+  let hue = 0;
+  if (max === red) hue = ((green - blue) / delta) % 6;
+  else if (max === green) hue = (blue - red) / delta + 2;
+  else hue = (red - green) / delta + 4;
+
+  return { h: (hue * 60 + 360) % 360, s: saturation, l: lightness };
+}
+
+function themeHslToRgb(color: ThemeHslColor): ThemeRgbColor {
+  const hue = ((color.h % 360) + 360) % 360;
+  const chroma = (1 - Math.abs(2 * color.l - 1)) * color.s;
+  const hueSector = hue / 60;
+  const secondary = chroma * (1 - Math.abs((hueSector % 2) - 1));
+  const match = color.l - chroma / 2;
+  const [red, green, blue] =
+    hueSector < 1
+      ? [chroma, secondary, 0]
+      : hueSector < 2
+        ? [secondary, chroma, 0]
+        : hueSector < 3
+          ? [0, chroma, secondary]
+          : hueSector < 4
+            ? [0, secondary, chroma]
+            : hueSector < 5
+              ? [secondary, 0, chroma]
+              : [chroma, 0, secondary];
+
+  return { r: (red + match) * 255, g: (green + match) * 255, b: (blue + match) * 255 };
+}
+
+function mixThemeRgbColors(
+  base: ThemeRgbColor,
+  overlay: ThemeRgbColor,
+  amount: number,
+): ThemeRgbColor {
+  return {
+    r: base.r + (overlay.r - base.r) * amount,
+    g: base.g + (overlay.g - base.g) * amount,
+    b: base.b + (overlay.b - base.b) * amount,
+  };
+}
+
+function themeRelativeLuminance(color: ThemeRgbColor): number {
+  const linearize = (channel: number) => {
+    const normalized = channel / 255;
+    return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
+  };
+
+  return 0.2126 * linearize(color.r) + 0.7152 * linearize(color.g) + 0.0722 * linearize(color.b);
+}
+
+function themeContrastRatio(first: ThemeRgbColor, second: ThemeRgbColor): number {
+  const firstLuminance = themeRelativeLuminance(first);
+  const secondLuminance = themeRelativeLuminance(second);
+  const lighter = Math.max(firstLuminance, secondLuminance);
+  const darker = Math.min(firstLuminance, secondLuminance);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function readableThemeForeground(background: ThemeRgbColor): ThemeRgbColor {
+  const lightContrast = themeContrastRatio(background, THEME_LIGHT_FOREGROUND);
+  const darkContrast = themeContrastRatio(background, THEME_DARK_FOREGROUND);
+  if (Math.max(lightContrast, darkContrast) >= 4.5) {
+    return lightContrast >= darkContrast ? THEME_LIGHT_FOREGROUND : THEME_DARK_FOREGROUND;
+  }
+
+  return themeContrastRatio(background, THEME_WHITE_FOREGROUND) >=
+    themeContrastRatio(background, THEME_BLACK_FOREGROUND)
+    ? THEME_WHITE_FOREGROUND
+    : THEME_BLACK_FOREGROUND;
+}
+
+function readableThemeText(
+  background: ThemeRgbColor,
+  foreground: ThemeRgbColor,
+  amount: number,
+  minimumRatio: number,
+): ThemeRgbColor {
+  const softened = mixThemeRgbColors(foreground, background, amount);
+  return themeContrastRatio(softened, background) >= minimumRatio ? softened : foreground;
+}
+
+function managedThemeBackground(value: string, appearance: ThemeAppearance): ThemeRgbColor {
+  const selected = parseThemeRgbColor(
+    value,
+    appearance === "dark" ? { r: 24, g: 15, b: 27 } : { r: 250, g: 245, b: 250 },
+  );
+  const hsl = themeRgbToHsl(selected);
+  return themeHslToRgb({
+    h: hsl.h,
+    // A background tint should support the selected mode, not turn the whole
+    // app into a high-saturation surface.
+    s: Math.min(hsl.s, appearance === "dark" ? 0.3 : 0.2),
+    l:
+      appearance === "dark"
+        ? Math.min(0.18, Math.max(0.07, hsl.l))
+        : Math.min(0.985, Math.max(0.94, hsl.l)),
+  });
+}
+
+function managedThemeAccent(
+  value: string,
+  appearance: ThemeAppearance,
+  background: ThemeRgbColor,
+): ThemeRgbColor {
+  const selected = parseThemeRgbColor(value, { r: 168, g: 67, b: 112 });
+  const hsl = themeRgbToHsl(selected);
+  const preferredLightness =
+    appearance === "dark"
+      ? Math.min(0.72, Math.max(0.42, hsl.l))
+      : Math.min(0.58, Math.max(0.35, hsl.l));
+  const lightnessRange: readonly [number, number] =
+    appearance === "dark" ? [0.42, 0.82] : [0.22, 0.58];
+  const saturation = Math.min(hsl.s, 0.82);
+  const candidates = Array.from({ length: 61 }, (_, index) => {
+    const lightness =
+      lightnessRange[0] + ((lightnessRange[1] - lightnessRange[0]) * index) / (61 - 1);
+    const color = themeHslToRgb({ h: hsl.h, s: saturation, l: lightness });
+    return { color, lightness, contrast: themeContrastRatio(color, background) };
+  });
+  // Leave a little room for rounding when the generated RGB values become a
+  // six-digit hex token.
+  const readableCandidates = candidates.filter((candidate) => candidate.contrast >= 4.7);
+  const pool = readableCandidates.length > 0 ? readableCandidates : candidates;
+
+  return pool.reduce((best, candidate) => {
+    const distance = Math.abs(candidate.lightness - preferredLightness);
+    const bestDistance = Math.abs(best.lightness - preferredLightness);
+    return distance < bestDistance ||
+      (distance === bestDistance && candidate.contrast > best.contrast)
+      ? candidate
+      : best;
+  }).color;
+}
+
+/**
+ * Creates the guided palette used by the basic theme editor. The two user
+ * colors control the mood, while dependent roles are generated together so
+ * text, surfaces, message actions, code, and terminal UI stay coherent.
+ */
+export function createManagedThemeColors(
+  appearance: ThemeAppearance,
+  backgroundValue: string,
+  accentValue: string,
+): ThemeColors {
+  const defaults = getDefaultThemeColors(appearance);
+  const canvas = managedThemeBackground(backgroundValue, appearance);
+  const accent = managedThemeAccent(accentValue, appearance, canvas);
+  const text = readableThemeForeground(canvas);
+  const chrome = mixThemeRgbColors(canvas, accent, 0.04);
+  const sidebar = mixThemeRgbColors(canvas, accent, 0.08);
+  const surfaceRaised = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.12 : 0.035);
+  const surfaceOverlay = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.06);
+  const secondary = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.2 : 0.08);
+  const muted = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.13 : 0.06);
+  const accentSurface = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.3 : 0.14);
+  const messageSurface = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.36 : 0.18);
+  const accentForeground = readableThemeForeground(accent);
+  const codeBackground = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.025);
+  const terminalBackground = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.2 : 0.035);
+  const messageActionHover = mixThemeRgbColors(
+    accent,
+    accentForeground === THEME_LIGHT_FOREGROUND || accentForeground === THEME_WHITE_FOREGROUND
+      ? THEME_BLACK_FOREGROUND
+      : THEME_WHITE_FOREGROUND,
+    0.12,
+  );
+
+  return {
+    ...defaults,
+    canvas: themeRgbToHexColor(canvas),
+    chrome: themeRgbToHexColor(chrome),
+    surface: themeRgbToHexColor(canvas),
+    surfaceRaised: themeRgbToHexColor(surfaceRaised),
+    surfaceOverlay: themeRgbToHexColor(surfaceOverlay),
+    text: themeRgbToHexColor(text),
+    textMuted: themeRgbToHexColor(readableThemeText(canvas, text, 0.25, 4.5)),
+    border: themeRgbToHexColor(
+      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.36 : 0.12),
+    ),
+    input: themeRgbToHexColor(mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.5 : 0.18)),
+    focus: themeRgbToHexColor(accent),
+    accent: themeRgbToHexColor(accent),
+    accentForeground: themeRgbToHexColor(accentForeground),
+    secondary: themeRgbToHexColor(secondary),
+    secondaryForeground: themeRgbToHexColor(readableThemeForeground(secondary)),
+    muted: themeRgbToHexColor(muted),
+    mutedForeground: themeRgbToHexColor(readableThemeText(canvas, text, 0.2, 4.5)),
+    placeholder: themeRgbToHexColor(readableThemeText(canvas, text, 0.12, 4.5)),
+    secondaryLabel: themeRgbToHexColor(readableThemeText(canvas, text, 0.18, 4.5)),
+    iconMuted: themeRgbToHexColor(readableThemeText(canvas, text, 0.18, 3)),
+    accentSurface: themeRgbToHexColor(accentSurface),
+    accentSurfaceForeground: themeRgbToHexColor(readableThemeForeground(accentSurface)),
+    messageSurface: themeRgbToHexColor(messageSurface),
+    messageForeground: themeRgbToHexColor(readableThemeForeground(messageSurface)),
+    messageAction: themeRgbToHexColor(accent),
+    messageActionForeground: themeRgbToHexColor(accentForeground),
+    messageActionHover: themeRgbToHexColor(messageActionHover),
+    codeBackground: themeRgbToHexColor(codeBackground),
+    codeForeground: themeRgbToHexColor(readableThemeForeground(codeBackground)),
+    sidebar: themeRgbToHexColor(sidebar),
+    sidebarForeground: themeRgbToHexColor(readableThemeForeground(sidebar)),
+    sidebarMutedForeground: themeRgbToHexColor(readableThemeText(sidebar, text, 0.2, 4.5)),
+    sidebarControlSurface: themeRgbToHexColor(
+      mixThemeRgbColors(sidebar, text, appearance === "dark" ? 0.16 : 0.08),
+    ),
+    sidebarRowHover: themeRgbToHexColor(mixThemeRgbColors(sidebar, accent, 0.12)),
+    sidebarRowActive: themeRgbToHexColor(mixThemeRgbColors(sidebar, accent, 0.2)),
+    sidebarRowSelected: themeRgbToHexColor(mixThemeRgbColors(sidebar, accent, 0.24)),
+    sidebarBorder: themeRgbToHexColor(
+      mixThemeRgbColors(sidebar, text, appearance === "dark" ? 0.35 : 0.12),
+    ),
+    terminalBackground: themeRgbToHexColor(terminalBackground),
+    terminalForeground: themeRgbToHexColor(readableThemeForeground(terminalBackground)),
+    terminalCursor: themeRgbToHexColor(accent),
+    terminalSelection: themeRgbToHexColor(
+      mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.35 : 0.18),
+    ),
+    terminalScrollbar: themeRgbToHexColor(
+      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.42 : 0.22),
+    ),
+    terminalScrollbarHover: themeRgbToHexColor(
+      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.55 : 0.32),
+    ),
+  };
+}
+
+export const T3_CHAT_THEME: ThemeDefinition = {
+  id: T3_CHAT_THEME_ID,
+  label: T3_CHAT_THEME_LABEL,
+  appearance: "light",
+  colors: T3_CHAT_LIGHT_COLORS,
+};
+
+/** Dark defaults are only used when creating a custom dark theme. */
+export function getDefaultThemeColors(appearance: ThemeAppearance): ThemeColors {
+  return appearance === "dark" ? DEFAULT_DARK_THEME_COLORS : T3_CHAT_THEME.colors;
+}
+
+export const T3_GROVE_THEME: ThemeDefinition = {
+  id: T3_GROVE_THEME_ID,
+  label: T3_GROVE_THEME_LABEL,
+  appearance: "light",
+  colors: createManagedThemeColors("light", "#f4f8f5", "#1e7d52"),
+  variants: {
+    dark: createManagedThemeColors("dark", "#111f19", "#5dd58e"),
+  },
+};
+
+const BUILT_IN_THEME_DEFINITIONS: ReadonlyArray<ThemeDefinition> = [T3_CHAT_THEME, T3_GROVE_THEME];
+
+export function getThemeDefinition(theme: ThemePreference): ThemeDefinition | null {
+  const themeId = themeIdFromPreference(theme);
+  return (
+    BUILT_IN_THEME_DEFINITIONS.find((definition) => definition.id === themeId) ??
+    getCustomThemes().find((definition) => definition.id === themeId) ??
+    null
+  );
+}
+
+export function getThemeColorsForMode(
+  theme: ThemeDefinition,
+  mode: ThemeAppearance,
+): ThemeColors | null {
+  if (mode === theme.appearance) return theme.colors;
+  return theme.variants?.[mode] ?? null;
+}
+
+export function getThemeModes(theme: ThemeDefinition): ReadonlyArray<ThemeAppearance> {
+  return (["light", "dark"] as const).filter((mode) => getThemeColorsForMode(theme, mode) !== null);
+}
+
+export function getThemePreferenceMode(theme: ThemePreference): ThemeAppearance | null {
+  if (theme === "system") return null;
+  if (theme === "light" || theme === "dark") return theme;
+  const explicitMode = explicitThemeMode(theme);
+  if (explicitMode) return explicitMode;
+  return getThemeDefinition(theme)?.appearance ?? null;
+}
+
+export function themePreferenceForMode(
+  theme: ThemePreference | ThemeDefinition,
+  mode: ThemeAppearance,
+): ThemePreference {
+  const definition = typeof theme === "string" ? getThemeDefinition(theme) : theme;
+  const themeId = typeof theme === "string" ? theme : theme.id;
+  if (!definition || getThemeColorsForMode(definition, mode) === null) return themeId;
+  return mode === definition.appearance
+    ? definition.id
+    : `${definition.id}${THEME_PREFERENCE_SEPARATOR}${mode}`;
+}
+
+export function isThemeFollowingSystem(theme: ThemePreference): boolean {
+  if (theme === "system") return true;
+  return splitThemePreference(theme).mode === "system";
+}
+
+export function getThemeDefinitions(): ReadonlyArray<ThemeDefinition> {
+  return [...BUILT_IN_THEME_DEFINITIONS, ...getCustomThemes()];
+}
+
+export function isCustomTheme(theme: ThemePreference): boolean {
+  const themeId = themeIdFromPreference(theme);
+  return getCustomThemes().some((definition) => definition.id === themeId);
+}
+
+export function isT3ChatTheme(theme: ThemePreference): boolean {
+  return themeIdFromPreference(theme) === T3_CHAT_THEME_ID;
+}
+
+function themeIdFromName(name: string): string {
+  const normalized = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return normalized || "custom-theme";
+}
+
+function saveCustomThemes(themes: ReadonlyArray<ThemeDefinition>): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(CUSTOM_THEMES_STORAGE_KEY, JSON.stringify(themes));
+    customThemesSnapshot = themes;
+  } catch (cause) {
+    throw new Error(
+      `Could not save the theme library. ${cause instanceof Error ? cause.message : "Storage is unavailable."}`,
+      { cause },
+    );
+  }
+  notifyCustomThemeListeners();
+}
+
+export function installCustomTheme(theme: ThemeDefinition): ThemeDefinition {
+  if (RESERVED_THEME_IDS.has(theme.id)) {
+    throw new Error(`The theme id "${theme.id}" is reserved.`);
+  }
+  if (getThemeDefinitions().some((existing) => existing.id === theme.id)) {
+    throw new Error(`A theme named "${theme.label}" is already installed.`);
+  }
+  saveCustomThemes([...getCustomThemes(), theme]);
+  return theme;
+}
+
+export function updateCustomTheme(theme: ThemeDefinition): ThemeDefinition {
+  if (RESERVED_THEME_IDS.has(theme.id)) {
+    throw new Error(`The theme id "${theme.id}" is reserved.`);
+  }
+
+  const themes = getCustomThemes();
+  const themeIndex = themes.findIndex((existing) => existing.id === theme.id);
+  if (themeIndex === -1) {
+    throw new Error(`The theme "${theme.label}" is not installed.`);
+  }
+
+  const nextThemes = [...themes];
+  nextThemes[themeIndex] = theme;
+  saveCustomThemes(nextThemes);
+  return theme;
+}
+
+export function removeCustomTheme(themeId: string): void {
+  const nextThemes = getCustomThemes().filter((theme) => theme.id !== themeId);
+  if (nextThemes.length === getCustomThemes().length) return;
+  saveCustomThemes(nextThemes);
+}
+
+function parseThemeColorOverrides(value: unknown): ThemeColorOverrides {
+  if (!isRecord(value)) throw new Error("Theme colors must be objects.");
+
+  const overrides: Partial<Record<ThemeColorRole, string>> = {};
+  for (const [role, color] of Object.entries(value)) {
+    if (!THEME_COLOR_ROLE_SET.has(role)) {
+      throw new Error(`"${role}" is not a supported theme color role.`);
+    }
+    if (!isThemeColor(color)) {
+      throw new Error(`The color for "${role}" must be a hex color such as #8b5cf6.`);
+    }
+    overrides[role as ThemeColorRole] = color;
+  }
+  if (Object.keys(overrides).length === 0) {
+    throw new Error("Add at least one color role to the theme file.");
+  }
+  return overrides;
+}
+
+export function parseThemeFile(value: unknown): ThemeDefinition {
+  if (!isRecord(value)) {
+    throw new Error("Theme files must contain a JSON object.");
+  }
+  if (value.version !== THEME_FILE_VERSION) {
+    throw new Error(`This theme file uses an unsupported version. Expected ${THEME_FILE_VERSION}.`);
+  }
+
+  const name = value.name;
+  const appearance = value.appearance;
+  const rawColors = value.colors;
+  if (!isThemeLabel(name)) throw new Error("Theme files need a name (48 characters or fewer).");
+  if (!isThemeAppearance(appearance)) {
+    throw new Error('Theme files need an appearance of "light" or "dark".');
+  }
+  if (!isRecord(rawColors)) throw new Error("Theme files need a colors object.");
+
+  const id = value.id === undefined ? themeIdFromName(name) : value.id;
+  if (!isThemeId(id)) {
+    throw new Error("Theme ids may only contain lowercase letters, numbers, and hyphens.");
+  }
+  if (RESERVED_THEME_IDS.has(id)) {
+    throw new Error(`The theme id "${id}" is reserved.`);
+  }
+
+  const overrides = parseThemeColorOverrides(rawColors);
+
+  const fallback = getDefaultThemeColors(appearance);
+  const variants: Partial<Record<ThemeAppearance, ThemeColors>> = {};
+  if (value.variants !== undefined) {
+    if (!isRecord(value.variants)) throw new Error("Theme variants must be an object.");
+    for (const [variantAppearance, variantColors] of Object.entries(value.variants)) {
+      if (!isThemeAppearance(variantAppearance)) {
+        throw new Error('Theme variants may only be named "light" or "dark".');
+      }
+      if (variantAppearance === appearance) {
+        throw new Error(`Theme variants must not repeat the base appearance "${appearance}".`);
+      }
+      const variantFallback = getDefaultThemeColors(variantAppearance);
+      variants[variantAppearance] = {
+        ...variantFallback,
+        ...parseThemeColorOverrides(variantColors),
+      };
+    }
+  }
+
+  return {
+    id,
+    label: name.trim(),
+    appearance,
+    colors: { ...fallback, ...overrides },
+    ...(Object.keys(variants).length > 0 ? { variants } : {}),
+  };
+}
+
+export function serializeThemeFile(theme: ThemeDefinition): string {
+  const file: ThemeFile = {
+    version: THEME_FILE_VERSION,
+    id: theme.id,
+    name: theme.label,
+    appearance: theme.appearance,
+    colors: theme.colors,
+    ...(theme.variants ? { variants: theme.variants } : {}),
+  };
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+const APP_THEME_VARIABLES: Readonly<Record<ThemeColorRole, string>> = {
+  canvas: "--app-theme-canvas",
+  chrome: "--app-theme-chrome",
+  surface: "--app-theme-surface",
+  surfaceRaised: "--app-theme-surface-raised",
+  surfaceOverlay: "--app-theme-surface-overlay",
+  text: "--app-theme-text",
+  textMuted: "--app-theme-text-muted",
+  border: "--app-theme-border",
+  input: "--app-theme-input",
+  focus: "--app-theme-focus",
+  accent: "--app-theme-accent",
+  accentForeground: "--app-theme-accent-foreground",
+  secondary: "--app-theme-secondary",
+  secondaryForeground: "--app-theme-secondary-foreground",
+  muted: "--app-theme-muted",
+  mutedForeground: "--app-theme-muted-foreground",
+  placeholder: "--app-theme-placeholder",
+  secondaryLabel: "--app-theme-secondary-label",
+  iconMuted: "--app-theme-icon-muted",
+  error: "--app-theme-error",
+  errorForeground: "--app-theme-error-foreground",
+  errorSurface: "--app-theme-error-surface",
+  warning: "--app-theme-warning",
+  warningForeground: "--app-theme-warning-foreground",
+  warningSurface: "--app-theme-warning-surface",
+  update: "--app-theme-update",
+  updateForeground: "--app-theme-update-foreground",
+  updateSurface: "--app-theme-update-surface",
+  accentSurface: "--app-theme-accent-surface",
+  accentSurfaceForeground: "--app-theme-accent-surface-foreground",
+  messageSurface: "--app-theme-message-surface",
+  messageForeground: "--app-theme-message-foreground",
+  messageAction: "--app-theme-message-action",
+  messageActionForeground: "--app-theme-message-action-foreground",
+  messageActionHover: "--app-theme-message-action-hover",
+  codeBackground: "--app-theme-code-background",
+  codeForeground: "--app-theme-code-foreground",
+  sidebar: "--app-theme-sidebar",
+  sidebarForeground: "--app-theme-sidebar-foreground",
+  sidebarMutedForeground: "--app-theme-sidebar-muted-foreground",
+  sidebarControlSurface: "--app-theme-sidebar-control-surface",
+  sidebarRowHover: "--app-theme-sidebar-row-hover",
+  sidebarRowActive: "--app-theme-sidebar-row-active",
+  sidebarRowSelected: "--app-theme-sidebar-row-selected",
+  sidebarBorder: "--app-theme-sidebar-border",
+  terminalBackground: "--app-theme-terminal-background",
+  terminalForeground: "--app-theme-terminal-foreground",
+  terminalCursor: "--app-theme-terminal-cursor",
+  terminalSelection: "--app-theme-terminal-selection-background",
+  terminalScrollbar: "--app-theme-terminal-scrollbar",
+  terminalScrollbarHover: "--app-theme-terminal-scrollbar-hover",
+};
+
+export function applyThemePalette(theme: ThemePreference, appearance?: ThemeAppearance): void {
+  if (typeof document === "undefined") return;
+
+  const root = document.documentElement;
+  if (!root?.style) return;
+
+  const palette = getThemeDefinition(theme);
+
+  if (palette) {
+    root.dataset.themeId = palette.id;
+    // The resolved appearance is authoritative. This lets a two-mode theme
+    // follow the system even when its stored preference includes a mode suffix.
+    const mode = appearance ?? explicitThemeMode(theme) ?? palette.appearance;
+    const colors = getThemeColorsForMode(palette, mode) ?? palette.colors;
+    for (const [role, value] of Object.entries(colors) as Array<[ThemeColorRole, string]>) {
+      root.style.setProperty(APP_THEME_VARIABLES[role], value);
+    }
+    return;
+  }
+
+  delete root.dataset.themeId;
+  for (const variable of Object.values(APP_THEME_VARIABLES)) {
+    root.style.removeProperty(variable);
+  }
+}
+
+export function resolveThemeAppearance(
+  theme: ThemePreference,
+  systemDark: boolean,
+  followSystem?: boolean,
+): "light" | "dark" {
+  const systemAppearance = systemDark ? "dark" : "light";
+  if (followSystem ?? isThemeFollowingSystem(theme)) {
+    const definition = getThemeDefinition(theme);
+    return definition && getThemeColorsForMode(definition, systemAppearance) === null
+      ? definition.appearance
+      : systemAppearance;
+  }
+  return getThemePreferenceMode(theme) ?? "light";
+}
+
+export function resolveDesktopTheme(
+  theme: ThemePreference,
+  followSystem?: boolean,
+): "light" | "dark" | "system" {
+  if (followSystem ?? isThemeFollowingSystem(theme)) {
+    const definition = getThemeDefinition(theme);
+    const hasLightMode = definition && getThemeColorsForMode(definition, "light") !== null;
+    const hasDarkMode = definition && getThemeColorsForMode(definition, "dark") !== null;
+    return definition && (!hasLightMode || !hasDarkMode) ? definition.appearance : "system";
+  }
+  return getThemePreferenceMode(theme) ?? "system";
+}
+
+export function isKnownThemePreference(theme: string): boolean {
+  if (theme === "light" || theme === "dark" || theme === "system") return true;
+  const parts = splitThemePreference(theme);
+  if (parts.invalidMode) return false;
+  const definition = getThemeDefinition(theme);
+  if (!definition) return false;
+  const mode = getThemePreferenceMode(theme);
+  return mode === null || getThemeColorsForMode(definition, mode) !== null;
+}