From 8014c0ae97490cdb51ad58cb8cde3c273e0d2d9a Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 12:47:59 +0200
Subject: [PATCH 01/25] feat(web): add modular theme library

Adds semantic theme roles, persisted light and dark variants, personal theme import and creation, contrast-safe surfaces, and themed message actions. Includes the T3 Chat palette, follow-system behavior, splash handling, and the theme library UI.
---
 apps/web/index.html                           |  198 +++-
 .../src/components/CommandPalette.logic.ts    |    2 +-
 .../src/components/ComposerPromptEditor.tsx   |    2 +-
 apps/web/src/components/ProjectFavicon.tsx    |    2 +-
 apps/web/src/components/Sidebar.tsx           |   20 +-
 apps/web/src/components/SidebarV2.tsx         |   20 +-
 .../src/components/ThreadTerminalDrawer.tsx   |   92 +-
 apps/web/src/components/chat/ChatComposer.tsx |   22 +-
 apps/web/src/components/chat/ChatHeader.tsx   |    2 +-
 .../components/chat/ComposerCommandMenu.tsx   |   18 +-
 .../src/components/chat/ComposerControl.tsx   |    4 +-
 .../chat/ComposerPendingUserInputPanel.tsx    |   10 +-
 .../chat/ComposerPreviewAnnotationCards.tsx   |   10 +-
 .../chat/ComposerPrimaryActions.tsx           |   31 +-
 .../src/components/chat/ComposerStashMenu.tsx |   10 +-
 .../components/chat/ContextWindowMeter.tsx    |   10 +-
 .../src/components/chat/MessagesTimeline.tsx  |   66 +-
 .../src/components/chat/PierreEntryIcon.tsx   |    4 +-
 .../components/settings/SettingsPanels.tsx    | 1009 ++++++++++++++++-
 apps/web/src/components/ui/command.tsx        |    6 +-
 apps/web/src/components/ui/input.tsx          |    2 +-
 apps/web/src/components/ui/menu.tsx           |    2 +-
 apps/web/src/components/ui/select.tsx         |   10 +-
 apps/web/src/hooks/useCustomThemes.ts         |    9 +
 apps/web/src/hooks/useTheme.test.ts           |   12 +
 apps/web/src/hooks/useTheme.ts                |  154 ++-
 apps/web/src/index.css                        |  140 +++
 apps/web/src/themePalette.test.ts             |  115 ++
 apps/web/src/themePalette.ts                  |  659 +++++++++++
 29 files changed, 2409 insertions(+), 232 deletions(-)
 create mode 100644 apps/web/src/hooks/useCustomThemes.ts
 create mode 100644 apps/web/src/themePalette.test.ts
 create mode 100644 apps/web/src/themePalette.ts

diff --git a/apps/web/index.html b/apps/web/index.html
index dadef17d3bc..cda8e9a64e9 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -15,20 +15,185 @@
       (() => {
         const LIGHT_BACKGROUND = "#ffffff";
         const DARK_BACKGROUND = "#161616";
+        const T3_CHAT_BACKGROUND = "#fffaff";
+        const T3_CHAT_DARK_BACKGROUND = "#180f1b";
+        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: "#fffaff",
+            foreground: "#5c205f",
+            accent: "#c52d7b",
+          },
+          t3ChatDark: {
+            background: "#180f1b",
+            foreground: "#faeaf9",
+            accent: "#f06cab",
+          },
+        };
         const themeColorMeta = document.querySelector('meta[name="theme-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 readCustomTheme = (themePreference, systemDark, followSystem) => {
+          if (!themePreference) return null;
+          const preference = splitThemePreference(themePreference);
+          if (preference.invalidMode) return null;
+          try {
+            const parsed = JSON.parse(
+              window.localStorage.getItem(CUSTOM_THEMES_STORAGE_KEY) ?? "null",
+            );
+            if (!Array.isArray(parsed)) return null;
+            const candidate = parsed.find(
+              (value) =>
+                value &&
+                value.id === preference.id &&
+                isThemeAppearance(value.appearance) &&
+                value.colors,
+            );
+            if (!candidate) return null;
+
+            const preferredMode =
+              followSystem || preference.mode === "system"
+                ? systemDark
+                  ? "dark"
+                  : "light"
+                : (preference.mode ?? candidate.appearance);
+            const mode =
+              preferredMode === candidate.appearance || candidate.variants?.[preferredMode]
+                ? preferredMode
+                : candidate.appearance;
+            const colors =
+              mode === candidate.appearance
+                ? candidate.colors
+                : (candidate.variants?.[mode] ?? candidate.colors);
+            if (
+              !colors ||
+              !isHexColor(colors.canvas) ||
+              !isHexColor(colors.text) ||
+              !isHexColor(colors.accent)
+            ) {
+              return null;
+            }
+            return { theme: candidate, colors, mode };
+          } 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 preference = splitThemePreference(storedTheme ?? "");
+          const storedFollowSystem = window.localStorage.getItem(THEME_FOLLOW_SYSTEM_STORAGE_KEY);
+          const followSystem =
+            storedFollowSystem === "true" ||
+            (storedFollowSystem === null &&
+              (storedTheme === null || storedTheme === "system" || preference.mode === "system"));
+          const customTheme = readCustomTheme(storedTheme, prefersDark, followSystem);
+          const isLegacyT3ChatDark = storedTheme === "t3-chat-dark";
+          const isT3Chat =
+            isLegacyT3ChatDark ||
+            (!preference.invalidMode &&
+              (preference.id === "t3-chat" || preference.id === "t3-chat-dark"));
+          const t3ChatMode = isLegacyT3ChatDark
+            ? followSystem
+              ? prefersDark
+                ? "dark"
+                : "light"
+              : "dark"
+            : followSystem || preference.mode === "system"
+              ? prefersDark
+                ? "dark"
+                : "light"
+              : preference.id === "t3-chat-dark"
+                ? "dark"
+                : (preference.mode ?? "light");
+          const hasStoredTheme =
+            storedTheme === "light" ||
+            storedTheme === "dark" ||
+            storedTheme === "system" ||
+            isT3Chat ||
+            customTheme !== null;
+          const theme = hasStoredTheme && storedTheme ? storedTheme : "system";
+          const isDark = customTheme
+            ? customTheme.mode === "dark"
+            : isT3Chat
+              ? t3ChatMode === "dark"
+              : followSystem
+                ? prefersDark
+                : theme === "dark";
+          if (isT3Chat || customTheme !== null) {
+            document.documentElement.dataset.themeId = isT3Chat ? "t3-chat" : customTheme.theme.id;
+          } else {
+            delete document.documentElement.dataset.themeId;
+          }
+          if (hasStoredTheme) {
+            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 =
+            customTheme !== null
+              ? customTheme.colors.canvas
+              : isT3Chat
+                ? t3ChatMode === "dark"
+                  ? T3_CHAT_DARK_BACKGROUND
+                  : T3_CHAT_BACKGROUND
+                : isDark
+                  ? DARK_BACKGROUND
+                  : LIGHT_BACKGROUND;
           document.documentElement.style.backgroundColor = chromeColor;
+          if (hasStoredTheme) {
+            const splashColors =
+              customTheme !== null
+                ? {
+                    background: customTheme.colors.canvas,
+                    foreground: customTheme.colors.text,
+                    accent: customTheme.colors.accent,
+                  }
+                : isT3Chat
+                  ? t3ChatMode === "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);
+            }
+          }
           themeColorMeta?.setAttribute("content", chromeColor);
         } catch {
+          delete document.documentElement.dataset.themeId;
+          delete document.documentElement.dataset.themeSelected;
           document.documentElement.classList.add("dark");
           document.documentElement.style.backgroundColor = DARK_BACKGROUND;
           themeColorMeta?.setAttribute("content", DARK_BACKGROUND);
@@ -63,14 +228,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/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/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
index 18fcc810f50..0f4652edf11 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -731,10 +731,10 @@ 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",
+                    : "text-foreground",
             )
           : cn(
               "truncate group-hover/v2-row:text-foreground",
@@ -742,7 +742,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                 ? "text-foreground"
                 : isUnread
                   ? "text-muted-foreground"
-                  : "text-muted-foreground/70",
+                  : "text-secondary-label",
             ),
         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..8419cd419c4 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -131,7 +131,11 @@ function normalizeComputedColor(value: string | null | undefined, fallback: stri
   return value ?? fallback;
 }
 
-function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
+function readThemeColor(styles: CSSStyleDeclaration, variable: string, fallback: string): string {
+  return normalizeComputedColor(styles.getPropertyValue(variable), fallback);
+}
+
+function terminalThemeFromApp(mountElement?: HTMLElement | null): ITheme {
   const isDark = document.documentElement.classList.contains("dark");
   const fallbackBackground = isDark ? "rgb(14, 18, 24)" : "rgb(255, 255, 255)";
   const fallbackForeground = isDark ? "rgb(237, 241, 247)" : "rgb(28, 33, 41)";
@@ -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,81 @@ 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)",
+  );
+  const terminalScrollbar = readThemeColor(
+    themeStyles,
+    "--terminal-scrollbar",
+    isDark ? "rgba(255, 255, 255, 0.1)" : "rgba(0, 0, 0, 0.15)",
+  );
+  const terminalScrollbarHover = readThemeColor(
+    themeStyles,
+    "--terminal-scrollbar-hover",
+    isDark ? "rgba(255, 255, 255, 0.18)" : "rgba(0, 0, 0, 0.25)",
+  );
+
+  if (isDark) {
+    return {
+      background: terminalBackground,
+      foreground: terminalForeground,
+      cursor: terminalCursor,
+      selectionBackground: terminalSelection,
+      scrollbarSliderBackground: terminalScrollbar,
+      scrollbarSliderHoverBackground: terminalScrollbarHover,
+      scrollbarSliderActiveBackground: terminalScrollbarHover,
+      black: "rgb(24, 30, 38)",
+      red: "rgb(255, 122, 142)",
+      green: "rgb(134, 231, 149)",
+      yellow: "rgb(244, 205, 114)",
+      blue: "rgb(137, 190, 255)",
+      magenta: "rgb(208, 176, 255)",
+      cyan: "rgb(124, 232, 237)",
+      white: "rgb(210, 218, 230)",
+      brightBlack: "rgb(110, 120, 136)",
+      brightRed: "rgb(255, 168, 180)",
+      brightGreen: "rgb(176, 245, 186)",
+      brightYellow: "rgb(255, 224, 149)",
+      brightBlue: "rgb(174, 210, 255)",
+      brightMagenta: "rgb(229, 203, 255)",
+      brightCyan: "rgb(167, 244, 247)",
+      brightWhite: "rgb(244, 247, 252)",
+    };
+  }
 
   return {
-    background: parseTerminalColor(
-      background,
-      isDark ? { r: 14, g: 18, b: 24 } : { r: 255, g: 255, b: 255 },
-    ),
-    foreground: parseTerminalColor(
-      foreground,
-      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)",
+    background: terminalBackground,
+    foreground: terminalForeground,
+    cursor: terminalCursor,
+    selectionBackground: terminalSelection,
+    scrollbarSliderBackground: terminalScrollbar,
+    scrollbarSliderHoverBackground: terminalScrollbarHover,
+    scrollbarSliderActiveBackground: terminalScrollbarHover,
+    black: "rgb(44, 53, 66)",
+    red: "rgb(191, 70, 87)",
+    green: "rgb(60, 126, 86)",
+    yellow: "rgb(146, 112, 35)",
+    blue: "rgb(72, 102, 163)",
+    magenta: "rgb(132, 86, 149)",
+    cyan: "rgb(53, 127, 141)",
+    white: "rgb(210, 215, 223)",
+    brightBlack: "rgb(112, 123, 140)",
+    brightRed: "rgb(212, 95, 112)",
+    brightGreen: "rgb(85, 148, 111)",
+    brightYellow: "rgb(173, 133, 45)",
+    brightBlue: "rgb(91, 124, 194)",
+    brightMagenta: "rgb(153, 107, 172)",
+    brightCyan: "rgb(70, 149, 164)",
+    brightWhite: "rgb(236, 240, 246)",
   };
 }
 
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index e92ecd497e3..a02033d0993 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-accent text-accent-foreground hover:bg-accent/80"
+                      : "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..f19ab572a84 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-message-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..34a7b84b0a4 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,13 +134,13 @@ 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>
@@ -150,7 +150,7 @@ export const ComposerStashMenu = memo(function ComposerStashMenu(props: {
                       {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 4223ce86259..bba6f6a9ace 100644
--- a/apps/web/src/components/chat/ContextWindowMeter.tsx
+++ b/apps/web/src/components/chat/ContextWindowMeter.tsx
@@ -90,7 +90,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>
@@ -99,7 +99,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>
             )}
@@ -121,14 +121,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.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index a429b54deaf..ddb78e551ec 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-message-foreground 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-message-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/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/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 31ac4bba66e..a780b1effa1 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1,15 +1,20 @@
 import {
   ArchiveIcon,
   ArchiveX,
+  DownloadIcon,
   InfoIcon,
   LoaderIcon,
+  MoonIcon,
   PlusIcon,
   RefreshCwIcon,
   SettingsIcon,
+  SunIcon,
+  Trash2Icon,
+  UploadIcon,
 } from "lucide-react";
 import { Link } from "@tanstack/react-router";
-import type { CSSProperties } from "react";
-import { useCallback, useMemo, useRef, useState } from "react";
+import type { ChangeEvent, CSSProperties, UIEvent } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useAtomValue } from "@effect/atom-react";
 import {
   defaultInstanceIdForDriver,
@@ -63,7 +68,27 @@ import {
 } from "../SidebarStageBackdrop";
 import { isElectron } from "../../env";
 import { buildHostedChannelSelectionUrl, type HostedAppChannel } from "../../hostedPairing";
+import { useCustomThemes } from "../../hooks/useCustomThemes";
 import { useTheme } from "../../hooks/useTheme";
+import { cn } from "../../lib/utils";
+import {
+  THEME_COLOR_ROLES,
+  THEME_FILE_VERSION,
+  getThemeColorsForMode,
+  getThemeDefinition,
+  getThemeModes,
+  getThemePreferenceMode,
+  installCustomTheme,
+  parseThemeFile,
+  removeCustomTheme,
+  serializeThemeFile,
+  themePreferenceForMode,
+  type ThemeAppearance,
+  type ThemeColorRole,
+  type ThemeDefinition,
+  T3_CHAT_DARK_THEME,
+  T3_CHAT_THEME,
+} from "../../themePalette";
 import { usePrimarySettings, useUpdatePrimarySettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import { useDesktopUpdateState } from "../../state/desktopUpdate";
@@ -97,6 +122,7 @@ import {
   DialogTitle,
 } from "../ui/dialog";
 import { DraftInput } from "../ui/draft-input";
+import { Input } from "../ui/input";
 import {
   NumberField,
   NumberFieldDecrement,
@@ -140,21 +166,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",
@@ -948,8 +959,930 @@ function BackgroundActivityAdvancedDialog({
   );
 }
 
+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_ADVANCED_ROLES = THEME_COLOR_ROLES.filter(
+  (role) => !THEME_EDITOR_PRIMARY_ROLES.includes(role),
+);
+
+type ThemeEditorColors = Record<ThemeColorRole, string>;
+type ThemeEditorModeSelection = "single" | "both";
+type ThemeEditorColorsByAppearance = Record<ThemeAppearance, ThemeEditorColors>;
+
+function getThemeEditorDefaults(appearance: ThemeAppearance): ThemeEditorColors {
+  return {
+    ...(appearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors),
+  };
+}
+
+function getThemeEditorColorsByAppearance(): ThemeEditorColorsByAppearance {
+  return {
+    light: getThemeEditorDefaults("light"),
+    dark: getThemeEditorDefaults("dark"),
+  };
+}
+
+function getThemeRoleLabel(role: ThemeColorRole): string {
+  return role.replace(/([A-Z])/g, " $1").replace(/^./, (character) => character.toUpperCase());
+}
+
+function ThemeColorField({
+  role,
+  value,
+  onChange,
+}: {
+  role: ThemeColorRole;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const label = getThemeRoleLabel(role);
+  const pickerValue = /^#[0-9a-f]{6}$/i.test(value) ? value : "#000000";
+
+  return (
+    <div className="flex items-start justify-between gap-3 rounded-lg border border-border/70 bg-background/40 px-3 py-2">
+      <label className="min-w-0 flex-1 text-sm leading-snug" htmlFor={`${role}-hex`}>
+        {label}
+      </label>
+      <div className="flex shrink-0 items-center gap-2">
+        <input
+          aria-label={`Choose ${label} color`}
+          className="size-7 cursor-pointer rounded-md border border-border bg-transparent p-0.5"
+          onChange={(event) => onChange(event.currentTarget.value)}
+          type="color"
+          value={pickerValue}
+        />
+        <Input
+          aria-label={`${label} hex value`}
+          className="w-28"
+          id={`${role}-hex`}
+          onChange={(event) => onChange(event.currentTarget.value)}
+          size="sm"
+          value={value}
+        />
+      </div>
+    </div>
+  );
+}
+
+function CreateThemeDialog({
+  open,
+  onOpenChange,
+  onCreated,
+  initialAppearance,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onCreated: (theme: ThemeDefinition) => void;
+  initialAppearance: ThemeAppearance;
+}) {
+  const [name, setName] = useState("");
+  const [modeSelection, setModeSelection] = useState<ThemeEditorModeSelection>("single");
+  const [activeAppearance, setActiveAppearance] = useState<ThemeAppearance>(initialAppearance);
+  const [colorsByAppearance, setColorsByAppearance] = useState<ThemeEditorColorsByAppearance>(() =>
+    getThemeEditorColorsByAppearance(),
+  );
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    setName("");
+    setModeSelection("single");
+    setActiveAppearance(initialAppearance);
+    setColorsByAppearance(getThemeEditorColorsByAppearance());
+    setError(null);
+  }, [initialAppearance, open]);
+
+  const updateColor = useCallback(
+    (role: ThemeColorRole, value: string) => {
+      setColorsByAppearance((current) => ({
+        ...current,
+        [activeAppearance]: { ...current[activeAppearance], [role]: value },
+      }));
+    },
+    [activeAppearance],
+  );
+
+  const handleSubmit = useCallback(() => {
+    if (!name.trim()) {
+      setError("Give your theme a name before saving it.");
+      return;
+    }
+
+    try {
+      const variantAppearance = activeAppearance === "light" ? "dark" : "light";
+      const variants =
+        modeSelection === "both"
+          ? { [variantAppearance]: colorsByAppearance[variantAppearance] }
+          : undefined;
+      const createdTheme = installCustomTheme(
+        parseThemeFile({
+          version: THEME_FILE_VERSION,
+          name,
+          appearance: activeAppearance,
+          colors: colorsByAppearance[activeAppearance],
+          ...(variants ? { variants } : {}),
+        }),
+      );
+      onCreated(createdTheme);
+      onOpenChange(false);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : "Could not create the theme.");
+    }
+  }, [activeAppearance, colorsByAppearance, modeSelection, name, onCreated, onOpenChange]);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen) setError(null);
+        onOpenChange(nextOpen);
+      }}
+    >
+      <DialogPopup className="max-w-3xl overflow-hidden">
+        <DialogHeader>
+          <DialogTitle>Create theme</DialogTitle>
+          <DialogDescription>
+            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="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-2">
+            <div>
+              <h3 className="text-sm font-medium">Main colors</h3>
+              <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={(value) => updateColor(role, value)}
+                  role={role}
+                  value={colorsByAppearance[activeAppearance][role]}
+                />
+              ))}
+            </div>
+          </div>
+
+          <details className="group rounded-xl border border-border/70 bg-muted/20">
+            <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3 py-3 text-sm font-medium [&::-webkit-details-marker]:hidden">
+              <span>Advanced colors</span>
+              <span className="text-xs font-normal text-muted-foreground">
+                {THEME_EDITOR_ADVANCED_ROLES.length} more roles
+              </span>
+            </summary>
+            <div className="grid gap-2 border-t border-border/70 p-3 sm:grid-cols-2">
+              {THEME_EDITOR_ADVANCED_ROLES.map((role) => (
+                <ThemeColorField
+                  key={role}
+                  onChange={(value) => updateColor(role, value)}
+                  role={role}
+                  value={colorsByAppearance[activeAppearance][role]}
+                />
+              ))}
+            </div>
+          </details>
+
+          {error ? (
+            <div
+              aria-live="polite"
+              className="rounded-lg border border-destructive/30 bg-destructive/8 px-3 py-2 text-sm text-destructive-foreground"
+            >
+              {error}
+            </div>
+          ) : null}
+        </DialogPanel>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button disabled={!name.trim()} onClick={handleSubmit}>
+            <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);
+
+  useEffect(() => {
+    if (!open) return;
+    setJson("");
+    setFileName(null);
+    setError(null);
+  }, [open]);
+
+  const handleFileChange = useCallback(async (event: ChangeEvent<HTMLInputElement>) => {
+    const file = event.currentTarget.files?.[0];
+    event.currentTarget.value = "";
+    if (!file) return;
+
+    setIsReading(true);
+    try {
+      setJson(await file.text());
+      setFileName(file.name);
+      setError(null);
+    } catch {
+      setError("Could not read that file. Paste the JSON below instead.");
+    } finally {
+      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 ? (
+            <div
+              aria-live="polite"
+              className="rounded-lg border border-destructive/30 bg-destructive/8 px-3 py-2 text-sm text-destructive-foreground"
+            >
+              {error}
+            </div>
+          ) : 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 = `linear-gradient(135deg, ${colors.sidebar} 0%, ${colors.canvas} 38%, ${colors.accentSurface} 68%, ${colors.messageAction} 100%)`;
+  return (
+    <span
+      aria-hidden
+      className="block size-14 shrink-0 rounded-full border-2 border-background shadow-sm"
+      style={{ 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,
+  onDownload,
+  onRemove,
+}: {
+  theme: ThemeCardDefinition;
+  isActive: boolean;
+  isPersonal: boolean;
+  onUse: () => void;
+  onUseMode?: ((mode: ThemeAppearance) => void) | undefined;
+  activeMode?: ThemeAppearance | null;
+  onDownload?: () => void;
+  onRemove?: () => void;
+}) {
+  return (
+    <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}
+      onKeyDown={(event) => {
+        if (event.target !== event.currentTarget) return;
+        if (event.key !== "Enter" && event.key !== " ") return;
+        event.preventDefault();
+        onUse();
+      }}
+      role="button"
+      style={isActive ? { boxShadow: "inset 0 0 0 1px var(--ring)" } : undefined}
+      tabIndex={0}
+    >
+      <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">
+        <button
+          aria-label={`${theme.label} theme${isActive ? ", currently active" : ""}`}
+          aria-pressed={isActive}
+          className="min-w-0 flex-1 cursor-pointer rounded-lg px-0.5 py-0.5 text-left outline-none transition-colors hover:bg-accent/20 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+          onClick={(event) => {
+            event.stopPropagation();
+            onUse();
+          }}
+          type="button"
+        >
+          <div className="flex items-center gap-1.5">
+            <p className="truncate text-sm font-medium text-foreground">{theme.label}</p>
+            {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>
+        </button>
+        {onDownload || onRemove ? (
+          <div className="flex shrink-0 items-center gap-1">
+            {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>
+  );
+}
+
+function ThemeLibrary({
+  theme,
+  setTheme,
+  followSystem,
+  setFollowSystem,
+  customThemes,
+  initialAppearance,
+}: {
+  theme: string;
+  setTheme: (theme: string) => void;
+  followSystem: boolean;
+  setFollowSystem: (followSystem: boolean) => void;
+  customThemes: ReadonlyArray<ThemeDefinition>;
+  initialAppearance: ThemeAppearance;
+}) {
+  const [isImportOpen, setIsImportOpen] = useState(false);
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const activeTheme = getThemeDefinition(theme);
+  const standardThemes = getStandardThemeCards();
+  const maintainerThemes = [T3_CHAT_THEME];
+
+  const handleFollowSystemChange = useCallback(
+    (checked: boolean) => {
+      setFollowSystem(checked);
+      setTheme(
+        checked
+          ? (activeTheme?.id ?? "system")
+          : activeTheme
+            ? themePreferenceForMode(activeTheme, initialAppearance)
+            : initialAppearance,
+      );
+    },
+    [activeTheme, initialAppearance, setFollowSystem, setTheme],
+  );
+
+  const handleRemoveTheme = useCallback(
+    (customTheme: ThemeDefinition) => {
+      if (!window.confirm(`Remove the “${customTheme.label}” theme?`)) return;
+      removeCustomTheme(customTheme.id);
+      if (getThemeDefinition(theme)?.id === customTheme.id) setTheme("system");
+    },
+    [setTheme, theme],
+  );
+
+  const handleCreatedTheme = useCallback(
+    (createdTheme: ThemeDefinition) => {
+      setTheme(createdTheme.id);
+      toastManager.add(
+        stackedThreadToast({
+          type: "success",
+          title: `${createdTheme.label} created`,
+          description: "It’s now active.",
+        }),
+      );
+    },
+    [setTheme],
+  );
+
+  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="grid gap-2 px-3 sm:grid-cols-2 sm:px-4">
+        {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}
+              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}
+      <CreateThemeDialog
+        initialAppearance={initialAppearance}
+        onCreated={handleCreatedTheme}
+        onOpenChange={setIsCreateOpen}
+        open={isCreateOpen}
+      />
+      <ThemeImportDialog
+        onImported={(importedTheme) => {
+          setTheme(importedTheme.id);
+          toastManager.add(
+            stackedThreadToast({
+              type: "success",
+              title: `${importedTheme.label} added`,
+              description: "It’s now active.",
+            }),
+          );
+        }}
+        onOpenChange={setIsImportOpen}
+        open={isImportOpen}
+      />
+    </div>
+  );
+}
+
 export function AppearanceSettingsPanel() {
-  const { theme, setTheme } = useTheme();
+  const { theme, setTheme, setFollowSystem, followSystem, resolvedTheme } = useTheme();
+  const customThemes = useCustomThemes();
   const settings = usePrimarySettings();
   const updateSettings = useUpdatePrimarySettings();
   const environmentStageLabel = useEnvironmentStageLabel();
@@ -964,38 +1897,14 @@ 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 title="Appearance">
+        <ThemeLibrary
+          customThemes={customThemes}
+          followSystem={followSystem}
+          initialAppearance={resolvedTheme}
+          setFollowSystem={setFollowSystem}
+          setTheme={setTheme}
+          theme={theme}
         />
 
         <SettingsRow
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..164a2f7d608 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(() => {});
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index bdaf37f099d..c72e0ac88f0 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,7 +65,7 @@ export const isDesktopThemeSyncError = Schema.is(DesktopThemeSyncError);
 
 let listeners: Array<() => void> = [];
 let lastSnapshot: ThemeSnapshot | null = null;
-let lastDesktopTheme: Theme | null = null;
+let lastDesktopTheme: "light" | "dark" | "system" | null = null;
 let lastAppliedTheme: ThemeSnapshot | null = null;
 let themeStorageReadFailure: ThemeStorageError | null = null;
 
@@ -69,6 +81,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 +120,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,11 +202,15 @@ 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;
@@ -175,20 +220,27 @@ export function syncBrowserChromeTheme() {
 
 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 +254,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 +280,7 @@ export function syncDesktopTheme(theme: Theme) {
       theme: error.theme,
       ...safeErrorLogAttributes(error),
     });
-    if (lastDesktopTheme === theme) {
+    if (lastDesktopTheme === desktopTheme) {
       lastDesktopTheme = null;
     }
   });
@@ -240,13 +294,19 @@ if (typeof document !== "undefined" && typeof window !== "undefined") {
 function getSnapshot(): ThemeSnapshot {
   if (typeof window === "undefined") return DEFAULT_THEME_SNAPSHOT;
   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;
 }
 
@@ -261,7 +321,8 @@ function subscribe(listener: () => void): () => void {
   // Listen for system preference changes
   const mq = typeof window.matchMedia === "function" ? window.matchMedia(MEDIA_QUERY) : null;
   const handleChange = () => {
-    if (getStored() === "system") applyTheme("system", true);
+    const storedTheme = getStored();
+    if (readStoredFollowSystem(storedTheme)) applyTheme(storedTheme, true);
     emitChange();
   };
   mq?.addEventListener("change", handleChange);
@@ -272,6 +333,13 @@ function subscribe(listener: () => void): () => void {
       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) {
+      invalidateCustomThemes();
+      applyTheme(getStored(), true);
+      emitChange();
     }
   };
   window.addEventListener("storage", handleStorage);
@@ -287,8 +355,11 @@ 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;
@@ -315,10 +386,39 @@ export function useTheme() {
     emitChange();
   }, []);
 
+  const setFollowSystem = useCallback((nextFollowSystem: boolean) => {
+    if (typeof window === "undefined") return;
+    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;
+    }
+    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,
+    followSystem: snapshot.followSystem,
+    resolvedTheme,
+  } as const;
 }
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index b1ca197149a..80540938cc9 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -158,6 +158,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 +172,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,6 +875,14 @@ 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: var(--primary);
   --accent: var(--color-zinc-100);
   --accent-foreground: var(--color-zinc-900);
   --destructive: var(--color-red-500);
@@ -891,6 +907,12 @@ 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);
+  --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,6 +932,14 @@ 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: var(--primary);
     --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));
@@ -932,6 +962,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 +1025,110 @@ 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. Status, provider, and channel identity colors intentionally
+   remain independent. */
+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-muted-foreground);
+  --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);
+  --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);
+  --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-muted-foreground);
+  --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",
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
new file mode 100644
index 00000000000..1533d655f23
--- /dev/null
+++ b/apps/web/src/themePalette.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  getThemeColorsForMode,
+  getThemeModes,
+  isThemeFollowingSystem,
+  parseThemeFile,
+  resolveDesktopTheme,
+  resolveThemeAppearance,
+  serializeThemeFile,
+  T3_CHAT_THEME,
+  themePreferenceForMode,
+  themePreferenceForSystem,
+  THEME_FILE_VERSION,
+} from "./themePalette";
+
+describe("theme files", () => {
+  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(themePreferenceForSystem(theme)).toBe("aurora:system");
+    expect(isThemeFollowingSystem("aurora:system")).toBe(true);
+    expect(isThemeFollowingSystem("aurora:dark")).toBe(false);
+    expect(resolveThemeAppearance(T3_CHAT_THEME.id, true, true)).toBe("dark");
+    expect(resolveDesktopTheme(T3_CHAT_THEME.id, true)).toBe("system");
+    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 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();
+  });
+});
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
new file mode 100644
index 00000000000..b7237288218
--- /dev/null
+++ b/apps/web/src/themePalette.ts
@@ -0,0 +1,659 @@
+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_CHAT_DARK_THEME_ID = "t3-chat-dark" as const;
+export const T3_CHAT_DARK_THEME_LABEL = "T3 Chat Dark";
+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";
+
+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",
+  "accentSurface",
+  "accentSurfaceForeground",
+  "messageSurface",
+  "messageForeground",
+  "messageAction",
+  "messageActionForeground",
+  "messageActionHover",
+  "sidebar",
+  "sidebarForeground",
+  "sidebarMutedForeground",
+  "sidebarControlSurface",
+  "sidebarRowHover",
+  "sidebarRowActive",
+  "sidebarRowSelected",
+  "sidebarBorder",
+  "terminalBackground",
+  "terminalForeground",
+  "terminalCursor",
+  "terminalSelection",
+  "terminalScrollbar",
+  "terminalScrollbarHover",
+] as const;
+
+export type ThemeColorRole = (typeof THEME_COLOR_ROLES)[number];
+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_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";
+}
+
+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 isThemeColors(value: unknown): value is ThemeColors {
+  if (!isRecord(value)) return false;
+  return THEME_COLOR_ROLES.every((role) => isThemeColor(value[role]));
+}
+
+function parseStoredThemeVariants(value: unknown): 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) || !isThemeColors(colors)) return null;
+    variants[appearance] = colors;
+  }
+  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;
+  if (!isThemeColors(value.colors)) return null;
+  const variants = parseStoredThemeVariants(value.variants);
+  if (value.variants !== undefined && variants === null) return null;
+
+  return {
+    id: value.id,
+    label: value.label.trim(),
+    appearance: value.appearance,
+    colors: value.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) 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 === 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);
+  if (parts.id === T3_CHAT_DARK_THEME_ID) return "dark";
+  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.
+ */
+const T3_CHAT_LIGHT_COLORS: ThemeColors = {
+  canvas: "#fffaff",
+  chrome: "#f6e8f7",
+  surface: "#fffaff",
+  surfaceRaised: "#fff5fd",
+  surfaceOverlay: "#fffaff",
+  text: "#5c205f",
+  textMuted: "#98669a",
+  border: "#efc7eb",
+  input: "#e8b9e3",
+  focus: "#c52d7b",
+  accent: "#c52d7b",
+  accentForeground: "#fff8ff",
+  secondary: "#f9e8f8",
+  secondaryForeground: "#7e3a7f",
+  muted: "#f7eaf7",
+  mutedForeground: "#956a97",
+  placeholder: "#855386",
+  secondaryLabel: "#7e4f80",
+  iconMuted: "#855386",
+  accentSurface: "#f5dff3",
+  accentSurfaceForeground: "#713071",
+  messageSurface: "#f0d1ed",
+  messageForeground: "#5c205f",
+  messageAction: "#b12268",
+  messageActionForeground: "#fff8ff",
+  messageActionHover: "#c52d7b",
+  sidebar: "#f2e2f4",
+  sidebarForeground: "#682a6b",
+  sidebarMutedForeground: "#a36ea1",
+  sidebarControlSurface: "#ebd2eb",
+  sidebarRowHover: "#f8eaf8",
+  sidebarRowActive: "#efd4ed",
+  sidebarRowSelected: "#f1d9ef",
+  sidebarBorder: "#edc0e8",
+  terminalBackground: "#fffaff",
+  terminalForeground: "#5c205f",
+  terminalCursor: "#c52d7b",
+  terminalSelection: "#f0c3eb",
+  terminalScrollbar: "#dfb0da",
+  terminalScrollbarHover: "#cd91c9",
+};
+
+const T3_CHAT_DARK_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",
+  accentSurface: "#492244",
+  accentSurfaceForeground: "#ffd8f4",
+  messageSurface: "#522447",
+  messageForeground: "#ffe9fa",
+  messageAction: "#df4c96",
+  messageActionForeground: "#2a1022",
+  messageActionHover: "#f06cab",
+  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",
+};
+
+export const T3_CHAT_THEME: ThemeDefinition = {
+  id: T3_CHAT_THEME_ID,
+  label: T3_CHAT_THEME_LABEL,
+  appearance: "light",
+  colors: T3_CHAT_LIGHT_COLORS,
+  variants: { dark: T3_CHAT_DARK_COLORS },
+};
+
+/**
+ * Legacy export retained for callers that use the dark palette as an editor
+ * starting point. The selectable theme is now the single T3 Chat definition.
+ */
+export const T3_CHAT_DARK_THEME: ThemeDefinition = {
+  id: T3_CHAT_DARK_THEME_ID,
+  label: T3_CHAT_DARK_THEME_LABEL,
+  appearance: "dark",
+  colors: T3_CHAT_DARK_COLORS,
+};
+
+const BUILT_IN_THEME_DEFINITIONS: ReadonlyArray<ThemeDefinition> = [T3_CHAT_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 themePreferenceForSystem(
+  theme: ThemePreference | ThemeDefinition,
+): ThemePreference {
+  const definition = typeof theme === "string" ? getThemeDefinition(theme) : theme;
+  if (!definition) return "system";
+  return `${definition.id}${THEME_PREFERENCE_SEPARATOR}system`;
+}
+
+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."}`,
+    );
+  }
+  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 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_ROLES as ReadonlyArray<string>).includes(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 = appearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors;
+  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".');
+      }
+      const variantFallback =
+        variantAppearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors;
+      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",
+  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",
+  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;
+    // A bare theme id follows the global appearance preference. Only an
+    // explicit `theme:light`/`theme:dark` preference should override it.
+    const mode = explicitThemeMode(theme) ?? appearance ?? 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;
+  }
+  if (theme === "dark" || theme === "light") return theme;
+  const definition = getThemeDefinition(theme);
+  const mode = getThemePreferenceMode(theme);
+  if (definition && mode) return mode;
+  if (definition) return definition.appearance;
+  return "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";
+  }
+  if (theme === "dark") return "dark";
+  if (theme === "light") return "light";
+  const definition = getThemeDefinition(theme);
+  const mode = getThemePreferenceMode(theme);
+  if (definition && mode) return mode;
+  if (definition) return definition.appearance;
+  return "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;
+}

From 1446d328aaffe9c71cfba58ff15b98f40c6ae91b Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 13:03:23 +0200
Subject: [PATCH 02/25] fix(web): smooth theme preview gradients

---
 apps/web/src/components/settings/SettingsPanels.tsx | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index a780b1effa1..022b4b3c7f8 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1538,12 +1538,18 @@ function downloadThemeFile(filename: string, contents: string): void {
 }
 
 function ThemePreviewCircle({ colors }: { colors: ThemeCardPreview["colors"] }) {
-  const gradient = `linear-gradient(135deg, ${colors.sidebar} 0%, ${colors.canvas} 38%, ${colors.accentSurface} 68%, ${colors.messageAction} 100%)`;
+  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={{ backgroundImage: gradient }}
+      style={{ backgroundColor: colors.canvas, backgroundImage: gradient }}
     />
   );
 }

From 607dd6b28048fbfcbdddb3951bf87a1215b218b5 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 13:52:27 +0200
Subject: [PATCH 03/25] fix(web): finish theme review fixes

---
 apps/web/src/components/DiffPanel.tsx         | 13 ++--
 .../src/components/ThreadTerminalDrawer.tsx   | 75 ++++---------------
 .../src/components/chat/MessagesTimeline.tsx  |  2 +-
 .../src/components/files/FilePreviewPanel.tsx |  8 ++
 .../components/settings/SettingsPanels.tsx    | 66 +++++++++-------
 apps/web/src/index.css                        | 17 ++++-
 apps/web/src/themePalette.ts                  | 45 ++++++++---
 7 files changed, 121 insertions(+), 105 deletions(-)

diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index d10cb39f0e3..dd77be9cc3b 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;
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 8419cd419c4..51fc14cad5a 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -135,7 +135,7 @@ function readThemeColor(styles: CSSStyleDeclaration, variable: string, fallback:
   return normalizeComputedColor(styles.getPropertyValue(variable), fallback);
 }
 
-function terminalThemeFromApp(mountElement?: HTMLElement | null): ITheme {
+function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
   const isDark = document.documentElement.classList.contains("dark");
   const fallbackBackground = isDark ? "rgb(14, 18, 24)" : "rgb(255, 255, 255)";
   const fallbackForeground = isDark ? "rgb(237, 241, 247)" : "rgb(28, 33, 41)";
@@ -166,69 +166,20 @@ function terminalThemeFromApp(mountElement?: HTMLElement | null): ITheme {
     "--terminal-selection-background",
     isDark ? "rgba(180, 203, 255, 0.25)" : "rgba(37, 63, 99, 0.2)",
   );
-  const terminalScrollbar = readThemeColor(
-    themeStyles,
-    "--terminal-scrollbar",
-    isDark ? "rgba(255, 255, 255, 0.1)" : "rgba(0, 0, 0, 0.15)",
-  );
-  const terminalScrollbarHover = readThemeColor(
-    themeStyles,
-    "--terminal-scrollbar-hover",
-    isDark ? "rgba(255, 255, 255, 0.18)" : "rgba(0, 0, 0, 0.25)",
-  );
-
-  if (isDark) {
-    return {
-      background: terminalBackground,
-      foreground: terminalForeground,
-      cursor: terminalCursor,
-      selectionBackground: terminalSelection,
-      scrollbarSliderBackground: terminalScrollbar,
-      scrollbarSliderHoverBackground: terminalScrollbarHover,
-      scrollbarSliderActiveBackground: terminalScrollbarHover,
-      black: "rgb(24, 30, 38)",
-      red: "rgb(255, 122, 142)",
-      green: "rgb(134, 231, 149)",
-      yellow: "rgb(244, 205, 114)",
-      blue: "rgb(137, 190, 255)",
-      magenta: "rgb(208, 176, 255)",
-      cyan: "rgb(124, 232, 237)",
-      white: "rgb(210, 218, 230)",
-      brightBlack: "rgb(110, 120, 136)",
-      brightRed: "rgb(255, 168, 180)",
-      brightGreen: "rgb(176, 245, 186)",
-      brightYellow: "rgb(255, 224, 149)",
-      brightBlue: "rgb(174, 210, 255)",
-      brightMagenta: "rgb(229, 203, 255)",
-      brightCyan: "rgb(167, 244, 247)",
-      brightWhite: "rgb(244, 247, 252)",
-    };
-  }
-
   return {
-    background: terminalBackground,
-    foreground: terminalForeground,
-    cursor: terminalCursor,
+    background: parseTerminalColor(
+      terminalBackground,
+      isDark ? { r: 14, g: 18, b: 24 } : { r: 255, g: 255, b: 255 },
+    ),
+    foreground: parseTerminalColor(
+      terminalForeground,
+      isDark ? { r: 237, g: 241, b: 247 } : { r: 28, g: 33, b: 41 },
+    ),
+    cursor: parseTerminalColor(
+      terminalCursor,
+      isDark ? { r: 180, g: 203, b: 255 } : { r: 38, g: 56, b: 78 },
+    ),
     selectionBackground: terminalSelection,
-    scrollbarSliderBackground: terminalScrollbar,
-    scrollbarSliderHoverBackground: terminalScrollbarHover,
-    scrollbarSliderActiveBackground: terminalScrollbarHover,
-    black: "rgb(44, 53, 66)",
-    red: "rgb(191, 70, 87)",
-    green: "rgb(60, 126, 86)",
-    yellow: "rgb(146, 112, 35)",
-    blue: "rgb(72, 102, 163)",
-    magenta: "rgb(132, 86, 149)",
-    cyan: "rgb(53, 127, 141)",
-    white: "rgb(210, 215, 223)",
-    brightBlack: "rgb(112, 123, 140)",
-    brightRed: "rgb(212, 95, 112)",
-    brightGreen: "rgb(85, 148, 111)",
-    brightYellow: "rgb(173, 133, 45)",
-    brightBlue: "rgb(91, 124, 194)",
-    brightMagenta: "rgb(153, 107, 172)",
-    brightCyan: "rgb(70, 149, 164)",
-    brightWhite: "rgb(236, 240, 246)",
   };
 }
 
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index ddb78e551ec..33fefd84a96 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -1366,7 +1366,7 @@ function UserMessagePreviewAnnotationCard(props: {
       ) : null}
       <div className="min-w-0 px-2.5 py-2">
         {props.annotation.comment ? (
-          <div className="max-w-80 truncate text-message-foreground text-xs font-medium">
+          <div className="max-w-80 truncate text-foreground text-xs font-medium">
             {props.annotation.comment}
           </div>
         ) : null}
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index a736cf96cd3..281f8958f72 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(
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 022b4b3c7f8..310d2ca8244 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -568,7 +568,7 @@ function AboutVersionSection() {
 }
 
 export function useSettingsRestore(onRestored?: () => void) {
-  const { theme, setTheme } = useTheme();
+  const { theme, setTheme, followSystem, setFollowSystem } = useTheme();
   const settings = usePrimarySettings();
   const updateSettings = useUpdatePrimarySettings();
 
@@ -581,6 +581,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
@@ -647,6 +648,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.sidebarThreadPreviewCount,
       settings.timestampFormat,
       settings.wordWrap,
+      followSystem,
       theme,
     ],
   );
@@ -662,6 +664,7 @@ export function useSettingsRestore(onRestored?: () => void) {
     if (!confirmed) return;
 
     setTheme("system");
+    setFollowSystem(true);
     updateSettings({
       timestampFormat: DEFAULT_UNIFIED_SETTINGS.timestampFormat,
       wordWrap: DEFAULT_UNIFIED_SETTINGS.wordWrap,
@@ -685,7 +688,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
     });
     onRestored?.();
-  }, [changedSettingLabels, onRestored, setTheme, updateSettings]);
+  }, [changedSettingLabels, onRestored, setFollowSystem, setTheme, updateSettings]);
 
   return {
     changedSettingLabels,
@@ -1091,27 +1094,30 @@ function ThemeColorField({
   const pickerValue = /^#[0-9a-f]{6}$/i.test(value) ? value : "#000000";
 
   return (
-    <div className="flex items-start justify-between gap-3 rounded-lg border border-border/70 bg-background/40 px-3 py-2">
-      <label className="min-w-0 flex-1 text-sm leading-snug" htmlFor={`${role}-hex`}>
-        {label}
-      </label>
-      <div className="flex shrink-0 items-center gap-2">
+    <div
+      className="flex min-h-11 min-w-0 overflow-hidden rounded-lg border border-border/70"
+      style={{ backgroundColor: pickerValue }}
+    >
+      <label className="relative flex min-w-0 flex-1 cursor-pointer items-center px-3 py-2 text-sm leading-snug text-foreground">
+        <span className="break-words">{label}</span>
         <input
           aria-label={`Choose ${label} color`}
-          className="size-7 cursor-pointer rounded-md border border-border bg-transparent p-0.5"
+          className="absolute inset-0 size-full cursor-pointer opacity-0"
           onChange={(event) => onChange(event.currentTarget.value)}
           type="color"
           value={pickerValue}
         />
-        <Input
-          aria-label={`${label} hex value`}
-          className="w-28"
-          id={`${role}-hex`}
-          onChange={(event) => onChange(event.currentTarget.value)}
-          size="sm"
-          value={value}
-        />
-      </div>
+      </label>
+      <Input
+        aria-label={`${label} hex value`}
+        className="flex w-28 shrink-0 self-stretch items-center rounded-none border-0 border-l border-border/70 bg-background/20 shadow-none"
+        id={`${role}-hex`}
+        nativeInput
+        onChange={(event) => onChange(event.currentTarget.value)}
+        size="sm"
+        unstyled
+        value={value}
+      />
     </div>
   );
 }
@@ -1134,14 +1140,17 @@ function CreateThemeDialog({
     getThemeEditorColorsByAppearance(),
   );
   const [error, setError] = useState<string | null>(null);
+  const previousOpenRef = useRef(false);
 
   useEffect(() => {
-    if (!open) return;
-    setName("");
-    setModeSelection("single");
-    setActiveAppearance(initialAppearance);
-    setColorsByAppearance(getThemeEditorColorsByAppearance());
-    setError(null);
+    if (open && !previousOpenRef.current) {
+      setName("");
+      setModeSelection("single");
+      setActiveAppearance(initialAppearance);
+      setColorsByAppearance(getThemeEditorColorsByAppearance());
+      setError(null);
+    }
+    previousOpenRef.current = open;
   }, [initialAppearance, open]);
 
   const updateColor = useCallback(
@@ -1416,12 +1425,15 @@ function ThemeImportDialog({
   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>) => {
@@ -1429,15 +1441,19 @@ function ThemeImportDialog({
     event.currentTarget.value = "";
     if (!file) return;
 
+    const requestId = ++importRequestRef.current;
     setIsReading(true);
     try {
-      setJson(await file.text());
+      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 {
-      setIsReading(false);
+      if (requestId === importRequestRef.current) setIsReading(false);
     }
   }, []);
 
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 80540938cc9..d9a057a0040 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -907,6 +907,8 @@ 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);
@@ -1068,6 +1070,8 @@ html.dark[data-theme-id] {
   --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);
@@ -1709,7 +1713,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/themePalette.ts b/apps/web/src/themePalette.ts
index b7237288218..0771abfbf41 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -38,6 +38,8 @@ export const THEME_COLOR_ROLES = [
   "messageAction",
   "messageActionForeground",
   "messageActionHover",
+  "codeBackground",
+  "codeForeground",
   "sidebar",
   "sidebarForeground",
   "sidebarMutedForeground",
@@ -112,9 +114,23 @@ function isThemeLabel(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0 && value.trim().length <= 48;
 }
 
-function isThemeColors(value: unknown): value is ThemeColors {
-  if (!isRecord(value)) return false;
-  return THEME_COLOR_ROLES.every((role) => isThemeColor(value[role]));
+function getThemeFallbackColors(appearance: ThemeAppearance): ThemeColors {
+  return appearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors;
+}
+
+function parseStoredThemeColors(value: unknown, appearance: ThemeAppearance): ThemeColors | null {
+  if (!isRecord(value)) return null;
+
+  const colors: Partial<Record<ThemeColorRole, string>> = {
+    ...getThemeFallbackColors(appearance),
+  };
+  for (const [role, color] of Object.entries(value)) {
+    if (!(THEME_COLOR_ROLES as ReadonlyArray<string>).includes(role) || !isThemeColor(color)) {
+      return null;
+    }
+    colors[role as ThemeColorRole] = color;
+  }
+  return colors as ThemeColors;
 }
 
 function parseStoredThemeVariants(value: unknown): ThemeVariants | null | undefined {
@@ -123,8 +139,10 @@ function parseStoredThemeVariants(value: unknown): ThemeVariants | null | undefi
 
   const variants: Partial<Record<ThemeAppearance, ThemeColors>> = {};
   for (const [appearance, colors] of Object.entries(value)) {
-    if (!isThemeAppearance(appearance) || !isThemeColors(colors)) return null;
-    variants[appearance] = colors;
+    if (!isThemeAppearance(appearance)) return null;
+    const parsedColors = parseStoredThemeColors(colors, appearance);
+    if (!parsedColors) return null;
+    variants[appearance] = parsedColors;
   }
   return Object.keys(variants).length > 0 ? variants : undefined;
 }
@@ -133,7 +151,8 @@ 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;
-  if (!isThemeColors(value.colors)) return null;
+  const colors = parseStoredThemeColors(value.colors, value.appearance);
+  if (!colors) return null;
   const variants = parseStoredThemeVariants(value.variants);
   if (value.variants !== undefined && variants === null) return null;
 
@@ -141,7 +160,7 @@ function parseStoredTheme(value: unknown): ThemeDefinition | null {
     id: value.id,
     label: value.label.trim(),
     appearance: value.appearance,
-    colors: value.colors,
+    colors,
     ...(variants ? { variants } : {}),
   };
 }
@@ -269,6 +288,8 @@ const T3_CHAT_LIGHT_COLORS: ThemeColors = {
   messageAction: "#b12268",
   messageActionForeground: "#fff8ff",
   messageActionHover: "#c52d7b",
+  codeBackground: "#fff7fd",
+  codeForeground: "#5c205f",
   sidebar: "#f2e2f4",
   sidebarForeground: "#682a6b",
   sidebarMutedForeground: "#a36ea1",
@@ -312,6 +333,8 @@ const T3_CHAT_DARK_COLORS: ThemeColors = {
   messageAction: "#df4c96",
   messageActionForeground: "#2a1022",
   messageActionHover: "#f06cab",
+  codeBackground: "#120d14",
+  codeForeground: "#faeaf9",
   sidebar: "#241329",
   sidebarForeground: "#f4d8f0",
   sidebarMutedForeground: "#c49bc0",
@@ -567,6 +590,8 @@ const APP_THEME_VARIABLES: Readonly<Record<ThemeColorRole, string>> = {
   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",
@@ -593,9 +618,9 @@ export function applyThemePalette(theme: ThemePreference, appearance?: ThemeAppe
 
   if (palette) {
     root.dataset.themeId = palette.id;
-    // A bare theme id follows the global appearance preference. Only an
-    // explicit `theme:light`/`theme:dark` preference should override it.
-    const mode = explicitThemeMode(theme) ?? appearance ?? palette.appearance;
+    // 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);

From fcd1354d56000b8aacb78f5328d9e7fb8355cc6b Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:07:27 +0200
Subject: [PATCH 04/25] feat(web): theme status and update colors

---
 .../components/chat/MessagesTimeline.test.tsx |  2 +-
 .../settings/ProviderInstanceCard.tsx         |  2 +-
 .../components/settings/SettingsPanels.tsx    | 49 +++++++++++--
 .../sidebar/SidebarProviderUpdatePill.tsx     |  2 +-
 .../components/sidebar/SidebarUpdatePill.tsx  |  6 +-
 apps/web/src/components/ui/alert.tsx          |  5 +-
 apps/web/src/hooks/useTheme.test.ts           |  7 +-
 apps/web/src/index.css                        | 44 +++++++++--
 apps/web/src/themePalette.test.ts             |  5 +-
 apps/web/src/themePalette.ts                  | 73 +++++++++++++------
 10 files changed, 150 insertions(+), 45 deletions(-)

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/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 310d2ca8244..198569fb99c 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -74,6 +74,7 @@ import { cn } from "../../lib/utils";
 import {
   THEME_COLOR_ROLES,
   THEME_FILE_VERSION,
+  getDefaultThemeColors,
   getThemeColorsForMode,
   getThemeDefinition,
   getThemeModes,
@@ -86,7 +87,6 @@ import {
   type ThemeAppearance,
   type ThemeColorRole,
   type ThemeDefinition,
-  T3_CHAT_DARK_THEME,
   T3_CHAT_THEME,
 } from "../../themePalette";
 import { usePrimarySettings, useUpdatePrimarySettings } from "../../hooks/useSettings";
@@ -1056,8 +1056,20 @@ const THEME_EDITOR_PRIMARY_ROLES: ReadonlyArray<ThemeColorRole> = [
   "messageAction",
 ];
 
+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),
+  (role) => !THEME_EDITOR_PRIMARY_ROLES.includes(role) && !THEME_EDITOR_STATUS_ROLES.includes(role),
 );
 
 type ThemeEditorColors = Record<ThemeColorRole, string>;
@@ -1065,9 +1077,7 @@ type ThemeEditorModeSelection = "single" | "both";
 type ThemeEditorColorsByAppearance = Record<ThemeAppearance, ThemeEditorColors>;
 
 function getThemeEditorDefaults(appearance: ThemeAppearance): ThemeEditorColors {
-  return {
-    ...(appearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors),
-  };
+  return { ...getDefaultThemeColors(appearance) };
 }
 
 function getThemeEditorColorsByAppearance(): ThemeEditorColorsByAppearance {
@@ -1078,6 +1088,16 @@ function getThemeEditorColorsByAppearance(): ThemeEditorColorsByAppearance {
 }
 
 function getThemeRoleLabel(role: ThemeColorRole): string {
+  const labels: Partial<Record<ThemeColorRole, string>> = {
+    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());
 }
 
@@ -1285,6 +1305,25 @@ function CreateThemeDialog({
             </div>
           </div>
 
+          <div className="space-y-2">
+            <div>
+              <h3 className="text-sm font-medium">Status colors</h3>
+              <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={(value) => updateColor(role, value)}
+                  role={role}
+                  value={colorsByAppearance[activeAppearance][role]}
+                />
+              ))}
+            </div>
+          </div>
+
           <details className="group rounded-xl border border-border/70 bg-muted/20">
             <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3 py-3 text-sm font-medium [&::-webkit-details-marker]:hidden">
               <span>Advanced colors</span>
diff --git a/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarProviderUpdatePill.tsx
index b28b967eefa..b6606fe047c 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/12",
   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/hooks/useTheme.test.ts b/apps/web/src/hooks/useTheme.test.ts
index 164a2f7d608..ab87388ff29 100644
--- a/apps/web/src/hooks/useTheme.test.ts
+++ b/apps/web/src/hooks/useTheme.test.ts
@@ -116,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;
@@ -153,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/index.css b/apps/web/src/index.css
index d9a057a0040..1264d2ab37f 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);
@@ -885,17 +892,24 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --message-action-hover: var(--primary);
   --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);
@@ -944,17 +958,24 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
     --message-action-hover: var(--primary);
     --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);
@@ -1030,8 +1051,8 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
 /* 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. Status, provider, and channel identity colors intentionally
-   remain independent. */
+   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);
@@ -1058,6 +1079,17 @@ html.dark[data-theme-id] {
   --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);
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index 1533d655f23..97fb4e2065c 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -89,8 +89,9 @@ describe("theme files", () => {
     expect(themePreferenceForSystem(theme)).toBe("aurora:system");
     expect(isThemeFollowingSystem("aurora:system")).toBe(true);
     expect(isThemeFollowingSystem("aurora:dark")).toBe(false);
-    expect(resolveThemeAppearance(T3_CHAT_THEME.id, true, true)).toBe("dark");
-    expect(resolveDesktopTheme(T3_CHAT_THEME.id, true)).toBe("system");
+    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({
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index 0771abfbf41..52e50eb5b44 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -2,12 +2,12 @@ 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_CHAT_DARK_THEME_ID = "t3-chat-dark" as const;
-export const T3_CHAT_DARK_THEME_LABEL = "T3 Chat Dark";
 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;
 
@@ -31,6 +31,15 @@ export const THEME_COLOR_ROLES = [
   "placeholder",
   "secondaryLabel",
   "iconMuted",
+  "error",
+  "errorForeground",
+  "errorSurface",
+  "warning",
+  "warningForeground",
+  "warningSurface",
+  "update",
+  "updateForeground",
+  "updateSurface",
   "accentSurface",
   "accentSurfaceForeground",
   "messageSurface",
@@ -85,7 +94,7 @@ const RESERVED_THEME_IDS = new Set([
   "light",
   "dark",
   T3_CHAT_THEME_ID,
-  T3_CHAT_DARK_THEME_ID,
+  LEGACY_T3_CHAT_DARK_THEME_ID,
 ]);
 
 const customThemeListeners = new Set<() => void>();
@@ -115,7 +124,7 @@ function isThemeLabel(value: unknown): value is string {
 }
 
 function getThemeFallbackColors(appearance: ThemeAppearance): ThemeColors {
-  return appearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors;
+  return appearance === "dark" ? DEFAULT_DARK_THEME_COLORS : T3_CHAT_THEME.colors;
 }
 
 function parseStoredThemeColors(value: unknown, appearance: ThemeAppearance): ThemeColors | null {
@@ -244,7 +253,7 @@ function splitThemePreference(theme: ThemePreference): ThemePreferenceParts {
 }
 
 function normalizeThemeId(themeId: string): string {
-  return themeId === T3_CHAT_DARK_THEME_ID ? T3_CHAT_THEME_ID : themeId;
+  return themeId === LEGACY_T3_CHAT_DARK_THEME_ID ? T3_CHAT_THEME_ID : themeId;
 }
 
 function themeIdFromPreference(theme: ThemePreference): string {
@@ -253,7 +262,10 @@ function themeIdFromPreference(theme: ThemePreference): string {
 
 function explicitThemeMode(theme: ThemePreference): ThemeAppearance | null {
   const parts = splitThemePreference(theme);
-  if (parts.id === T3_CHAT_DARK_THEME_ID) return "dark";
+  // 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;
 }
 
@@ -281,6 +293,15 @@ const T3_CHAT_LIGHT_COLORS: ThemeColors = {
   placeholder: "#855386",
   secondaryLabel: "#7e4f80",
   iconMuted: "#855386",
+  error: "#b4235f",
+  errorForeground: "#8f1748",
+  errorSurface: "#fce3ec",
+  warning: "#a65f19",
+  warningForeground: "#7d4510",
+  warningSurface: "#fff0d7",
+  update: "#b12268",
+  updateForeground: "#7e245e",
+  updateSurface: "#f8e2f4",
   accentSurface: "#f5dff3",
   accentSurfaceForeground: "#713071",
   messageSurface: "#f0d1ed",
@@ -306,7 +327,7 @@ const T3_CHAT_LIGHT_COLORS: ThemeColors = {
   terminalScrollbarHover: "#cd91c9",
 };
 
-const T3_CHAT_DARK_COLORS: ThemeColors = {
+const DEFAULT_DARK_THEME_COLORS: ThemeColors = {
   canvas: "#180f1b",
   chrome: "#241329",
   surface: "#221323",
@@ -326,6 +347,15 @@ const T3_CHAT_DARK_COLORS: ThemeColors = {
   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",
@@ -356,19 +386,12 @@ export const T3_CHAT_THEME: ThemeDefinition = {
   label: T3_CHAT_THEME_LABEL,
   appearance: "light",
   colors: T3_CHAT_LIGHT_COLORS,
-  variants: { dark: T3_CHAT_DARK_COLORS },
 };
 
-/**
- * Legacy export retained for callers that use the dark palette as an editor
- * starting point. The selectable theme is now the single T3 Chat definition.
- */
-export const T3_CHAT_DARK_THEME: ThemeDefinition = {
-  id: T3_CHAT_DARK_THEME_ID,
-  label: T3_CHAT_DARK_THEME_LABEL,
-  appearance: "dark",
-  colors: T3_CHAT_DARK_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;
+}
 
 const BUILT_IN_THEME_DEFINITIONS: ReadonlyArray<ThemeDefinition> = [T3_CHAT_THEME];
 
@@ -525,7 +548,7 @@ export function parseThemeFile(value: unknown): ThemeDefinition {
 
   const overrides = parseThemeColorOverrides(rawColors);
 
-  const fallback = appearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors;
+  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.");
@@ -533,8 +556,7 @@ export function parseThemeFile(value: unknown): ThemeDefinition {
       if (!isThemeAppearance(variantAppearance)) {
         throw new Error('Theme variants may only be named "light" or "dark".');
       }
-      const variantFallback =
-        variantAppearance === "dark" ? T3_CHAT_DARK_THEME.colors : T3_CHAT_THEME.colors;
+      const variantFallback = getDefaultThemeColors(variantAppearance);
       variants[variantAppearance] = {
         ...variantFallback,
         ...parseThemeColorOverrides(variantColors),
@@ -583,6 +605,15 @@ const APP_THEME_VARIABLES: Readonly<Record<ThemeColorRole, string>> = {
   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",

From ebcf87491ef964d0be25120cfdd62e94c3aaf26b Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:26:59 +0200
Subject: [PATCH 05/25] fix(web): address theme review feedback

---
 .../components/settings/SettingsPanels.tsx    |  4 +-
 apps/web/src/hooks/useTheme.ts                |  5 +-
 apps/web/src/index.css                        |  4 +-
 apps/web/src/themePalette.test.ts             | 52 ++++++++++++++++++-
 apps/web/src/themePalette.ts                  |  7 ++-
 5 files changed, 65 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 198569fb99c..252416de20b 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1797,8 +1797,8 @@ function ThemeLibrary({
   const handleRemoveTheme = useCallback(
     (customTheme: ThemeDefinition) => {
       if (!window.confirm(`Remove the “${customTheme.label}” theme?`)) return;
-      removeCustomTheme(customTheme.id);
       if (getThemeDefinition(theme)?.id === customTheme.id) setTheme("system");
+      removeCustomTheme(customTheme.id);
     },
     [setTheme, theme],
   );
@@ -1958,7 +1958,7 @@ export function AppearanceSettingsPanel() {
 
   return (
     <SettingsPageContainer>
-      <SettingsSection title="Appearance">
+      <SettingsSection {...searchableSetting("theme")} title="Appearance">
         <ThemeLibrary
           customThemes={customThemes}
           followSystem={followSystem}
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index c72e0ac88f0..afd7dec2ea0 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -336,8 +336,10 @@ function subscribe(listener: () => void): () => void {
     } else if (e.key === THEME_FOLLOW_SYSTEM_STORAGE_KEY) {
       applyTheme(getStored(), true);
       emitChange();
-    } else if (e.key === CUSTOM_THEMES_STORAGE_KEY) {
+    } else if (e.key === CUSTOM_THEMES_STORAGE_KEY || e.key === null) {
+      if (e.key === null) themeStorageReadFailure = null;
       invalidateCustomThemes();
+      lastAppliedTheme = null;
       applyTheme(getStored(), true);
       emitChange();
     }
@@ -405,6 +407,7 @@ export function useTheme() {
       });
       return;
     }
+    themeStorageReadFailure = null;
     applyTheme(getStored(), true);
     emitChange();
   }, []);
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 1264d2ab37f..7cac00aaed0 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -1068,7 +1068,7 @@ html.dark[data-theme-id] {
   --secondary: var(--app-theme-secondary);
   --secondary-foreground: var(--app-theme-secondary-foreground);
   --muted: var(--app-theme-muted);
-  --muted-foreground: var(--app-theme-muted-foreground);
+  --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);
@@ -1134,7 +1134,7 @@ html[data-theme-id] [data-sidebar-version="v2"] {
   --accent: var(--app-theme-accent-surface);
   --accent-foreground: var(--app-theme-accent-surface-foreground);
   --muted: var(--app-theme-muted);
-  --muted-foreground: var(--app-theme-muted-foreground);
+  --muted-foreground: var(--app-theme-text-muted);
   --border: var(--app-theme-border);
   --input: var(--app-theme-input);
   --sidebar: var(--app-theme-sidebar);
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index 97fb4e2065c..158d9b01a65 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -1,16 +1,20 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, it, vi } from "vite-plus/test";
 
 import {
   getThemeColorsForMode,
   getThemeModes,
+  getCustomThemes,
+  invalidateCustomThemes,
   isThemeFollowingSystem,
   parseThemeFile,
   resolveDesktopTheme,
   resolveThemeAppearance,
   serializeThemeFile,
+  subscribeToCustomThemes,
   T3_CHAT_THEME,
   themePreferenceForMode,
   themePreferenceForSystem,
+  CUSTOM_THEMES_STORAGE_KEY,
   THEME_FILE_VERSION,
 } from "./themePalette";
 
@@ -100,6 +104,18 @@ describe("theme files", () => {
     });
   });
 
+  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,
@@ -113,4 +129,38 @@ describe("theme files", () => {
     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),
+      },
+    });
+
+    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();
+  });
 });
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index 52e50eb5b44..0514fa05a32 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -218,7 +218,9 @@ export function subscribeToCustomThemes(listener: () => void): () => void {
     return () => customThemeListeners.delete(listener);
   }
   const handleStorage = (event: StorageEvent) => {
-    if (event.key === CUSTOM_THEMES_STORAGE_KEY) invalidateCustomThemes();
+    if (event.key === CUSTOM_THEMES_STORAGE_KEY || event.key === null) {
+      invalidateCustomThemes();
+    }
   };
   window.addEventListener("storage", handleStorage);
 
@@ -556,6 +558,9 @@ export function parseThemeFile(value: unknown): ThemeDefinition {
       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,

From 23d92c4ff542df5ecd10632e4110e74b1375a180 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:32:20 +0200
Subject: [PATCH 06/25] test(web): reset theme cache before storage test

---
 apps/web/src/themePalette.test.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index 158d9b01a65..cd7cc199b62 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -150,6 +150,7 @@ describe("theme files", () => {
       },
     });
 
+    invalidateCustomThemes();
     expect(getCustomThemes()).toHaveLength(1);
     const listener = vi.fn();
     const unsubscribe = subscribeToCustomThemes(listener);

From f8ef5fa04258390ee192e2f23af6ae444e1dcc86 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:37:31 +0200
Subject: [PATCH 07/25] feat(web): simplify theme editor defaults

---
 .../components/settings/SettingsPanels.tsx    | 148 ++++++++++++------
 1 file changed, 96 insertions(+), 52 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 252416de20b..6e23efadd45 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1056,6 +1056,8 @@ const THEME_EDITOR_PRIMARY_ROLES: ReadonlyArray<ThemeColorRole> = [
   "messageAction",
 ];
 
+const THEME_EDITOR_SIMPLE_ROLES: ReadonlyArray<ThemeColorRole> = ["canvas", "accent"];
+
 const THEME_EDITOR_STATUS_ROLES: ReadonlyArray<ThemeColorRole> = [
   "error",
   "errorForeground",
@@ -1089,6 +1091,8 @@ function getThemeEditorColorsByAppearance(): ThemeEditorColorsByAppearance {
 
 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",
@@ -1156,6 +1160,7 @@ function CreateThemeDialog({
   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(),
   );
@@ -1167,6 +1172,7 @@ function CreateThemeDialog({
       setName("");
       setModeSelection("single");
       setActiveAppearance(initialAppearance);
+      setIsAdvanced(false);
       setColorsByAppearance(getThemeEditorColorsByAppearance());
       setError(null);
     }
@@ -1286,63 +1292,101 @@ function CreateThemeDialog({
             </div>
           </div>
 
-          <div className="space-y-2">
-            <div>
-              <h3 className="text-sm font-medium">Main colors</h3>
-              <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={(value) => updateColor(role, value)}
-                  role={role}
-                  value={colorsByAppearance[activeAppearance][role]}
+          <div className="space-y-3">
+            <div className="flex items-start justify-between gap-3">
+              <div>
+                <h3 className="text-sm font-medium">
+                  {isAdvanced ? "Theme colors" : "Basic colors"}
+                </h3>
+                <p className="text-xs leading-relaxed text-muted-foreground">
+                  {isAdvanced
+                    ? "Customize every color role used by T3 Code."
+                    : "Choose a background and accent. T3 Code fills in the rest."}
+                </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) => setIsAdvanced(Boolean(checked))}
                 />
-              ))}
+              </label>
             </div>
-          </div>
 
-          <div className="space-y-2">
-            <div>
-              <h3 className="text-sm font-medium">Status colors</h3>
-              <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={(value) => updateColor(role, value)}
-                  role={role}
-                  value={colorsByAppearance[activeAppearance][role]}
-                />
-              ))}
-            </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={(value) => updateColor(role, value)}
+                        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={(value) => updateColor(role, value)}
+                        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={(value) => updateColor(role, value)}
+                        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={(value) => updateColor(role, value)}
+                    role={role}
+                    value={colorsByAppearance[activeAppearance][role]}
+                  />
+                ))}
+              </div>
+            )}
           </div>
 
-          <details className="group rounded-xl border border-border/70 bg-muted/20">
-            <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3 py-3 text-sm font-medium [&::-webkit-details-marker]:hidden">
-              <span>Advanced colors</span>
-              <span className="text-xs font-normal text-muted-foreground">
-                {THEME_EDITOR_ADVANCED_ROLES.length} more roles
-              </span>
-            </summary>
-            <div className="grid gap-2 border-t border-border/70 p-3 sm:grid-cols-2">
-              {THEME_EDITOR_ADVANCED_ROLES.map((role) => (
-                <ThemeColorField
-                  key={role}
-                  onChange={(value) => updateColor(role, value)}
-                  role={role}
-                  value={colorsByAppearance[activeAppearance][role]}
-                />
-              ))}
-            </div>
-          </details>
-
           {error ? (
             <div
               aria-live="polite"

From e09a4cfc796c23918ecdd0ade19e87b9ce41b86b Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:49:35 +0200
Subject: [PATCH 08/25] fix(web): unify theme card selection

---
 .../src/components/settings/SettingsPanels.tsx  | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 6e23efadd45..baf7ca45c61 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1726,9 +1726,11 @@ function ThemeLibraryCard({
   return (
     <div
       className={cn(
-        "cursor-pointer overflow-hidden rounded-xl border border-border/70 bg-card/60 transition-colors hover:bg-accent/10",
+        "cursor-pointer overflow-hidden rounded-xl border border-border/70 bg-card/60 outline-none transition-colors hover:bg-accent/10 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
         isActive && "bg-accent/30",
       )}
+      aria-label={`${theme.label} theme${isActive ? ", currently active" : ""}`}
+      aria-pressed={isActive}
       data-theme-library-card={theme.id}
       onClick={onUse}
       onKeyDown={(event) => {
@@ -1748,16 +1750,7 @@ function ThemeLibraryCard({
         previews={theme.previews}
       />
       <div className="flex items-center gap-2 px-3 pb-3 pt-2">
-        <button
-          aria-label={`${theme.label} theme${isActive ? ", currently active" : ""}`}
-          aria-pressed={isActive}
-          className="min-w-0 flex-1 cursor-pointer rounded-lg px-0.5 py-0.5 text-left outline-none transition-colors hover:bg-accent/20 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
-          onClick={(event) => {
-            event.stopPropagation();
-            onUse();
-          }}
-          type="button"
-        >
+        <div className="min-w-0 flex-1">
           <div className="flex items-center gap-1.5">
             <p className="truncate text-sm font-medium text-foreground">{theme.label}</p>
             {isPersonal ? (
@@ -1766,7 +1759,7 @@ function ThemeLibraryCard({
               </span>
             ) : null}
           </div>
-        </button>
+        </div>
         {onDownload || onRemove ? (
           <div className="flex shrink-0 items-center gap-1">
             {onDownload ? (

From ef6220217fb2f26ab1d4fed52085181dedc00e48 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 14:53:34 +0200
Subject: [PATCH 09/25] fix(web): refine theme color editor

---
 .../components/settings/SettingsPanels.tsx    | 23 +++++++++++++------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index baf7ca45c61..1ff09ad9c16 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1115,15 +1115,20 @@ function ThemeColorField({
   onChange: (value: string) => void;
 }) {
   const label = getThemeRoleLabel(role);
+  const isColorValue = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value);
   const pickerValue = /^#[0-9a-f]{6}$/i.test(value) ? value : "#000000";
+  const swatchValue = isColorValue ? value : "#000000";
 
   return (
-    <div
-      className="flex min-h-11 min-w-0 overflow-hidden rounded-lg border border-border/70"
-      style={{ backgroundColor: pickerValue }}
-    >
-      <label className="relative flex min-w-0 flex-1 cursor-pointer items-center px-3 py-2 text-sm leading-snug text-foreground">
-        <span className="break-words">{label}</span>
+    <div className="group flex min-h-11 min-w-0 items-center gap-2 border-b border-zinc-200/70 px-1.5 py-1.5 transition-colors hover:bg-zinc-100/60 dark:border-zinc-800/70 dark:hover:bg-zinc-900/60">
+      <label
+        className="relative flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-full transition-transform hover:scale-105 focus-within:ring-2 focus-within:ring-blue-500/70 focus-within:ring-offset-2 focus-within:ring-offset-background dark:focus-within:ring-blue-400/70"
+        title={`Choose ${label} color`}
+      >
+        <span
+          className="absolute inset-0.5 rounded-full shadow-[inset_0_0_0_1px_rgb(0_0_0_/_14%),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: swatchValue }}
+        />
         <input
           aria-label={`Choose ${label} color`}
           className="absolute inset-0 size-full cursor-pointer opacity-0"
@@ -1132,9 +1137,13 @@ function ThemeColorField({
           value={pickerValue}
         />
       </label>
+      <span className="min-w-0 flex-1 truncate text-sm font-medium text-zinc-900 dark:text-zinc-100">
+        {label}
+      </span>
       <Input
+        aria-invalid={!isColorValue}
         aria-label={`${label} hex value`}
-        className="flex w-28 shrink-0 self-stretch items-center rounded-none border-0 border-l border-border/70 bg-background/20 shadow-none"
+        className="w-28 shrink-0 rounded-none border-0 border-b border-zinc-300 bg-transparent font-mono text-xs text-zinc-900 shadow-none focus-within:border-blue-500 focus-within:ring-0 dark:border-zinc-700 dark:text-zinc-100 dark:focus-within:border-blue-400"
         id={`${role}-hex`}
         nativeInput
         onChange={(event) => onChange(event.currentTarget.value)}

From de811206df91e50bb4de80136518ecb8224e368f Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 15:02:19 +0200
Subject: [PATCH 10/25] fix(web): use themed dialog for theme deletion

---
 .../components/settings/SettingsPanels.tsx    | 50 ++++++++++++++++---
 1 file changed, 42 insertions(+), 8 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 1ff09ad9c16..b6b5b4dcb59 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -112,6 +112,15 @@ import { useProjects } from "../../state/entities";
 import { useArchivedThreadSnapshots } from "../../lib/archivedThreadsState";
 import { formatRelativeTimeLabel, getRelativeTimeState } from "../../timestampFormat";
 import { Button } from "../ui/button";
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogPopup,
+  AlertDialogTitle,
+} from "../ui/alert-dialog";
 import {
   Dialog,
   DialogDescription,
@@ -1822,6 +1831,7 @@ function ThemeLibrary({
 }) {
   const [isImportOpen, setIsImportOpen] = useState(false);
   const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const [themeToRemove, setThemeToRemove] = useState<ThemeDefinition | null>(null);
   const activeTheme = getThemeDefinition(theme);
   const standardThemes = getStandardThemeCards();
   const maintainerThemes = [T3_CHAT_THEME];
@@ -1840,14 +1850,16 @@ function ThemeLibrary({
     [activeTheme, initialAppearance, setFollowSystem, setTheme],
   );
 
-  const handleRemoveTheme = useCallback(
-    (customTheme: ThemeDefinition) => {
-      if (!window.confirm(`Remove the “${customTheme.label}” theme?`)) return;
-      if (getThemeDefinition(theme)?.id === customTheme.id) setTheme("system");
-      removeCustomTheme(customTheme.id);
-    },
-    [setTheme, theme],
-  );
+  const handleRemoveTheme = useCallback((customTheme: ThemeDefinition) => {
+    setThemeToRemove(customTheme);
+  }, []);
+
+  const handleConfirmRemoveTheme = useCallback(() => {
+    if (!themeToRemove) return;
+    if (getThemeDefinition(theme)?.id === themeToRemove.id) setTheme("system");
+    removeCustomTheme(themeToRemove.id);
+    setThemeToRemove(null);
+  }, [setTheme, theme, themeToRemove]);
 
   const handleCreatedTheme = useCallback(
     (createdTheme: ThemeDefinition) => {
@@ -1983,6 +1995,28 @@ function ThemeLibrary({
         onOpenChange={setIsImportOpen}
         open={isImportOpen}
       />
+      <AlertDialog
+        open={themeToRemove !== null}
+        onOpenChange={(open) => {
+          if (!open) setThemeToRemove(null);
+        }}
+      >
+        <AlertDialogPopup>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Remove “{themeToRemove?.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>
   );
 }

From 82f9299733c707583bd65dc21474c0c13e1d5c92 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 15:12:37 +0200
Subject: [PATCH 11/25] feat(web): edit personal themes

---
 .../components/settings/SettingsPanels.tsx    | 160 ++++++++++++++----
 apps/web/src/hooks/useTheme.ts                |   8 +
 apps/web/src/themePalette.test.ts             |  38 +++++
 apps/web/src/themePalette.ts                  |  18 ++
 4 files changed, 192 insertions(+), 32 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index b6b5b4dcb59..c8cee29a643 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -5,6 +5,7 @@ import {
   InfoIcon,
   LoaderIcon,
   MoonIcon,
+  PenLineIcon,
   PlusIcon,
   RefreshCwIcon,
   SettingsIcon,
@@ -84,6 +85,7 @@ import {
   removeCustomTheme,
   serializeThemeFile,
   themePreferenceForMode,
+  updateCustomTheme,
   type ThemeAppearance,
   type ThemeColorRole,
   type ThemeDefinition,
@@ -1164,17 +1166,20 @@ function ThemeColorField({
   );
 }
 
-function CreateThemeDialog({
+function ThemeEditorDialog({
   open,
   onOpenChange,
-  onCreated,
+  onSaved,
+  editingTheme,
   initialAppearance,
 }: {
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  onCreated: (theme: ThemeDefinition) => 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);
@@ -1187,15 +1192,29 @@ function CreateThemeDialog({
 
   useEffect(() => {
     if (open && !previousOpenRef.current) {
-      setName("");
-      setModeSelection("single");
-      setActiveAppearance(initialAppearance);
+      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(false);
-      setColorsByAppearance(getThemeEditorColorsByAppearance());
+      setColorsByAppearance(nextColors);
       setError(null);
     }
     previousOpenRef.current = open;
-  }, [initialAppearance, open]);
+  }, [editingTheme, initialAppearance, open]);
 
   const updateColor = useCallback(
     (role: ThemeColorRole, value: string) => {
@@ -1214,26 +1233,45 @@ function CreateThemeDialog({
     }
 
     try {
-      const variantAppearance = activeAppearance === "light" ? "dark" : "light";
+      const baseAppearance =
+        editingTheme && modeSelection === "both" ? editingTheme.appearance : activeAppearance;
+      const variantAppearance = baseAppearance === "light" ? "dark" : "light";
       const variants =
         modeSelection === "both"
           ? { [variantAppearance]: colorsByAppearance[variantAppearance] }
           : undefined;
-      const createdTheme = installCustomTheme(
-        parseThemeFile({
-          version: THEME_FILE_VERSION,
-          name,
-          appearance: activeAppearance,
-          colors: colorsByAppearance[activeAppearance],
-          ...(variants ? { variants } : {}),
-        }),
-      );
-      onCreated(createdTheme);
+      const themeFile = {
+        version: THEME_FILE_VERSION,
+        ...(editingTheme ? { id: editingTheme.id } : {}),
+        name,
+        appearance: baseAppearance,
+        colors: colorsByAppearance[baseAppearance],
+        ...(variants ? { variants } : {}),
+      };
+      const savedTheme = editingTheme
+        ? updateCustomTheme(parseThemeFile(themeFile))
+        : installCustomTheme(parseThemeFile(themeFile));
+      onSaved(savedTheme);
       onOpenChange(false);
     } catch (cause) {
-      setError(cause instanceof Error ? cause.message : "Could not create the theme.");
+      setError(
+        cause instanceof Error
+          ? cause.message
+          : isEditing
+            ? "Could not save the theme."
+            : "Could not create the theme.",
+      );
     }
-  }, [activeAppearance, colorsByAppearance, modeSelection, name, onCreated, onOpenChange]);
+  }, [
+    activeAppearance,
+    colorsByAppearance,
+    editingTheme,
+    isEditing,
+    modeSelection,
+    name,
+    onOpenChange,
+    onSaved,
+  ]);
 
   return (
     <Dialog
@@ -1245,9 +1283,11 @@ function CreateThemeDialog({
     >
       <DialogPopup className="max-w-3xl overflow-hidden">
         <DialogHeader>
-          <DialogTitle>Create theme</DialogTitle>
+          <DialogTitle>{isEditing ? "Edit theme" : "Create theme"}</DialogTitle>
           <DialogDescription>
-            Pick a palette for T3 Code. Add a dark version if you need one.
+            {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">
@@ -1256,7 +1296,7 @@ function CreateThemeDialog({
             <Input
               autoFocus
               onChange={(event) => setName(event.currentTarget.value)}
-              placeholder="e.g. Aurora"
+              placeholder={isEditing ? "Theme name" : "e.g. Aurora"}
               value={name}
             />
           </label>
@@ -1419,8 +1459,14 @@ function CreateThemeDialog({
             Cancel
           </Button>
           <Button disabled={!name.trim()} onClick={handleSubmit}>
-            <PlusIcon />
-            Create theme
+            {isEditing ? (
+              "Save changes"
+            ) : (
+              <>
+                <PlusIcon />
+                Create theme
+              </>
+            )}
           </Button>
         </DialogFooter>
       </DialogPopup>
@@ -1729,6 +1775,7 @@ function ThemeLibraryCard({
   onUse,
   onUseMode,
   activeMode,
+  onEdit,
   onDownload,
   onRemove,
 }: {
@@ -1738,6 +1785,7 @@ function ThemeLibraryCard({
   onUse: () => void;
   onUseMode?: ((mode: ThemeAppearance) => void) | undefined;
   activeMode?: ThemeAppearance | null;
+  onEdit?: () => void;
   onDownload?: () => void;
   onRemove?: () => void;
 }) {
@@ -1778,8 +1826,21 @@ function ThemeLibraryCard({
             ) : null}
           </div>
         </div>
-        {onDownload || onRemove ? (
+        {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}`}
@@ -1821,6 +1882,7 @@ function ThemeLibrary({
   setFollowSystem,
   customThemes,
   initialAppearance,
+  refreshTheme,
 }: {
   theme: string;
   setTheme: (theme: string) => void;
@@ -1828,9 +1890,11 @@ function ThemeLibrary({
   setFollowSystem: (followSystem: boolean) => void;
   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);
   const activeTheme = getThemeDefinition(theme);
   const standardThemes = getStandardThemeCards();
@@ -1875,6 +1939,29 @@ function ThemeLibrary({
     [setTheme],
   );
 
+  const handleEditedTheme = useCallback(
+    (updatedTheme: ThemeDefinition) => {
+      if (getThemeDefinition(theme)?.id === updatedTheme.id) {
+        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: "Your changes are now active.",
+        }),
+      );
+    },
+    [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">
@@ -1954,6 +2041,7 @@ function ThemeLibrary({
               isActive={isActive}
               isPersonal
               key={customTheme.id}
+              onEdit={() => setThemeToEdit(customTheme)}
               onDownload={() =>
                 downloadThemeFile(`${customTheme.id}.json`, serializeThemeFile(customTheme))
               }
@@ -1975,11 +2063,17 @@ function ThemeLibrary({
           Your themes will show up here.
         </div>
       ) : null}
-      <CreateThemeDialog
+      <ThemeEditorDialog
+        editingTheme={themeToEdit}
         initialAppearance={initialAppearance}
-        onCreated={handleCreatedTheme}
-        onOpenChange={setIsCreateOpen}
-        open={isCreateOpen}
+        onSaved={themeToEdit ? handleEditedTheme : handleCreatedTheme}
+        onOpenChange={(open) => {
+          if (!open) {
+            setIsCreateOpen(false);
+            setThemeToEdit(null);
+          }
+        }}
+        open={isCreateOpen || themeToEdit !== null}
       />
       <ThemeImportDialog
         onImported={(importedTheme) => {
@@ -2022,7 +2116,8 @@ function ThemeLibrary({
 }
 
 export function AppearanceSettingsPanel() {
-  const { theme, setTheme, setFollowSystem, followSystem, resolvedTheme } = useTheme();
+  const { theme, setTheme, setFollowSystem, refreshTheme, followSystem, resolvedTheme } =
+    useTheme();
   const customThemes = useCustomThemes();
   const settings = usePrimarySettings();
   const updateSettings = useUpdatePrimarySettings();
@@ -2043,6 +2138,7 @@ export function AppearanceSettingsPanel() {
           customThemes={customThemes}
           followSystem={followSystem}
           initialAppearance={resolvedTheme}
+          refreshTheme={refreshTheme}
           setFollowSystem={setFollowSystem}
           setTheme={setTheme}
           theme={theme}
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index afd7dec2ea0..e7d97211f48 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -412,6 +412,13 @@ export function useTheme() {
     emitChange();
   }, []);
 
+  const refreshTheme = useCallback(() => {
+    if (typeof window === "undefined") return;
+    lastAppliedTheme = null;
+    applyTheme(getStored(), true);
+    emitChange();
+  }, []);
+
   // Keep DOM in sync on mount/change
   useEffect(() => {
     applyTheme(theme);
@@ -421,6 +428,7 @@ export function useTheme() {
     theme,
     setTheme,
     setFollowSystem,
+    refreshTheme,
     followSystem: snapshot.followSystem,
     resolvedTheme,
   } as const;
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index cd7cc199b62..d8ca4f4d059 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -5,6 +5,7 @@ import {
   getThemeModes,
   getCustomThemes,
   invalidateCustomThemes,
+  installCustomTheme,
   isThemeFollowingSystem,
   parseThemeFile,
   resolveDesktopTheme,
@@ -14,6 +15,7 @@ import {
   T3_CHAT_THEME,
   themePreferenceForMode,
   themePreferenceForSystem,
+  updateCustomTheme,
   CUSTOM_THEMES_STORAGE_KEY,
   THEME_FILE_VERSION,
 } from "./themePalette";
@@ -164,4 +166,40 @@ describe("theme files", () => {
     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();
+  });
 });
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index 0514fa05a32..ee779b4fa14 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -482,6 +482,7 @@ function saveCustomThemes(themes: ReadonlyArray<ThemeDefinition>): void {
   } catch (cause) {
     throw new Error(
       `Could not save the theme library. ${cause instanceof Error ? cause.message : "Storage is unavailable."}`,
+      { cause },
     );
   }
   notifyCustomThemeListeners();
@@ -498,6 +499,23 @@ export function installCustomTheme(theme: ThemeDefinition): ThemeDefinition {
   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;

From 6a0acb144bb63d9bf07000fdfafc605481e9dad0 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Sun, 2 Aug 2026 15:21:52 +0200
Subject: [PATCH 12/25] feat(web): add theme color picker

---
 .../components/settings/SettingsPanels.tsx    | 375 ++++++++++++++++--
 1 file changed, 352 insertions(+), 23 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index c8cee29a643..c30b5def757 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -14,7 +14,7 @@ import {
   UploadIcon,
 } from "lucide-react";
 import { Link } from "@tanstack/react-router";
-import type { ChangeEvent, CSSProperties, UIEvent } from "react";
+import type { ChangeEvent, CSSProperties, KeyboardEvent, PointerEvent, UIEvent } from "react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useAtomValue } from "@effect/atom-react";
 import {
@@ -141,6 +141,7 @@ import {
   NumberFieldIncrement,
   NumberFieldInput,
 } from "../ui/number-field";
+import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
 import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
 import { Switch } from "../ui/switch";
 import { stackedThreadToast, toastManager } from "../ui/toast";
@@ -1116,6 +1117,345 @@ function getThemeRoleLabel(role: ThemeColorRole): string {
   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(() => {
+    const nextHsv = themeHexToHsv(normalizedValue);
+    setHsv(nextHsv);
+    setHexDraft(normalizedValue);
+    setRgbDraft(themeRgbValue(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-black/10 shadow-[inset_0_0_0_1px_rgb(255_255_255_/_28%),0_1px_2px_rgb(0_0_0_/_18%)] dark:border-white/15 dark:shadow-[inset_0_0_0_1px_rgb(255_255_255_/_18%),0_1px_2px_rgb(0_0_0_/_35%)]"
+          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-black/10 transition-transform hover:scale-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500/70 focus-visible:ring-offset-2 focus-visible:ring-offset-background dark:border-white/15 dark:focus-visible:ring-blue-400/70"
+            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>
+  );
+}
+
 function ThemeColorField({
   role,
   value,
@@ -1127,27 +1467,11 @@ function ThemeColorField({
 }) {
   const label = getThemeRoleLabel(role);
   const isColorValue = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value);
-  const pickerValue = /^#[0-9a-f]{6}$/i.test(value) ? value : "#000000";
   const swatchValue = isColorValue ? value : "#000000";
 
   return (
     <div className="group flex min-h-11 min-w-0 items-center gap-2 border-b border-zinc-200/70 px-1.5 py-1.5 transition-colors hover:bg-zinc-100/60 dark:border-zinc-800/70 dark:hover:bg-zinc-900/60">
-      <label
-        className="relative flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-full transition-transform hover:scale-105 focus-within:ring-2 focus-within:ring-blue-500/70 focus-within:ring-offset-2 focus-within:ring-offset-background dark:focus-within:ring-blue-400/70"
-        title={`Choose ${label} color`}
-      >
-        <span
-          className="absolute inset-0.5 rounded-full shadow-[inset_0_0_0_1px_rgb(0_0_0_/_14%),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: swatchValue }}
-        />
-        <input
-          aria-label={`Choose ${label} color`}
-          className="absolute inset-0 size-full cursor-pointer opacity-0"
-          onChange={(event) => onChange(event.currentTarget.value)}
-          type="color"
-          value={pickerValue}
-        />
-      </label>
+      <ThemeColorPicker label={label} onChange={onChange} value={swatchValue} />
       <span className="min-w-0 flex-1 truncate text-sm font-medium text-zinc-900 dark:text-zinc-100">
         {label}
       </span>
@@ -1234,7 +1558,9 @@ function ThemeEditorDialog({
 
     try {
       const baseAppearance =
-        editingTheme && modeSelection === "both" ? editingTheme.appearance : activeAppearance;
+        editingTheme && getThemeModes(editingTheme).length > 1
+          ? editingTheme.appearance
+          : activeAppearance;
       const variantAppearance = baseAppearance === "light" ? "dark" : "light";
       const variants =
         modeSelection === "both"
@@ -1920,10 +2246,12 @@ function ThemeLibrary({
 
   const handleConfirmRemoveTheme = useCallback(() => {
     if (!themeToRemove) return;
-    if (getThemeDefinition(theme)?.id === themeToRemove.id) setTheme("system");
+    if (getThemeDefinition(theme)?.id === themeToRemove.id) {
+      setTheme(followSystem ? "system" : initialAppearance);
+    }
     removeCustomTheme(themeToRemove.id);
     setThemeToRemove(null);
-  }, [setTheme, theme, themeToRemove]);
+  }, [followSystem, initialAppearance, setTheme, theme, themeToRemove]);
 
   const handleCreatedTheme = useCallback(
     (createdTheme: ThemeDefinition) => {
@@ -1941,7 +2269,8 @@ function ThemeLibrary({
 
   const handleEditedTheme = useCallback(
     (updatedTheme: ThemeDefinition) => {
-      if (getThemeDefinition(theme)?.id === updatedTheme.id) {
+      const wasActive = getThemeDefinition(theme)?.id === updatedTheme.id;
+      if (wasActive) {
         const selectedMode = followSystem ? null : getThemePreferenceMode(theme);
         const nextTheme =
           selectedMode && getThemeColorsForMode(updatedTheme, selectedMode)
@@ -1955,7 +2284,7 @@ function ThemeLibrary({
         stackedThreadToast({
           type: "success",
           title: `${updatedTheme.label} saved`,
-          description: "Your changes are now active.",
+          description: wasActive ? "Your changes are now active." : "Your changes are saved.",
         }),
       );
     },

From e4cf49aaec9c6bc383ed8c7e4cb46826863d72e7 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 07:58:51 +0200
Subject: [PATCH 13/25] fix(web): guide simple theme palettes

---
 .../components/settings/SettingsPanels.tsx    | 101 ++++--
 apps/web/src/themePalette.test.ts             |  36 +++
 apps/web/src/themePalette.ts                  | 297 ++++++++++++++++++
 3 files changed, 413 insertions(+), 21 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index c30b5def757..96cd23e75cb 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -75,6 +75,7 @@ import { cn } from "../../lib/utils";
 import {
   THEME_COLOR_ROLES,
   THEME_FILE_VERSION,
+  createManagedThemeColors,
   getDefaultThemeColors,
   getThemeColorsForMode,
   getThemeDefinition,
@@ -1101,6 +1102,22 @@ function getThemeEditorColorsByAppearance(): ThemeEditorColorsByAppearance {
   };
 }
 
+function isThemeEditorColor(value: string): boolean {
+  return /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(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,
+  );
+}
+
 function getThemeRoleLabel(role: ThemeColorRole): string {
   const labels: Partial<Record<ThemeColorRole, string>> = {
     canvas: "Background",
@@ -1460,12 +1477,14 @@ function ThemeColorField({
   role,
   value,
   onChange,
+  label: customLabel,
 }: {
   role: ThemeColorRole;
   value: string;
   onChange: (value: string) => void;
+  label?: string;
 }) {
-  const label = getThemeRoleLabel(role);
+  const label = customLabel ?? getThemeRoleLabel(role);
   const isColorValue = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value);
   const swatchValue = isColorValue ? value : "#000000";
 
@@ -1511,6 +1530,7 @@ function ThemeEditorDialog({
   const [colorsByAppearance, setColorsByAppearance] = useState<ThemeEditorColorsByAppearance>(() =>
     getThemeEditorColorsByAppearance(),
   );
+  const [simpleColorsDirty, setSimpleColorsDirty] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const previousOpenRef = useRef(false);
 
@@ -1534,6 +1554,7 @@ function ThemeEditorDialog({
       setModeSelection(editingTheme && getThemeModes(editingTheme).length > 1 ? "both" : "single");
       setActiveAppearance(nextAppearance);
       setIsAdvanced(false);
+      setSimpleColorsDirty(false);
       setColorsByAppearance(nextColors);
       setError(null);
     }
@@ -1542,14 +1563,36 @@ function ThemeEditorDialog({
 
   const updateColor = useCallback(
     (role: ThemeColorRole, value: string) => {
-      setColorsByAppearance((current) => ({
-        ...current,
-        [activeAppearance]: { ...current[activeAppearance], [role]: value },
-      }));
+      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)) {
+        setSimpleColorsDirty(true);
+      }
     },
-    [activeAppearance],
+    [activeAppearance, isAdvanced],
   );
 
+  const handleAdvancedChange = useCallback((checked: boolean) => {
+    setIsAdvanced(checked);
+    if (checked) return;
+
+    setSimpleColorsDirty(true);
+    setColorsByAppearance((current) => ({
+      light: getManagedEditorColors("light", current.light),
+      dark: getManagedEditorColors("dark", current.dark),
+    }));
+  }, []);
+
   const handleSubmit = useCallback(() => {
     if (!name.trim()) {
       setError("Give your theme a name before saving it.");
@@ -1562,16 +1605,23 @@ function ThemeEditorDialog({
           ? editingTheme.appearance
           : activeAppearance;
       const variantAppearance = baseAppearance === "light" ? "dark" : "light";
+      const colorsForSave =
+        !isAdvanced && (!isEditing || simpleColorsDirty)
+          ? {
+              light: getManagedEditorColors("light", colorsByAppearance.light),
+              dark: getManagedEditorColors("dark", colorsByAppearance.dark),
+            }
+          : colorsByAppearance;
       const variants =
         modeSelection === "both"
-          ? { [variantAppearance]: colorsByAppearance[variantAppearance] }
+          ? { [variantAppearance]: colorsForSave[variantAppearance] }
           : undefined;
       const themeFile = {
         version: THEME_FILE_VERSION,
         ...(editingTheme ? { id: editingTheme.id } : {}),
         name,
         appearance: baseAppearance,
-        colors: colorsByAppearance[baseAppearance],
+        colors: colorsForSave[baseAppearance],
         ...(variants ? { variants } : {}),
       };
       const savedTheme = editingTheme
@@ -1592,11 +1642,13 @@ function ThemeEditorDialog({
     activeAppearance,
     colorsByAppearance,
     editingTheme,
+    isAdvanced,
     isEditing,
     modeSelection,
     name,
     onOpenChange,
     onSaved,
+    simpleColorsDirty,
   ]);
 
   return (
@@ -1680,12 +1732,12 @@ function ThemeEditorDialog({
             <div className="flex items-start justify-between gap-3">
               <div>
                 <h3 className="text-sm font-medium">
-                  {isAdvanced ? "Theme colors" : "Basic colors"}
+                  {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 a background and accent. T3 Code fills in the rest."}
+                    : "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">
@@ -1693,7 +1745,7 @@ function ThemeEditorDialog({
                 <Switch
                   aria-label="Use advanced theme colors"
                   checked={isAdvanced}
-                  onCheckedChange={(checked) => setIsAdvanced(Boolean(checked))}
+                  onCheckedChange={(checked) => handleAdvancedChange(Boolean(checked))}
                 />
               </label>
             </div>
@@ -1758,16 +1810,23 @@ function ThemeEditorDialog({
                 </div>
               </>
             ) : (
-              <div className="grid gap-2 sm:grid-cols-2">
-                {THEME_EDITOR_SIMPLE_ROLES.map((role) => (
-                  <ThemeColorField
-                    key={role}
-                    onChange={(value) => updateColor(role, value)}
-                    role={role}
-                    value={colorsByAppearance[activeAppearance][role]}
-                  />
-                ))}
-              </div>
+              <>
+                <div className="grid gap-2 sm:grid-cols-2">
+                  {THEME_EDITOR_SIMPLE_ROLES.map((role) => (
+                    <ThemeColorField
+                      key={role}
+                      onChange={(value) => updateColor(role, value)}
+                      role={role}
+                      label={role === "canvas" ? "Background tint" : "Accent color"}
+                      value={colorsByAppearance[activeAppearance][role]}
+                    />
+                  ))}
+                </div>
+                <p className="text-xs leading-relaxed text-muted-foreground">
+                  These two colors guide the palette. Text, surfaces, buttons, and code colors are
+                  adjusted for the selected appearance automatically.
+                </p>
+              </>
             )}
           </div>
 
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index d8ca4f4d059..ed89e196bf0 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -17,10 +17,46 @@ import {
   themePreferenceForSystem,
   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,
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index ee779b4fa14..97b954afae4 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -383,6 +383,303 @@ const DEFAULT_DARK_THEME_COLORS: ThemeColors = {
   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: 255, g: 250, b: 255 },
+  );
+  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: 197, g: 45, b: 123 });
+  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 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(
+      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.025),
+    ),
+    codeForeground: themeRgbToHexColor(
+      readableThemeForeground(
+        mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.025),
+      ),
+    ),
+    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(
+      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.2 : 0.035),
+    ),
+    terminalForeground: themeRgbToHexColor(
+      readableThemeForeground(mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.2 : 0.035)),
+    ),
+    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,

From cd5063912d54efd9bf4a3a125aff7e8f51b7035d Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 08:53:23 +0200
Subject: [PATCH 14/25] feat(web): add T3 Grove theme

---
 .../components/settings/SettingsPanels.tsx    | 66 ++++++++++++-------
 apps/web/src/themePalette.test.ts             |  9 +++
 apps/web/src/themePalette.ts                  | 15 ++++-
 3 files changed, 66 insertions(+), 24 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 96cd23e75cb..5b95d4272ad 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -91,6 +91,7 @@ import {
   type ThemeColorRole,
   type ThemeDefinition,
   T3_CHAT_THEME,
+  T3_GROVE_THEME,
 } from "../../themePalette";
 import { usePrimarySettings, useUpdatePrimarySettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
@@ -1530,7 +1531,9 @@ function ThemeEditorDialog({
   const [colorsByAppearance, setColorsByAppearance] = useState<ThemeEditorColorsByAppearance>(() =>
     getThemeEditorColorsByAppearance(),
   );
-  const [simpleColorsDirty, setSimpleColorsDirty] = useState(false);
+  const [simpleColorsDirtyByAppearance, setSimpleColorsDirtyByAppearance] = useState<
+    Record<ThemeAppearance, boolean>
+  >({ light: false, dark: false });
   const [error, setError] = useState<string | null>(null);
   const previousOpenRef = useRef(false);
 
@@ -1554,7 +1557,7 @@ function ThemeEditorDialog({
       setModeSelection(editingTheme && getThemeModes(editingTheme).length > 1 ? "both" : "single");
       setActiveAppearance(nextAppearance);
       setIsAdvanced(false);
-      setSimpleColorsDirty(false);
+      setSimpleColorsDirtyByAppearance({ light: false, dark: false });
       setColorsByAppearance(nextColors);
       setError(null);
     }
@@ -1576,22 +1579,31 @@ function ThemeEditorDialog({
         };
       });
       if (!isAdvanced && THEME_EDITOR_SIMPLE_ROLES.includes(role) && isThemeEditorColor(value)) {
-        setSimpleColorsDirty(true);
+        setSimpleColorsDirtyByAppearance((current) => ({
+          ...current,
+          [activeAppearance]: true,
+        }));
       }
     },
     [activeAppearance, isAdvanced],
   );
 
-  const handleAdvancedChange = useCallback((checked: boolean) => {
-    setIsAdvanced(checked);
-    if (checked) return;
-
-    setSimpleColorsDirty(true);
-    setColorsByAppearance((current) => ({
-      light: getManagedEditorColors("light", current.light),
-      dark: getManagedEditorColors("dark", current.dark),
-    }));
-  }, []);
+  const handleAdvancedChange = useCallback(
+    (checked: boolean) => {
+      setIsAdvanced(checked);
+      if (checked) return;
+
+      setSimpleColorsDirtyByAppearance((current) => ({
+        ...current,
+        [activeAppearance]: true,
+      }));
+      setColorsByAppearance((current) => ({
+        ...current,
+        [activeAppearance]: getManagedEditorColors(activeAppearance, current[activeAppearance]),
+      }));
+    },
+    [activeAppearance],
+  );
 
   const handleSubmit = useCallback(() => {
     if (!name.trim()) {
@@ -1605,13 +1617,18 @@ function ThemeEditorDialog({
           ? editingTheme.appearance
           : activeAppearance;
       const variantAppearance = baseAppearance === "light" ? "dark" : "light";
-      const colorsForSave =
-        !isAdvanced && (!isEditing || simpleColorsDirty)
-          ? {
-              light: getManagedEditorColors("light", colorsByAppearance.light),
-              dark: getManagedEditorColors("dark", colorsByAppearance.dark),
-            }
-          : colorsByAppearance;
+      const colorsForSave = !isAdvanced
+        ? {
+            light:
+              !isEditing || simpleColorsDirtyByAppearance.light
+                ? getManagedEditorColors("light", colorsByAppearance.light)
+                : colorsByAppearance.light,
+            dark:
+              !isEditing || simpleColorsDirtyByAppearance.dark
+                ? getManagedEditorColors("dark", colorsByAppearance.dark)
+                : colorsByAppearance.dark,
+          }
+        : colorsByAppearance;
       const variants =
         modeSelection === "both"
           ? { [variantAppearance]: colorsForSave[variantAppearance] }
@@ -1648,7 +1665,7 @@ function ThemeEditorDialog({
     name,
     onOpenChange,
     onSaved,
-    simpleColorsDirty,
+    simpleColorsDirtyByAppearance,
   ]);
 
   return (
@@ -2283,7 +2300,7 @@ function ThemeLibrary({
   const [themeToRemove, setThemeToRemove] = useState<ThemeDefinition | null>(null);
   const activeTheme = getThemeDefinition(theme);
   const standardThemes = getStandardThemeCards();
-  const maintainerThemes = [T3_CHAT_THEME];
+  const maintainerThemes = [T3_CHAT_THEME, T3_GROVE_THEME];
 
   const handleFollowSystemChange = useCallback(
     (checked: boolean) => {
@@ -2376,7 +2393,10 @@ function ThemeLibrary({
       <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="grid gap-2 px-3 sm:grid-cols-2 sm:px-4">
+      <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={
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index ed89e196bf0..66ad3498798 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vite-plus/test";
 
 import {
   getThemeColorsForMode,
+  getThemeDefinition,
   getThemeModes,
   getCustomThemes,
   invalidateCustomThemes,
@@ -13,6 +14,7 @@ import {
   serializeThemeFile,
   subscribeToCustomThemes,
   T3_CHAT_THEME,
+  T3_GROVE_THEME,
   themePreferenceForMode,
   themePreferenceForSystem,
   updateCustomTheme,
@@ -142,6 +144,13 @@ describe("theme files", () => {
     });
   });
 
+  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({
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index 97b954afae4..624f1a898c1 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -2,6 +2,8 @@ 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";
@@ -94,6 +96,7 @@ const RESERVED_THEME_IDS = new Set([
   "light",
   "dark",
   T3_CHAT_THEME_ID,
+  T3_GROVE_THEME_ID,
   LEGACY_T3_CHAT_DARK_THEME_ID,
 ]);
 
@@ -692,7 +695,17 @@ export function getDefaultThemeColors(appearance: ThemeAppearance): ThemeColors
   return appearance === "dark" ? DEFAULT_DARK_THEME_COLORS : T3_CHAT_THEME.colors;
 }
 
-const BUILT_IN_THEME_DEFINITIONS: ReadonlyArray<ThemeDefinition> = [T3_CHAT_THEME];
+export const T3_GROVE_THEME: ThemeDefinition = {
+  id: T3_GROVE_THEME_ID,
+  label: T3_GROVE_THEME_LABEL,
+  appearance: "light",
+  colors: createManagedThemeColors("light", "#f2faf4", "#218c5c"),
+  variants: {
+    dark: createManagedThemeColors("dark", "#102019", "#5ed58f"),
+  },
+};
+
+const BUILT_IN_THEME_DEFINITIONS: ReadonlyArray<ThemeDefinition> = [T3_CHAT_THEME, T3_GROVE_THEME];
 
 export function getThemeDefinition(theme: ThemePreference): ThemeDefinition | null {
   const themeId = themeIdFromPreference(theme);

From 2650133712e19aa85dcb835f09aa38884a897e60 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 08:54:38 +0200
Subject: [PATCH 15/25] fix(web): simplify guided theme copy

---
 apps/web/src/components/settings/SettingsPanels.tsx | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 5b95d4272ad..8ab1e9ff9f9 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1839,10 +1839,6 @@ function ThemeEditorDialog({
                     />
                   ))}
                 </div>
-                <p className="text-xs leading-relaxed text-muted-foreground">
-                  These two colors guide the palette. Text, surfaces, buttons, and code colors are
-                  adjusted for the selected appearance automatically.
-                </p>
               </>
             )}
           </div>

From 9535885ba7f8af4e70c06e6ce0c42ccd207e9e4e Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 09:07:01 +0200
Subject: [PATCH 16/25] fix(web): theme theme editor actions

---
 .../web/src/components/settings/SettingsPanels.tsx | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 8ab1e9ff9f9..0322bf314a6 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1345,7 +1345,7 @@ function ThemeColorPickerPanel({
           <p className="text-[11px] text-muted-foreground">Choose a color</p>
         </div>
         <span
-          className="size-7 shrink-0 rounded-full border border-black/10 shadow-[inset_0_0_0_1px_rgb(255_255_255_/_28%),0_1px_2px_rgb(0_0_0_/_18%)] dark:border-white/15 dark:shadow-[inset_0_0_0_1px_rgb(255_255_255_/_18%),0_1px_2px_rgb(0_0_0_/_35%)]"
+          className="size-7 shrink-0 rounded-full border border-border shadow-sm"
           style={{ backgroundColor: currentColor }}
         />
       </div>
@@ -1451,7 +1451,7 @@ function ThemeColorPicker({
         render={
           <button
             aria-label={`Choose ${label} color`}
-            className="relative flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-full border border-black/10 transition-transform hover:scale-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500/70 focus-visible:ring-offset-2 focus-visible:ring-offset-background dark:border-white/15 dark:focus-visible:ring-blue-400/70"
+            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"
           >
@@ -1490,15 +1490,13 @@ function ThemeColorField({
   const swatchValue = isColorValue ? value : "#000000";
 
   return (
-    <div className="group flex min-h-11 min-w-0 items-center gap-2 border-b border-zinc-200/70 px-1.5 py-1.5 transition-colors hover:bg-zinc-100/60 dark:border-zinc-800/70 dark:hover:bg-zinc-900/60">
+    <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={onChange} value={swatchValue} />
-      <span className="min-w-0 flex-1 truncate text-sm font-medium text-zinc-900 dark:text-zinc-100">
-        {label}
-      </span>
+      <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-zinc-300 bg-transparent font-mono text-xs text-zinc-900 shadow-none focus-within:border-blue-500 focus-within:ring-0 dark:border-zinc-700 dark:text-zinc-100 dark:focus-within:border-blue-400"
+        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(event.currentTarget.value)}
@@ -2257,7 +2255,7 @@ function ThemeLibraryCard({
                 aria-label={`Remove ${theme.label}`}
                 size="icon-xs"
                 variant="ghost"
-                className="text-muted-foreground hover:text-destructive"
+                className="text-muted-foreground hover:text-primary"
                 onClick={(event) => {
                   event.stopPropagation();
                   onRemove();

From 89d70e928a34e94f719059d8d9c2d430063229e5 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 09:17:37 +0200
Subject: [PATCH 17/25] fix(web): theme theme removal action

---
 apps/web/index.html                           | 54 ++++++++++++++-----
 .../components/settings/SettingsPanels.tsx    |  9 +---
 2 files changed, 42 insertions(+), 21 deletions(-)

diff --git a/apps/web/index.html b/apps/web/index.html
index cda8e9a64e9..98f93c65c32 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -17,6 +17,8 @@
         const DARK_BACKGROUND = "#161616";
         const T3_CHAT_BACKGROUND = "#fffaff";
         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 = {
@@ -40,6 +42,16 @@
             foreground: "#faeaf9",
             accent: "#f06cab",
           },
+          t3Grove: {
+            background: "#f4f8f5",
+            foreground: "#241523",
+            accent: "#1e7d52",
+          },
+          t3GroveDark: {
+            background: "#111f19",
+            foreground: "#fffaff",
+            accent: "#5dd58e",
+          },
         };
         const themeColorMeta = document.querySelector('meta[name="theme-color"]');
 
@@ -122,7 +134,9 @@
             isLegacyT3ChatDark ||
             (!preference.invalidMode &&
               (preference.id === "t3-chat" || preference.id === "t3-chat-dark"));
-          const t3ChatMode = isLegacyT3ChatDark
+          const isT3Grove = !preference.invalidMode && preference.id === "t3-grove";
+          const isBuiltInTheme = isT3Chat || isT3Grove;
+          const builtInMode = isLegacyT3ChatDark
             ? followSystem
               ? prefersDark
                 ? "dark"
@@ -139,18 +153,22 @@
             storedTheme === "light" ||
             storedTheme === "dark" ||
             storedTheme === "system" ||
-            isT3Chat ||
+            isBuiltInTheme ||
             customTheme !== null;
           const theme = hasStoredTheme && storedTheme ? storedTheme : "system";
           const isDark = customTheme
             ? customTheme.mode === "dark"
-            : isT3Chat
-              ? t3ChatMode === "dark"
+            : isBuiltInTheme
+              ? builtInMode === "dark"
               : followSystem
                 ? prefersDark
                 : theme === "dark";
-          if (isT3Chat || customTheme !== null) {
-            document.documentElement.dataset.themeId = isT3Chat ? "t3-chat" : customTheme.theme.id;
+          if (isBuiltInTheme || customTheme !== null) {
+            document.documentElement.dataset.themeId = isBuiltInTheme
+              ? isT3Grove
+                ? "t3-grove"
+                : "t3-chat"
+              : customTheme.theme.id;
           } else {
             delete document.documentElement.dataset.themeId;
           }
@@ -163,10 +181,14 @@
           const chromeColor =
             customTheme !== null
               ? customTheme.colors.canvas
-              : isT3Chat
-                ? t3ChatMode === "dark"
-                  ? T3_CHAT_DARK_BACKGROUND
-                  : T3_CHAT_BACKGROUND
+              : isBuiltInTheme
+                ? builtInMode === "dark"
+                  ? isT3Grove
+                    ? T3_GROVE_DARK_BACKGROUND
+                    : T3_CHAT_DARK_BACKGROUND
+                  : isT3Grove
+                    ? T3_GROVE_BACKGROUND
+                    : T3_CHAT_BACKGROUND
                 : isDark
                   ? DARK_BACKGROUND
                   : LIGHT_BACKGROUND;
@@ -179,10 +201,14 @@
                     foreground: customTheme.colors.text,
                     accent: customTheme.colors.accent,
                   }
-                : isT3Chat
-                  ? t3ChatMode === "dark"
-                    ? SPLASH_COLORS.t3ChatDark
-                    : SPLASH_COLORS.t3Chat
+                : isBuiltInTheme
+                  ? isT3Grove
+                    ? builtInMode === "dark"
+                      ? SPLASH_COLORS.t3GroveDark
+                      : SPLASH_COLORS.t3Grove
+                    : builtInMode === "dark"
+                      ? SPLASH_COLORS.t3ChatDark
+                      : SPLASH_COLORS.t3Chat
                   : isDark
                     ? SPLASH_COLORS.dark
                     : SPLASH_COLORS.light;
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 0322bf314a6..5bbfcc420fa 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1610,10 +1610,7 @@ function ThemeEditorDialog({
     }
 
     try {
-      const baseAppearance =
-        editingTheme && getThemeModes(editingTheme).length > 1
-          ? editingTheme.appearance
-          : activeAppearance;
+      const baseAppearance = editingTheme?.appearance ?? activeAppearance;
       const variantAppearance = baseAppearance === "light" ? "dark" : "light";
       const colorsForSave = !isAdvanced
         ? {
@@ -2507,9 +2504,7 @@ function ThemeLibrary({
           </AlertDialogHeader>
           <AlertDialogFooter>
             <AlertDialogClose render={<Button variant="outline" />}>Cancel</AlertDialogClose>
-            <Button variant="destructive" onClick={handleConfirmRemoveTheme}>
-              Remove theme
-            </Button>
+            <Button onClick={handleConfirmRemoveTheme}>Remove theme</Button>
           </AlertDialogFooter>
         </AlertDialogPopup>
       </AlertDialog>

From ea199da32203e3cbe9d1dbcbe591057a01b3b56d Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 09:34:46 +0200
Subject: [PATCH 18/25] fix(web): align theme mode boot behavior

---
 apps/web/index.html                                 | 6 +-----
 apps/web/src/components/settings/SettingsPanels.tsx | 3 ++-
 apps/web/src/themePalette.ts                        | 4 ++--
 3 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/apps/web/index.html b/apps/web/index.html
index 98f93c65c32..3d17d9f35b8 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -137,11 +137,7 @@
           const isT3Grove = !preference.invalidMode && preference.id === "t3-grove";
           const isBuiltInTheme = isT3Chat || isT3Grove;
           const builtInMode = isLegacyT3ChatDark
-            ? followSystem
-              ? prefersDark
-                ? "dark"
-                : "light"
-              : "dark"
+            ? "light"
             : followSystem || preference.mode === "system"
               ? prefersDark
                 ? "dark"
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 5bbfcc420fa..95c13045dbf 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1610,7 +1610,8 @@ function ThemeEditorDialog({
     }
 
     try {
-      const baseAppearance = editingTheme?.appearance ?? activeAppearance;
+      const baseAppearance =
+        editingTheme && modeSelection === "both" ? editingTheme.appearance : activeAppearance;
       const variantAppearance = baseAppearance === "light" ? "dark" : "light";
       const colorsForSave = !isAdvanced
         ? {
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index 624f1a898c1..ba02abaa6d7 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -699,9 +699,9 @@ export const T3_GROVE_THEME: ThemeDefinition = {
   id: T3_GROVE_THEME_ID,
   label: T3_GROVE_THEME_LABEL,
   appearance: "light",
-  colors: createManagedThemeColors("light", "#f2faf4", "#218c5c"),
+  colors: createManagedThemeColors("light", "#f4f8f5", "#1e7d52"),
   variants: {
-    dark: createManagedThemeColors("dark", "#102019", "#5ed58f"),
+    dark: createManagedThemeColors("dark", "#111f19", "#5dd58e"),
   },
 };
 

From cdd64702476d67f02e1b40924a47aa4eea3c2dce Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 09:36:56 +0200
Subject: [PATCH 19/25] fix(web): use theme tokens for status accents

---
 apps/web/src/components/DiffPanel.tsx               | 2 +-
 apps/web/src/components/chat/ComposerStashMenu.tsx  | 2 +-
 apps/web/src/components/chat/ContextWindowMeter.tsx | 2 +-
 apps/web/src/components/chat/ModelListRow.tsx       | 2 +-
 apps/web/src/components/chat/ModelPickerSidebar.tsx | 2 +-
 apps/web/src/components/files/FilePreviewPanel.tsx  | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index dd77be9cc3b..a1d96231c3e 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -839,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/chat/ComposerStashMenu.tsx b/apps/web/src/components/chat/ComposerStashMenu.tsx
index 34a7b84b0a4..9e923851533 100644
--- a/apps/web/src/components/chat/ComposerStashMenu.tsx
+++ b/apps/web/src/components/chat/ComposerStashMenu.tsx
@@ -145,7 +145,7 @@ export const ComposerStashMenu = memo(function ComposerStashMenu(props: {
                       {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>
diff --git a/apps/web/src/components/chat/ContextWindowMeter.tsx b/apps/web/src/components/chat/ContextWindowMeter.tsx
index bba6f6a9ace..d7610712a14 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 (
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/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index 281f8958f72..f9b0999ca72 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -967,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}

From c326c28bd20fb88e1e2f5a76932557b816ae20b1 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 10:55:23 +0200
Subject: [PATCH 20/25] fix(web): harden theme boot parity, editor state, and
 token regressions

Full review pass over the modular theme system:

- Rewrite the index.html boot script to mirror runtime resolution exactly:
  clamp built-in themes to their available modes (T3 Chat is light-only),
  treat unrecognized preferences as the system default, follow the OS in
  the storage-failure fallback, and honor corrupted follow-system values
  the same way the runtime does. Add a boot/runtime parity test that
  evaluates the inline script against resolveThemeAppearance.
- Keep the color picker's hue when a grey/white/black echo round-trips,
  open hand-tuned themes in advanced mode so guided regeneration cannot
  silently discard their palettes, and regenerate every saved appearance
  when toggling Advanced off.
- Cache the useTheme snapshot instead of reading localStorage on every
  consumer render, and share one storage/matchMedia listener pair.
- Restore hover and emphasis states lost in the token migration
  (message action hover, provider update pill, sidebar read/unread,
  plan-mode toggle) and fix message-foreground tokens used on
  background surfaces.
- Extract the theme library/editor into ThemeSettings.tsx, memoize the
  color rows, reuse the Alert component and shared isThemeColor, drop
  the dead StageBackdropButtonArt and themePreferenceForSystem, and make
  stored-theme parsing tolerant of unknown roles from other builds.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/index.html                           |  255 +--
 .../components/SidebarStageBackdrop.test.tsx  |    3 +-
 .../src/components/SidebarStageBackdrop.tsx   |   12 +-
 apps/web/src/components/SidebarV2.tsx         |    4 +-
 apps/web/src/components/chat/ChatComposer.tsx |    2 +-
 .../chat/ComposerPreviewAnnotationCards.tsx   |    2 +-
 .../src/components/chat/MessagesTimeline.tsx  |    2 +-
 .../components/settings/SettingsPanels.tsx    | 1581 +---------------
 .../src/components/settings/ThemeSettings.tsx | 1640 +++++++++++++++++
 .../sidebar/SidebarProviderUpdatePill.tsx     |    2 +-
 apps/web/src/hooks/useTheme.ts                |   75 +-
 apps/web/src/index.css                        |    4 +-
 apps/web/src/themeBoot.test.ts                |  242 +++
 apps/web/src/themePalette.test.ts             |   64 +-
 apps/web/src/themePalette.ts                  |   71 +-
 15 files changed, 2175 insertions(+), 1784 deletions(-)
 create mode 100644 apps/web/src/components/settings/ThemeSettings.tsx
 create mode 100644 apps/web/src/themeBoot.test.ts

diff --git a/apps/web/index.html b/apps/web/index.html
index 3d17d9f35b8..b781abda550 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -53,6 +53,21 @@
             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",
+        ];
         const themeColorMeta = document.querySelector('meta[name="theme-color"]');
 
         const isHexColor = (value) =>
@@ -73,47 +88,22 @@
             invalidMode: !isThemePreferenceMode(rawMode),
           };
         };
-        const readCustomTheme = (themePreference, systemDark, followSystem) => {
-          if (!themePreference) return null;
-          const preference = splitThemePreference(themePreference);
-          if (preference.invalidMode) return null;
+        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;
-            const candidate = parsed.find(
-              (value) =>
-                value &&
-                value.id === preference.id &&
-                isThemeAppearance(value.appearance) &&
-                value.colors,
+            return (
+              parsed.find(
+                (value) =>
+                  value &&
+                  value.id === themeId &&
+                  isThemeAppearance(value.appearance) &&
+                  value.colors,
+              ) ?? null
             );
-            if (!candidate) return null;
-
-            const preferredMode =
-              followSystem || preference.mode === "system"
-                ? systemDark
-                  ? "dark"
-                  : "light"
-                : (preference.mode ?? candidate.appearance);
-            const mode =
-              preferredMode === candidate.appearance || candidate.variants?.[preferredMode]
-                ? preferredMode
-                : candidate.appearance;
-            const colors =
-              mode === candidate.appearance
-                ? candidate.colors
-                : (candidate.variants?.[mode] ?? candidate.colors);
-            if (
-              !colors ||
-              !isHexColor(colors.canvas) ||
-              !isHexColor(colors.text) ||
-              !isHexColor(colors.accent)
-            ) {
-              return null;
-            }
-            return { theme: candidate, colors, mode };
           } catch {
             return null;
           }
@@ -122,103 +112,148 @@
         try {
           const storedTheme = window.localStorage.getItem("t3code:theme");
           const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
-          const preference = splitThemePreference(storedTheme ?? "");
+          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" ||
-            (storedFollowSystem === null &&
-              (storedTheme === null || storedTheme === "system" || preference.mode === "system"));
-          const customTheme = readCustomTheme(storedTheme, prefersDark, followSystem);
-          const isLegacyT3ChatDark = storedTheme === "t3-chat-dark";
-          const isT3Chat =
-            isLegacyT3ChatDark ||
-            (!preference.invalidMode &&
-              (preference.id === "t3-chat" || preference.id === "t3-chat-dark"));
-          const isT3Grove = !preference.invalidMode && preference.id === "t3-grove";
-          const isBuiltInTheme = isT3Chat || isT3Grove;
-          const builtInMode = isLegacyT3ChatDark
-            ? "light"
+            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";
+          const themeMode = !isThemed
+            ? null
             : followSystem || preference.mode === "system"
+              ? themeModes.includes(systemMode)
+                ? systemMode
+                : baseAppearance
+              : (explicitMode ?? baseAppearance);
+          const isDark = isThemed
+            ? themeMode === "dark"
+            : followSystem
               ? prefersDark
-                ? "dark"
-                : "light"
-              : preference.id === "t3-chat-dark"
-                ? "dark"
-                : (preference.mode ?? "light");
-          const hasStoredTheme =
-            storedTheme === "light" ||
-            storedTheme === "dark" ||
-            storedTheme === "system" ||
-            isBuiltInTheme ||
-            customTheme !== null;
-          const theme = hasStoredTheme && storedTheme ? storedTheme : "system";
-          const isDark = customTheme
-            ? customTheme.mode === "dark"
-            : isBuiltInTheme
-              ? builtInMode === "dark"
-              : followSystem
-                ? prefersDark
-                : theme === "dark";
-          if (isBuiltInTheme || customTheme !== null) {
-            document.documentElement.dataset.themeId = isBuiltInTheme
-              ? isT3Grove
-                ? "t3-grove"
-                : "t3-chat"
-              : customTheme.theme.id;
+              : 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 (hasStoredTheme) {
+          if (isKnownTheme && storedTheme !== null) {
             document.documentElement.dataset.themeSelected = "true";
           } else {
             delete document.documentElement.dataset.themeSelected;
           }
           document.documentElement.classList.toggle("dark", isDark);
-          const chromeColor =
-            customTheme !== null
-              ? customTheme.colors.canvas
-              : isBuiltInTheme
-                ? builtInMode === "dark"
-                  ? isT3Grove
-                    ? T3_GROVE_DARK_BACKGROUND
-                    : T3_CHAT_DARK_BACKGROUND
-                  : isT3Grove
-                    ? T3_GROVE_BACKGROUND
-                    : T3_CHAT_BACKGROUND
-                : 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;
-          if (hasStoredTheme) {
+          if (isKnownTheme && storedTheme !== null) {
             const splashColors =
-              customTheme !== null
-                ? {
-                    background: customTheme.colors.canvas,
-                    foreground: customTheme.colors.text,
-                    accent: customTheme.colors.accent,
-                  }
-                : isBuiltInTheme
-                  ? isT3Grove
-                    ? builtInMode === "dark"
-                      ? SPLASH_COLORS.t3GroveDark
-                      : SPLASH_COLORS.t3Grove
-                    : builtInMode === "dark"
-                      ? SPLASH_COLORS.t3ChatDark
-                      : SPLASH_COLORS.t3Chat
-                  : isDark
-                    ? SPLASH_COLORS.dark
-                    : SPLASH_COLORS.light;
+              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);
             }
           }
           themeColorMeta?.setAttribute("content", chromeColor);
         } catch {
+          // 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.add("dark");
-          document.documentElement.style.backgroundColor = DARK_BACKGROUND;
-          themeColorMeta?.setAttribute("content", DARK_BACKGROUND);
+          document.documentElement.classList.toggle("dark", prefersDark);
+          const fallbackColor = prefersDark ? DARK_BACKGROUND : LIGHT_BACKGROUND;
+          document.documentElement.style.backgroundColor = fallbackColor;
+          themeColorMeta?.setAttribute("content", fallbackColor);
         }
       })();
     </script>
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 0f4652edf11..4864e827258 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -734,7 +734,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                   ? "text-secondary-label"
                   : status === "failed"
                     ? "text-foreground/95"
-                    : "text-foreground",
+                    : "text-foreground/90",
             )
           : cn(
               "truncate group-hover/v2-row:text-foreground",
@@ -742,7 +742,7 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
                 ? "text-foreground"
                 : isUnread
                   ? "text-muted-foreground"
-                  : "text-secondary-label",
+                  : "text-secondary-label/70",
             ),
         isRegeneratingTitle && "opacity-[0.55]",
       )}
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index a02033d0993..1f6f641032e 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -379,7 +379,7 @@ const ComposerFooterModeControls = memo(function ComposerFooterModeControls(prop
                   className={cn(
                     "shrink-0 whitespace-nowrap",
                     props.planSidebarOpen
-                      ? "bg-accent text-accent-foreground hover:bg-accent/80"
+                      ? "bg-primary/10 text-primary hover:bg-primary/15"
                       : "text-secondary-label hover:text-foreground",
                   )}
                   type="button"
diff --git a/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx b/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx
index f19ab572a84..5e9e43dcf21 100644
--- a/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx
+++ b/apps/web/src/components/chat/ComposerPreviewAnnotationCards.tsx
@@ -69,7 +69,7 @@ export function ComposerPreviewAnnotationCards({
             )}
             <div className="min-w-0 px-2.5 py-2 pr-8">
               {annotation.comment.trim() ? (
-                <p className="max-w-80 truncate text-message-foreground text-xs font-medium">
+                <p className="max-w-80 truncate text-foreground text-xs font-medium">
                   {annotation.comment.trim()}
                 </p>
               ) : null}
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index 33fefd84a96..c88ba8a50e9 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -1326,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-message-foreground text-xs">
+          <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>
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 95c13045dbf..45d53e49893 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1,21 +1,15 @@
 import {
   ArchiveIcon,
   ArchiveX,
-  DownloadIcon,
   InfoIcon,
   LoaderIcon,
-  MoonIcon,
-  PenLineIcon,
   PlusIcon,
   RefreshCwIcon,
   SettingsIcon,
-  SunIcon,
-  Trash2Icon,
-  UploadIcon,
 } from "lucide-react";
 import { Link } from "@tanstack/react-router";
-import type { ChangeEvent, CSSProperties, KeyboardEvent, PointerEvent, UIEvent } from "react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { CSSProperties } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { useAtomValue } from "@effect/atom-react";
 import {
   defaultInstanceIdForDriver,
@@ -71,28 +65,6 @@ import { isElectron } from "../../env";
 import { buildHostedChannelSelectionUrl, type HostedAppChannel } from "../../hostedPairing";
 import { useCustomThemes } from "../../hooks/useCustomThemes";
 import { useTheme } from "../../hooks/useTheme";
-import { cn } from "../../lib/utils";
-import {
-  THEME_COLOR_ROLES,
-  THEME_FILE_VERSION,
-  createManagedThemeColors,
-  getDefaultThemeColors,
-  getThemeColorsForMode,
-  getThemeDefinition,
-  getThemeModes,
-  getThemePreferenceMode,
-  installCustomTheme,
-  parseThemeFile,
-  removeCustomTheme,
-  serializeThemeFile,
-  themePreferenceForMode,
-  updateCustomTheme,
-  type ThemeAppearance,
-  type ThemeColorRole,
-  type ThemeDefinition,
-  T3_CHAT_THEME,
-  T3_GROVE_THEME,
-} from "../../themePalette";
 import { usePrimarySettings, useUpdatePrimarySettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import { useDesktopUpdateState } from "../../state/desktopUpdate";
@@ -116,15 +88,6 @@ import { useProjects } from "../../state/entities";
 import { useArchivedThreadSnapshots } from "../../lib/archivedThreadsState";
 import { formatRelativeTimeLabel, getRelativeTimeState } from "../../timestampFormat";
 import { Button } from "../ui/button";
-import {
-  AlertDialog,
-  AlertDialogClose,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogPopup,
-  AlertDialogTitle,
-} from "../ui/alert-dialog";
 import {
   Dialog,
   DialogDescription,
@@ -135,7 +98,6 @@ import {
   DialogTitle,
 } from "../ui/dialog";
 import { DraftInput } from "../ui/draft-input";
-import { Input } from "../ui/input";
 import {
   NumberField,
   NumberFieldDecrement,
@@ -143,12 +105,12 @@ import {
   NumberFieldIncrement,
   NumberFieldInput,
 } from "../ui/number-field";
-import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
 import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
 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,
@@ -976,1543 +938,6 @@ function BackgroundActivityAdvancedDialog({
   );
 }
 
-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 /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(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,
-  );
-}
-
-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(() => {
-    const nextHsv = themeHexToHsv(normalizedValue);
-    setHsv(nextHsv);
-    setHexDraft(normalizedValue);
-    setRgbDraft(themeRgbValue(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>
-  );
-}
-
-function ThemeColorField({
-  role,
-  value,
-  onChange,
-  label: customLabel,
-}: {
-  role: ThemeColorRole;
-  value: string;
-  onChange: (value: string) => void;
-  label?: string;
-}) {
-  const label = customLabel ?? getThemeRoleLabel(role);
-  const isColorValue = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(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={onChange} 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(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(false);
-      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;
-
-      setSimpleColorsDirtyByAppearance((current) => ({
-        ...current,
-        [activeAppearance]: true,
-      }));
-      setColorsByAppearance((current) => ({
-        ...current,
-        [activeAppearance]: getManagedEditorColors(activeAppearance, current[activeAppearance]),
-      }));
-    },
-    [activeAppearance],
-  );
-
-  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";
-      const colorsForSave = !isAdvanced
-        ? {
-            light:
-              !isEditing || simpleColorsDirtyByAppearance.light
-                ? getManagedEditorColors("light", colorsByAppearance.light)
-                : colorsByAppearance.light,
-            dark:
-              !isEditing || 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={(value) => updateColor(role, value)}
-                        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={(value) => updateColor(role, value)}
-                        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={(value) => updateColor(role, value)}
-                        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={(value) => updateColor(role, value)}
-                      role={role}
-                      label={role === "canvas" ? "Background tint" : "Accent color"}
-                      value={colorsByAppearance[activeAppearance][role]}
-                    />
-                  ))}
-                </div>
-              </>
-            )}
-          </div>
-
-          {error ? (
-            <div
-              aria-live="polite"
-              className="rounded-lg border border-destructive/30 bg-destructive/8 px-3 py-2 text-sm text-destructive-foreground"
-            >
-              {error}
-            </div>
-          ) : 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 ? (
-            <div
-              aria-live="polite"
-              className="rounded-lg border border-destructive/30 bg-destructive/8 px-3 py-2 text-sm text-destructive-foreground"
-            >
-              {error}
-            </div>
-          ) : 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 (
-    <div
-      className={cn(
-        "cursor-pointer overflow-hidden rounded-xl border border-border/70 bg-card/60 outline-none transition-colors hover:bg-accent/10 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
-        isActive && "bg-accent/30",
-      )}
-      aria-label={`${theme.label} theme${isActive ? ", currently active" : ""}`}
-      aria-pressed={isActive}
-      data-theme-library-card={theme.id}
-      onClick={onUse}
-      onKeyDown={(event) => {
-        if (event.target !== event.currentTarget) return;
-        if (event.key !== "Enter" && event.key !== " ") return;
-        event.preventDefault();
-        onUse();
-      }}
-      role="button"
-      style={isActive ? { boxShadow: "inset 0 0 0 1px var(--ring)" } : undefined}
-      tabIndex={0}
-    >
-      <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">
-            <p className="truncate text-sm font-medium text-foreground">{theme.label}</p>
-            {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-primary"
-                onClick={(event) => {
-                  event.stopPropagation();
-                  onRemove();
-                }}
-              >
-                <Trash2Icon />
-              </Button>
-            ) : null}
-          </div>
-        ) : null}
-      </div>
-    </div>
-  );
-}
-
-function ThemeLibrary({
-  theme,
-  setTheme,
-  followSystem,
-  setFollowSystem,
-  customThemes,
-  initialAppearance,
-  refreshTheme,
-}: {
-  theme: string;
-  setTheme: (theme: string) => void;
-  followSystem: boolean;
-  setFollowSystem: (followSystem: boolean) => void;
-  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);
-  const activeTheme = getThemeDefinition(theme);
-  const standardThemes = getStandardThemeCards();
-  const maintainerThemes = [T3_CHAT_THEME, T3_GROVE_THEME];
-
-  const handleFollowSystemChange = useCallback(
-    (checked: boolean) => {
-      setFollowSystem(checked);
-      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;
-    if (getThemeDefinition(theme)?.id === themeToRemove.id) {
-      setTheme(followSystem ? "system" : initialAppearance);
-    }
-    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 “{themeToRemove?.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 onClick={handleConfirmRemoveTheme}>Remove theme</Button>
-          </AlertDialogFooter>
-        </AlertDialogPopup>
-      </AlertDialog>
-    </div>
-  );
-}
-
 export function AppearanceSettingsPanel() {
   const { theme, setTheme, setFollowSystem, refreshTheme, followSystem, resolvedTheme } =
     useTheme();
diff --git a/apps/web/src/components/settings/ThemeSettings.tsx b/apps/web/src/components/settings/ThemeSettings.tsx
new file mode 100644
index 00000000000..92e6c705cac
--- /dev/null
+++ b/apps/web/src/components/settings/ThemeSettings.tsx
@@ -0,0 +1,1640 @@
+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) => void;
+  followSystem: boolean;
+  setFollowSystem: (followSystem: boolean) => void;
+  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) => {
+      setFollowSystem(checked);
+      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;
+    if (getThemeDefinition(theme)?.id === themeToRemove.id) {
+      setTheme(followSystem ? "system" : initialAppearance);
+    }
+    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 b6606fe047c..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-update-surface text-update group-has-[button.provider-update-main:hover]/provider-update:bg-update/12",
+    "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/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index e7d97211f48..3cd8f517ec7 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -65,11 +65,13 @@ export const isDesktopThemeSyncError = Schema.is(DesktopThemeSyncError);
 
 let listeners: Array<() => void> = [];
 let lastSnapshot: ThemeSnapshot | 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();
 }
 
@@ -293,6 +295,10 @@ 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 followSystem = readStoredFollowSystem(theme);
   const systemDark = followSystem ? getSystemDark() : false;
@@ -314,42 +320,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 = () => {
-    const storedTheme = getStored();
-    if (readStoredFollowSystem(storedTheme)) applyTheme(storedTheme, 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();
-    } 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();
-    }
-  };
-  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;
+    }
   };
 }
 
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 7cac00aaed0..3509590aa45 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -889,7 +889,7 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --message-foreground: var(--foreground);
   --message-action: var(--primary);
   --message-action-foreground: var(--primary-foreground);
-  --message-action-hover: var(--primary);
+  --message-action-hover: color-mix(in srgb, var(--primary) 90%, var(--background));
   --accent: var(--color-zinc-100);
   --accent-foreground: var(--color-zinc-900);
   --error: var(--color-red-500);
@@ -955,7 +955,7 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
     --message-foreground: var(--foreground);
     --message-action: var(--primary);
     --message-action-foreground: var(--primary-foreground);
-    --message-action-hover: var(--primary);
+    --message-action-hover: color-mix(in srgb, var(--primary) 90%, var(--background));
     --accent: --alpha(var(--color-white) / 4%);
     --accent-foreground: var(--color-neutral-100);
     --error: color-mix(in srgb, var(--color-red-500) 90%, var(--color-white));
diff --git a/apps/web/src/themeBoot.test.ts b/apps/web/src/themeBoot.test.ts
new file mode 100644
index 00000000000..02059730aaa
--- /dev/null
+++ b/apps/web/src/themeBoot.test.ts
@@ -0,0 +1,242 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+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 html = readFileSync(new URL("../index.html", import.meta.url), "utf8");
+  const match = html.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,
+    querySelector: (selector: string) => (selector === 'meta[name="theme-color"]' ? meta : null),
+  };
+  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: "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
index 66ad3498798..1bc399064f2 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -4,6 +4,8 @@ import {
   getThemeColorsForMode,
   getThemeDefinition,
   getThemeModes,
+  getThemePreferenceMode,
+  isKnownThemePreference,
   getCustomThemes,
   invalidateCustomThemes,
   installCustomTheme,
@@ -16,7 +18,6 @@ import {
   T3_CHAT_THEME,
   T3_GROVE_THEME,
   themePreferenceForMode,
-  themePreferenceForSystem,
   updateCustomTheme,
   CUSTOM_THEMES_STORAGE_KEY,
   createManagedThemeColors,
@@ -130,7 +131,6 @@ describe("theme files", () => {
       text: "#eef5ff",
     });
     expect(themePreferenceForMode(theme, "dark")).toBe("aurora:dark");
-    expect(themePreferenceForSystem(theme)).toBe("aurora:system");
     expect(isThemeFollowingSystem("aurora:system")).toBe(true);
     expect(isThemeFollowingSystem("aurora:dark")).toBe(false);
     expect(getThemeModes(T3_CHAT_THEME)).toEqual(["light"]);
@@ -248,3 +248,63 @@ describe("theme files", () => {
     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
index ba02abaa6d7..c15dd16ad0f 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -68,6 +68,7 @@ export const THEME_COLOR_ROLES = [
 ] 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>>;
@@ -111,7 +112,7 @@ function isThemeAppearance(value: unknown): value is ThemeAppearance {
   return value === "light" || value === "dark";
 }
 
-function isThemeColor(value: unknown): value is string {
+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)
@@ -126,32 +127,35 @@ function isThemeLabel(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0 && value.trim().length <= 48;
 }
 
-function getThemeFallbackColors(appearance: ThemeAppearance): ThemeColors {
-  return appearance === "dark" ? DEFAULT_DARK_THEME_COLORS : T3_CHAT_THEME.colors;
-}
-
 function parseStoredThemeColors(value: unknown, appearance: ThemeAppearance): ThemeColors | null {
   if (!isRecord(value)) return null;
 
   const colors: Partial<Record<ThemeColorRole, string>> = {
-    ...getThemeFallbackColors(appearance),
+    ...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_ROLES as ReadonlyArray<string>).includes(role) || !isThemeColor(color)) {
-      return null;
+    if (THEME_COLOR_ROLE_SET.has(role) && isThemeColor(color)) {
+      colors[role as ThemeColorRole] = color;
     }
-    colors[role as ThemeColorRole] = color;
   }
   return colors as ThemeColors;
 }
 
-function parseStoredThemeVariants(value: unknown): ThemeVariants | null | undefined {
+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;
@@ -165,7 +169,7 @@ function parseStoredTheme(value: unknown): ThemeDefinition | 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);
+  const variants = parseStoredThemeVariants(value.variants, value.appearance);
   if (value.variants !== undefined && variants === null) return null;
 
   return {
@@ -606,6 +610,8 @@ export function createManagedThemeColors(
   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
@@ -644,14 +650,8 @@ export function createManagedThemeColors(
     messageAction: themeRgbToHexColor(accent),
     messageActionForeground: themeRgbToHexColor(accentForeground),
     messageActionHover: themeRgbToHexColor(messageActionHover),
-    codeBackground: themeRgbToHexColor(
-      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.025),
-    ),
-    codeForeground: themeRgbToHexColor(
-      readableThemeForeground(
-        mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.025),
-      ),
-    ),
+    codeBackground: themeRgbToHexColor(codeBackground),
+    codeForeground: themeRgbToHexColor(readableThemeForeground(codeBackground)),
     sidebar: themeRgbToHexColor(sidebar),
     sidebarForeground: themeRgbToHexColor(readableThemeForeground(sidebar)),
     sidebarMutedForeground: themeRgbToHexColor(readableThemeText(sidebar, text, 0.2, 4.5)),
@@ -664,12 +664,8 @@ export function createManagedThemeColors(
     sidebarBorder: themeRgbToHexColor(
       mixThemeRgbColors(sidebar, text, appearance === "dark" ? 0.35 : 0.12),
     ),
-    terminalBackground: themeRgbToHexColor(
-      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.2 : 0.035),
-    ),
-    terminalForeground: themeRgbToHexColor(
-      readableThemeForeground(mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.2 : 0.035)),
-    ),
+    terminalBackground: themeRgbToHexColor(terminalBackground),
+    terminalForeground: themeRgbToHexColor(readableThemeForeground(terminalBackground)),
     terminalCursor: themeRgbToHexColor(accent),
     terminalSelection: themeRgbToHexColor(
       mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.35 : 0.18),
@@ -748,14 +744,6 @@ export function themePreferenceForMode(
     : `${definition.id}${THEME_PREFERENCE_SEPARATOR}${mode}`;
 }
 
-export function themePreferenceForSystem(
-  theme: ThemePreference | ThemeDefinition,
-): ThemePreference {
-  const definition = typeof theme === "string" ? getThemeDefinition(theme) : theme;
-  if (!definition) return "system";
-  return `${definition.id}${THEME_PREFERENCE_SEPARATOR}system`;
-}
-
 export function isThemeFollowingSystem(theme: ThemePreference): boolean {
   if (theme === "system") return true;
   return splitThemePreference(theme).mode === "system";
@@ -837,7 +825,7 @@ function parseThemeColorOverrides(value: unknown): ThemeColorOverrides {
 
   const overrides: Partial<Record<ThemeColorRole, string>> = {};
   for (const [role, color] of Object.entries(value)) {
-    if (!(THEME_COLOR_ROLES as ReadonlyArray<string>).includes(role)) {
+    if (!THEME_COLOR_ROLE_SET.has(role)) {
       throw new Error(`"${role}" is not a supported theme color role.`);
     }
     if (!isThemeColor(color)) {
@@ -1010,12 +998,7 @@ export function resolveThemeAppearance(
       ? definition.appearance
       : systemAppearance;
   }
-  if (theme === "dark" || theme === "light") return theme;
-  const definition = getThemeDefinition(theme);
-  const mode = getThemePreferenceMode(theme);
-  if (definition && mode) return mode;
-  if (definition) return definition.appearance;
-  return "light";
+  return getThemePreferenceMode(theme) ?? "light";
 }
 
 export function resolveDesktopTheme(
@@ -1028,13 +1011,7 @@ export function resolveDesktopTheme(
     const hasDarkMode = definition && getThemeColorsForMode(definition, "dark") !== null;
     return definition && (!hasLightMode || !hasDarkMode) ? definition.appearance : "system";
   }
-  if (theme === "dark") return "dark";
-  if (theme === "light") return "light";
-  const definition = getThemeDefinition(theme);
-  const mode = getThemePreferenceMode(theme);
-  if (definition && mode) return mode;
-  if (definition) return definition.appearance;
-  return "system";
+  return getThemePreferenceMode(theme) ?? "system";
 }
 
 export function isKnownThemePreference(theme: string): boolean {

From a096aba69a8ebe61feb4e2c84947c6fd485894c8 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 10:57:45 +0200
Subject: [PATCH 21/25] test(web): load the boot script via a raw import

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/themeBoot.test.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/themeBoot.test.ts b/apps/web/src/themeBoot.test.ts
index 02059730aaa..5dca813aa15 100644
--- a/apps/web/src/themeBoot.test.ts
+++ b/apps/web/src/themeBoot.test.ts
@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
 import { describe, expect, it, vi } from "vite-plus/test";
 
+import indexHtml from "../index.html?raw";
 import {
   CUSTOM_THEMES_STORAGE_KEY,
   invalidateCustomThemes,
@@ -13,8 +13,7 @@ import {
 const THEME_STORAGE_KEY = "t3code:theme";
 
 const bootScript = (() => {
-  const html = readFileSync(new URL("../index.html", import.meta.url), "utf8");
-  const match = html.match(/<script>([\s\S]*?)<\/script>/);
+  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];
 })();

From e1c653abf40394d417821a00f24e18bc5c9b70e6 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 11:08:34 +0200
Subject: [PATCH 22/25] fix(web): address Bugbot review on theme storage
 failure paths

- The boot script no longer follows the OS for a `:system`-suffixed
  preference when follow-system is explicitly off, matching the runtime;
  covered by two new parity cases.
- setTheme/setFollowSystem report write success, so the follow-system
  toggle leaves the theme preference untouched when its write fails, and
  removing the active theme keeps it installed when the selection cannot
  be moved off it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/index.html                             |  5 ++++-
 .../src/components/settings/ThemeSettings.tsx   | 17 ++++++++++++-----
 apps/web/src/hooks/useTheme.ts                  | 14 ++++++++------
 apps/web/src/themeBoot.test.ts                  | 17 +++++++++++++++++
 4 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/apps/web/index.html b/apps/web/index.html
index b781abda550..ada92968ab1 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -157,9 +157,12 @@
           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 || preference.mode === "system"
+            : followSystem
               ? themeModes.includes(systemMode)
                 ? systemMode
                 : baseAppearance
diff --git a/apps/web/src/components/settings/ThemeSettings.tsx b/apps/web/src/components/settings/ThemeSettings.tsx
index 92e6c705cac..4370e6a1d14 100644
--- a/apps/web/src/components/settings/ThemeSettings.tsx
+++ b/apps/web/src/components/settings/ThemeSettings.tsx
@@ -1398,9 +1398,9 @@ export function ThemeLibrary({
   refreshTheme,
 }: {
   theme: string;
-  setTheme: (theme: string) => void;
+  setTheme: (theme: string) => boolean;
   followSystem: boolean;
-  setFollowSystem: (followSystem: boolean) => void;
+  setFollowSystem: (followSystem: boolean) => boolean;
   customThemes: ReadonlyArray<ThemeDefinition>;
   initialAppearance: ThemeAppearance;
   refreshTheme: () => void;
@@ -1420,7 +1420,9 @@ export function ThemeLibrary({
 
   const handleFollowSystemChange = useCallback(
     (checked: boolean) => {
-      setFollowSystem(checked);
+      // 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")
@@ -1438,8 +1440,13 @@ export function ThemeLibrary({
 
   const handleConfirmRemoveTheme = useCallback(() => {
     if (!themeToRemove) return;
-    if (getThemeDefinition(theme)?.id === themeToRemove.id) {
-      setTheme(followSystem ? "system" : initialAppearance);
+    // 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);
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index 3cd8f517ec7..af5578b327e 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -380,8 +380,8 @@ export function useTheme() {
     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) {
@@ -399,14 +399,15 @@ export function useTheme() {
         theme: next,
         ...safeErrorLogAttributes(error),
       });
-      return;
+      return false;
     }
     applyTheme(next, true);
     emitChange();
+    return true;
   }, []);
 
-  const setFollowSystem = useCallback((nextFollowSystem: boolean) => {
-    if (typeof window === "undefined") return;
+  const setFollowSystem = useCallback((nextFollowSystem: boolean): boolean => {
+    if (typeof window === "undefined") return false;
     try {
       writeFollowSystemPreference(nextFollowSystem);
     } catch (cause) {
@@ -422,11 +423,12 @@ export function useTheme() {
         storageKey: error.storageKey,
         ...safeErrorLogAttributes(error),
       });
-      return;
+      return false;
     }
     themeStorageReadFailure = null;
     applyTheme(getStored(), true);
     emitChange();
+    return true;
   }, []);
 
   const refreshTheme = useCallback(() => {
diff --git a/apps/web/src/themeBoot.test.ts b/apps/web/src/themeBoot.test.ts
index 5dca813aa15..1cc5742fb67 100644
--- a/apps/web/src/themeBoot.test.ts
+++ b/apps/web/src/themeBoot.test.ts
@@ -184,6 +184,23 @@ describe("index.html boot script", () => {
       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" },

From 884aafe44f9501d9d556d9aa1c7accee0cf65cb8 Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 11:18:56 +0200
Subject: [PATCH 23/25] fix(web): update every theme-color meta with the
 resolved chrome color

The document ships light-media, dark-media, and plain theme-color metas;
the browser reads whichever matches the OS, so mutating only the first
element left themed chrome colors unapplied on a dark OS. Both the boot
script and syncBrowserChromeTheme now write the resolved color to every
matching meta.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/index.html            | 13 ++++++++++---
 apps/web/src/hooks/useTheme.ts | 13 ++++++++++++-
 apps/web/src/themeBoot.test.ts |  2 +-
 3 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/apps/web/index.html b/apps/web/index.html
index ada92968ab1..7b2bab57133 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -68,7 +68,14 @@
           "t3-grove",
           "t3-chat-dark",
         ];
-        const themeColorMeta = document.querySelector('meta[name="theme-color"]');
+        // 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" &&
@@ -242,7 +249,7 @@
               document.documentElement.style.setProperty(`--boot-${name}`, value);
             }
           }
-          themeColorMeta?.setAttribute("content", chromeColor);
+          setThemeColor(chromeColor);
         } catch {
           // Mirror the runtime's storage-failure fallback: follow the OS.
           let prefersDark = true;
@@ -256,7 +263,7 @@
           document.documentElement.classList.toggle("dark", prefersDark);
           const fallbackColor = prefersDark ? DARK_BACKGROUND : LIGHT_BACKGROUND;
           document.documentElement.style.backgroundColor = fallbackColor;
-          themeColorMeta?.setAttribute("content", fallbackColor);
+          setThemeColor(fallbackColor);
         }
       })();
     </script>
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index af5578b327e..de5c1674653 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -217,7 +217,18 @@ export function syncBrowserChromeTheme() {
 
   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) {
diff --git a/apps/web/src/themeBoot.test.ts b/apps/web/src/themeBoot.test.ts
index 1cc5742fb67..01195aaafe5 100644
--- a/apps/web/src/themeBoot.test.ts
+++ b/apps/web/src/themeBoot.test.ts
@@ -61,7 +61,7 @@ function runBootScript(options: {
   };
   const fakeDocument = {
     documentElement,
-    querySelector: (selector: string) => (selector === 'meta[name="theme-color"]' ? meta : null),
+    querySelectorAll: (selector: string) => (selector === 'meta[name="theme-color"]' ? [meta] : []),
   };
   const fakeWindow = {
     localStorage: {

From 46827f2c3cc4b77376d8b78e3c2328199e9b71af Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 11:30:23 +0200
Subject: [PATCH 24/25] chore: retrigger CI after GitHub 503 during checkout

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

From f52a34c9a6fa1aeb979b87ac4bae48dbf8b8c29d Mon Sep 17 00:00:00 2001
From: Wout Stiens <71498452+StiensWout@users.noreply.github.com>
Date: Mon, 3 Aug 2026 13:32:51 +0200
Subject: [PATCH 25/25] feat(web): anchor the T3 Chat theme to the real t3.chat
 palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Swap the light palette to t3.chat's actual tokens — #a84370 primary,
#db2777 ring, #501854 foreground, #faf5fa background, and its pink
surface family — for the deeper pink accents of the product. The boot
splash and managed-editor fallbacks follow, and a contrast guard test
keeps the key pairings readable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/index.html               |   8 +--
 apps/web/src/themePalette.test.ts |  12 ++++
 apps/web/src/themePalette.ts      | 102 +++++++++++++++---------------
 3 files changed, 68 insertions(+), 54 deletions(-)

diff --git a/apps/web/index.html b/apps/web/index.html
index 7b2bab57133..b608fd0bbff 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -15,7 +15,7 @@
       (() => {
         const LIGHT_BACKGROUND = "#ffffff";
         const DARK_BACKGROUND = "#161616";
-        const T3_CHAT_BACKGROUND = "#fffaff";
+        const T3_CHAT_BACKGROUND = "#faf5fa";
         const T3_CHAT_DARK_BACKGROUND = "#180f1b";
         const T3_GROVE_BACKGROUND = "#f4f8f5";
         const T3_GROVE_DARK_BACKGROUND = "#111f19";
@@ -33,9 +33,9 @@
             accent: "#818cf8",
           },
           t3Chat: {
-            background: "#fffaff",
-            foreground: "#5c205f",
-            accent: "#c52d7b",
+            background: "#faf5fa",
+            foreground: "#501854",
+            accent: "#a84370",
           },
           t3ChatDark: {
             background: "#180f1b",
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index 1bc399064f2..3ecd3001c66 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -144,6 +144,18 @@ describe("theme files", () => {
     });
   });
 
+  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"]);
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index c15dd16ad0f..771d14c18a1 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -282,58 +282,60 @@ function explicitThemeMode(theme: ThemePreference): ThemeAppearance | 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: "#fffaff",
-  chrome: "#f6e8f7",
-  surface: "#fffaff",
-  surfaceRaised: "#fff5fd",
-  surfaceOverlay: "#fffaff",
-  text: "#5c205f",
-  textMuted: "#98669a",
-  border: "#efc7eb",
-  input: "#e8b9e3",
-  focus: "#c52d7b",
-  accent: "#c52d7b",
-  accentForeground: "#fff8ff",
-  secondary: "#f9e8f8",
-  secondaryForeground: "#7e3a7f",
-  muted: "#f7eaf7",
-  mutedForeground: "#956a97",
-  placeholder: "#855386",
-  secondaryLabel: "#7e4f80",
-  iconMuted: "#855386",
-  error: "#b4235f",
-  errorForeground: "#8f1748",
-  errorSurface: "#fce3ec",
+  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: "#b12268",
-  updateForeground: "#7e245e",
-  updateSurface: "#f8e2f4",
-  accentSurface: "#f5dff3",
-  accentSurfaceForeground: "#713071",
-  messageSurface: "#f0d1ed",
-  messageForeground: "#5c205f",
-  messageAction: "#b12268",
-  messageActionForeground: "#fff8ff",
-  messageActionHover: "#c52d7b",
-  codeBackground: "#fff7fd",
-  codeForeground: "#5c205f",
-  sidebar: "#f2e2f4",
-  sidebarForeground: "#682a6b",
-  sidebarMutedForeground: "#a36ea1",
-  sidebarControlSurface: "#ebd2eb",
-  sidebarRowHover: "#f8eaf8",
-  sidebarRowActive: "#efd4ed",
-  sidebarRowSelected: "#f1d9ef",
-  sidebarBorder: "#edc0e8",
-  terminalBackground: "#fffaff",
-  terminalForeground: "#5c205f",
-  terminalCursor: "#c52d7b",
-  terminalSelection: "#f0c3eb",
-  terminalScrollbar: "#dfb0da",
-  terminalScrollbarHover: "#cd91c9",
+  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 = {
@@ -537,7 +539,7 @@ function readableThemeText(
 function managedThemeBackground(value: string, appearance: ThemeAppearance): ThemeRgbColor {
   const selected = parseThemeRgbColor(
     value,
-    appearance === "dark" ? { r: 24, g: 15, b: 27 } : { r: 255, g: 250, b: 255 },
+    appearance === "dark" ? { r: 24, g: 15, b: 27 } : { r: 250, g: 245, b: 250 },
   );
   const hsl = themeRgbToHsl(selected);
   return themeHslToRgb({
@@ -557,7 +559,7 @@ function managedThemeAccent(
   appearance: ThemeAppearance,
   background: ThemeRgbColor,
 ): ThemeRgbColor {
-  const selected = parseThemeRgbColor(value, { r: 197, g: 45, b: 123 });
+  const selected = parseThemeRgbColor(value, { r: 168, g: 67, b: 112 });
   const hsl = themeRgbToHsl(selected);
   const preferredLightness =
     appearance === "dark"