From eab19af2b462afe956bddfeae1e142f9add516f2 Mon Sep 17 00:00:00 2001
From: Jay1 <j-chiasson@outlook.com>
Date: Sun, 31 May 2026 18:38:55 -0400
Subject: [PATCH 1/6] web: add theme surface tokens

---
 apps/web/src/index.css                 | 38 +++++++++++--
 apps/web/src/theme/theme.logic.test.ts | 75 ++++++++++++++++++++++++++
 apps/web/src/theme/theme.logic.ts      | 47 ++++++++++++++++
 3 files changed, 157 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index a34e0703a..d0289ef7e 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -58,12 +58,12 @@
 
 @layer components {
   .sidebar-icon-button {
-    @apply items-center justify-center rounded-sm p-0.5 text-muted-foreground/60 transition-colors hover:text-foreground/82 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring;
-    background: transparent;
+    @apply items-center justify-center rounded-sm p-0.5 text-[var(--app-control-icon-fg,var(--muted-foreground))] transition-colors hover:text-[var(--app-control-icon-hover-fg,var(--foreground))] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[color:var(--app-state-focus,var(--ring))];
+    background: var(--app-control-icon-bg, transparent);
   }
 
   .sidebar-icon-button:hover {
-    background: var(--color-background-button-secondary-hover);
+    background: var(--app-control-icon-hover-bg, var(--color-background-button-secondary-hover));
   }
 
   /* Let the renderer switch between Codex-style translucent and opaque shells
@@ -234,10 +234,42 @@
   --app-surface-card: var(--card);
   --app-surface-card-header: var(--muted);
   --app-surface-composer: var(--card);
+  --app-surface-toolbar: var(--app-surface-topbar, var(--background));
+  --app-surface-toolbar-hover: var(--app-state-hover, var(--accent));
+  --app-surface-toolbar-active: var(--app-state-selected, var(--accent));
+  --app-surface-toolbar-border: var(--border);
   --app-state-hover: var(--accent);
   --app-state-selected: var(--sidebar-accent-active);
   --app-state-selected-border: var(--primary);
   --app-state-focus: var(--ring);
+  --app-text-metadata: var(--muted-foreground);
+  --app-text-metadata-strong: var(--foreground);
+  --app-control-icon-fg: var(--app-text-metadata, var(--muted-foreground));
+  --app-control-icon-hover-fg: var(--app-text-metadata-strong, var(--foreground));
+  --app-control-icon-bg: transparent;
+  --app-control-icon-hover-bg: var(--app-surface-toolbar-hover, var(--accent));
+  --app-control-icon-border: transparent;
+  --app-chrome-control-bg: var(
+    --color-background-control,
+    var(--app-surface-toolbar-hover, var(--accent))
+  );
+  --app-chrome-control-border: var(--app-surface-toolbar-border, var(--border));
+  --app-chrome-control-fg: var(--color-text-foreground-secondary, var(--foreground));
+  --app-chrome-control-hover-bg: var(
+    --color-background-button-secondary-hover,
+    var(--app-surface-toolbar-active, var(--accent))
+  );
+  --app-chrome-control-hover-fg: var(--color-text-foreground, var(--foreground));
+  --app-chrome-control-active-bg: var(
+    --color-background-button-secondary-active,
+    var(--app-state-selected, var(--accent))
+  );
+  --app-metadata-fg: var(--app-text-metadata-strong, var(--foreground));
+  --app-metadata-muted-fg: var(--app-text-metadata, var(--muted-foreground));
+  --app-work-row-bg: var(--app-surface-card, var(--card));
+  --app-work-row-hover-bg: var(--app-surface-card-header, var(--muted));
+  --app-work-row-border: var(--border);
+  --app-work-row-icon: var(--app-text-metadata, var(--muted-foreground));
   --app-status-error-bg: var(--destructive);
   --app-status-error-border: var(--destructive);
   --app-status-error-dot: var(--destructive-foreground);
diff --git a/apps/web/src/theme/theme.logic.test.ts b/apps/web/src/theme/theme.logic.test.ts
index b168faaf3..faaa16b1b 100644
--- a/apps/web/src/theme/theme.logic.test.ts
+++ b/apps/web/src/theme/theme.logic.test.ts
@@ -32,10 +32,33 @@ const REQUIRED_APP_DEPTH_TOKENS = [
   "--app-surface-card",
   "--app-surface-card-header",
   "--app-surface-composer",
+  "--app-surface-toolbar",
+  "--app-surface-toolbar-hover",
+  "--app-surface-toolbar-active",
+  "--app-surface-toolbar-border",
+  "--app-chrome-control-bg",
+  "--app-chrome-control-border",
+  "--app-chrome-control-fg",
+  "--app-chrome-control-hover-bg",
+  "--app-chrome-control-hover-fg",
+  "--app-chrome-control-active-bg",
   "--app-state-hover",
   "--app-state-selected",
   "--app-state-selected-border",
   "--app-state-focus",
+  "--app-metadata-fg",
+  "--app-metadata-muted-fg",
+  "--app-text-metadata",
+  "--app-text-metadata-strong",
+  "--app-control-icon-fg",
+  "--app-control-icon-hover-fg",
+  "--app-control-icon-bg",
+  "--app-control-icon-hover-bg",
+  "--app-control-icon-border",
+  "--app-work-row-bg",
+  "--app-work-row-hover-bg",
+  "--app-work-row-border",
+  "--app-work-row-icon",
   "--app-status-error-bg",
   "--app-status-error-border",
   "--app-status-error-dot",
@@ -441,6 +464,33 @@ describe("buildThemeCssVariables", () => {
     expect(tokens.derived.textButtonPrimary).not.toBe(tokens.derived.buttonPrimaryBackground);
   });
 
+  it("derives semantic chrome control tokens from non-palette theme math", () => {
+    const importedTheme = parseThemeShareString(PROVIDED_THEME_STRING);
+    const pack = {
+      codeThemeId: importedTheme.codeThemeId,
+      theme: importedTheme.theme,
+    };
+    const tokens = buildResolvedThemeTokens(pack, importedTheme.variant);
+    const cssVariables = buildThemeCssVariables(pack, importedTheme.variant);
+
+    expect(cssVariables.variables["--app-chrome-control-bg"]).toBe(
+      tokens.derived.controlBackground,
+    );
+    expect(cssVariables.variables["--app-chrome-control-border"]).toBe(tokens.derived.borderLight);
+    expect(cssVariables.variables["--app-chrome-control-fg"]).toBe(
+      tokens.derived.textForegroundSecondary,
+    );
+    expect(cssVariables.variables["--app-chrome-control-hover-bg"]).toBe(
+      tokens.derived.buttonSecondaryBackgroundHover,
+    );
+    expect(cssVariables.variables["--app-chrome-control-hover-fg"]).toBe(
+      tokens.derived.textForeground,
+    );
+    expect(cssVariables.variables["--app-chrome-control-active-bg"]).toBe(
+      tokens.derived.buttonSecondaryBackgroundActive,
+    );
+  });
+
   it("emits Catppuccin Mocha app-depth tokens from official palette layers", () => {
     const cssVariables = buildThemeCssVariables(
       {
@@ -455,6 +505,31 @@ describe("buildThemeCssVariables", () => {
     expect(cssVariables.variables["--app-surface-topbar"]).toBe("#181825");
     expect(cssVariables.variables["--app-surface-card"]).toBe("#1e1e2e");
     expect(cssVariables.variables["--app-surface-card-header"]).toBe("#313244");
+    expect(cssVariables.variables["--app-surface-toolbar"]).toBe("#181825");
+    expect(cssVariables.variables["--app-surface-toolbar-hover"]).toBe("#313244");
+    expect(cssVariables.variables["--app-surface-toolbar-active"]).toBe("#45475a");
+    expect(cssVariables.variables["--app-surface-toolbar-border"]).toBe("#45475a");
+    expect(cssVariables.variables["--app-chrome-control-bg"]).toBe("#313244");
+    expect(cssVariables.variables["--app-chrome-control-border"]).toBe("#45475a");
+    expect(cssVariables.variables["--app-chrome-control-fg"]).toBe("#cdd6f4");
+    expect(cssVariables.variables["--app-chrome-control-hover-bg"]).toBe("#45475a");
+    expect(cssVariables.variables["--app-chrome-control-hover-fg"]).toBe("#cdd6f4");
+    expect(cssVariables.variables["--app-chrome-control-active-bg"]).toBe(
+      "rgba(203, 166, 247, 0.14)",
+    );
+    expect(cssVariables.variables["--app-metadata-fg"]).toBe("rgba(205, 214, 244, 0.86)");
+    expect(cssVariables.variables["--app-metadata-muted-fg"]).toBe("rgba(205, 214, 244, 0.62)");
+    expect(cssVariables.variables["--app-text-metadata"]).toBe("rgba(205, 214, 244, 0.62)");
+    expect(cssVariables.variables["--app-text-metadata-strong"]).toBe("rgba(205, 214, 244, 0.86)");
+    expect(cssVariables.variables["--app-control-icon-fg"]).toBe("rgba(205, 214, 244, 0.62)");
+    expect(cssVariables.variables["--app-control-icon-hover-fg"]).toBe("rgba(205, 214, 244, 0.86)");
+    expect(cssVariables.variables["--app-control-icon-bg"]).toBe("transparent");
+    expect(cssVariables.variables["--app-control-icon-hover-bg"]).toBe("#313244");
+    expect(cssVariables.variables["--app-control-icon-border"]).toBe("rgba(69, 71, 90, 0.55)");
+    expect(cssVariables.variables["--app-work-row-bg"]).toBe("rgba(30, 30, 46, 0.82)");
+    expect(cssVariables.variables["--app-work-row-hover-bg"]).toBe("#313244");
+    expect(cssVariables.variables["--app-work-row-border"]).toBe("rgba(69, 71, 90, 0.52)");
+    expect(cssVariables.variables["--app-work-row-icon"]).toBe("rgba(205, 214, 244, 0.48)");
     expect(cssVariables.variables["--app-state-hover"]).toBe("#313244");
     expect(cssVariables.variables["--app-state-selected"]).toBe("rgba(203, 166, 247, 0.14)");
     expect(cssVariables.variables["--app-state-selected-border"]).toBe("#cba6f7");
diff --git a/apps/web/src/theme/theme.logic.ts b/apps/web/src/theme/theme.logic.ts
index 853b6d6ac..455506d97 100644
--- a/apps/web/src/theme/theme.logic.ts
+++ b/apps/web/src/theme/theme.logic.ts
@@ -982,10 +982,25 @@ function buildAppDepthVariables(
       "--app-scroll-button-hover-fg": palette.mauve,
       "--app-scrollbar-thumb": formatRgba(surface1, variant === "dark" ? 0.72 : 0.64),
       "--app-scrollbar-thumb-hover": formatRgba(surface1, variant === "dark" ? 0.92 : 0.82),
+      "--app-chrome-control-bg": palette.surface0,
+      "--app-chrome-control-border": palette.surface1,
+      "--app-chrome-control-fg": pack.theme.ink,
+      "--app-chrome-control-hover-bg": palette.surface1,
+      "--app-chrome-control-hover-fg": pack.theme.ink,
+      "--app-chrome-control-active-bg": formatRgba(accent, variant === "dark" ? 0.14 : 0.12),
+      "--app-control-icon-bg": "transparent",
+      "--app-control-icon-border": formatRgba(surface1, variant === "dark" ? 0.55 : 0.46),
+      "--app-control-icon-fg": formatRgba(parseHexColor(pack.theme.ink), 0.62),
+      "--app-control-icon-hover-bg": palette.surface0,
+      "--app-control-icon-hover-fg": formatRgba(parseHexColor(pack.theme.ink), 0.86),
       "--app-state-focus": palette.blue,
       "--app-state-hover": palette.surface0,
       "--app-state-selected": formatRgba(accent, variant === "dark" ? 0.14 : 0.12),
       "--app-state-selected-border": pack.theme.accent,
+      "--app-metadata-fg": formatRgba(parseHexColor(pack.theme.ink), 0.86),
+      "--app-metadata-muted-fg": formatRgba(parseHexColor(pack.theme.ink), 0.62),
+      "--app-text-metadata": formatRgba(parseHexColor(pack.theme.ink), 0.62),
+      "--app-text-metadata-strong": formatRgba(parseHexColor(pack.theme.ink), 0.86),
       "--app-status-error-bg": formatRgba(diffRemoved, variant === "dark" ? 0.14 : 0.1),
       "--app-status-error-border": formatRgba(diffRemoved, variant === "dark" ? 0.42 : 0.32),
       ...buildStatusVariables(
@@ -1016,6 +1031,10 @@ function buildAppDepthVariables(
       "--app-surface-panel": variant === "dark" ? palette.mantle : "#ffffff",
       "--app-surface-sidebar": variant === "dark" ? palette.mantle : palette.mantle,
       "--app-surface-topbar": variant === "dark" ? palette.mantle : palette.mantle,
+      "--app-surface-toolbar": variant === "dark" ? palette.mantle : palette.mantle,
+      "--app-surface-toolbar-active": palette.surface1,
+      "--app-surface-toolbar-border": palette.surface1,
+      "--app-surface-toolbar-hover": palette.surface0,
       ...buildSubagentAccentVariables([
         palette.red,
         palette.green,
@@ -1032,6 +1051,10 @@ function buildAppDepthVariables(
       "--app-terminal-search-match-bg": palette.surface1,
       "--app-terminal-search-match-border": palette.blue,
       "--app-terminal-search-match-overview": palette.peach,
+      "--app-work-row-bg": formatRgba(parseHexColor(palette.base), 0.82),
+      "--app-work-row-border": formatRgba(surface1, 0.52),
+      "--app-work-row-hover-bg": palette.surface0,
+      "--app-work-row-icon": formatRgba(parseHexColor(pack.theme.ink), 0.48),
       "--app-wordmark-prefix": APP_WORDMARK_PREFIX_BLOOD_RED,
     };
   }
@@ -1115,6 +1138,7 @@ function buildProfileAppDepthVariables(
   const accent = parseHexColor(pack.theme.accent);
   const diffRemoved = parseHexColor(pack.theme.semanticColors.diffRemoved);
   const diffAdded = parseHexColor(pack.theme.semanticColors.diffAdded);
+  const ink = parseHexColor(pack.theme.ink);
   const warningColor = profile.warning ?? (variant === "dark" ? "#f5b44a" : "#d97706");
   const warning = parseHexColor(warningColor);
   const toneLift = getThemeDepthToneLift(profile.tone, variant);
@@ -1180,10 +1204,25 @@ function buildProfileAppDepthVariables(
     "--app-scroll-button-hover-fg": pack.theme.accent,
     "--app-scrollbar-thumb": resolvedTokens.derived.iconTertiary,
     "--app-scrollbar-thumb-hover": resolvedTokens.derived.iconSecondary,
+    "--app-chrome-control-bg": resolvedTokens.derived.controlBackground,
+    "--app-chrome-control-border": resolvedTokens.derived.borderLight,
+    "--app-chrome-control-fg": resolvedTokens.derived.textForegroundSecondary,
+    "--app-chrome-control-hover-bg": resolvedTokens.derived.buttonSecondaryBackgroundHover,
+    "--app-chrome-control-hover-fg": resolvedTokens.derived.textForeground,
+    "--app-chrome-control-active-bg": resolvedTokens.derived.buttonSecondaryBackgroundActive,
+    "--app-control-icon-bg": "transparent",
+    "--app-control-icon-border": resolvedTokens.derived.borderLight,
+    "--app-control-icon-fg": resolvedTokens.derived.textForegroundTertiary,
+    "--app-control-icon-hover-bg": resolvedTokens.derived.buttonSecondaryBackgroundHover,
+    "--app-control-icon-hover-fg": resolvedTokens.derived.textForeground,
     "--app-state-focus": resolvedTokens.derived.borderFocus,
     "--app-state-hover": resolvedTokens.derived.buttonSecondaryBackgroundHover,
     "--app-state-selected": formatRgba(accent, selectedAlpha),
     "--app-state-selected-border": pack.theme.accent,
+    "--app-metadata-fg": formatRgba(ink, variant === "dark" ? 0.86 : 0.88),
+    "--app-metadata-muted-fg": formatRgba(ink, variant === "dark" ? 0.62 : 0.66),
+    "--app-text-metadata": formatRgba(ink, variant === "dark" ? 0.62 : 0.66),
+    "--app-text-metadata-strong": formatRgba(ink, variant === "dark" ? 0.86 : 0.88),
     "--app-status-error-bg": formatRgba(diffRemoved, variant === "dark" ? 0.12 : 0.08),
     "--app-status-error-border": formatRgba(diffRemoved, variant === "dark" ? 0.36 : 0.28),
     ...buildStatusVariables(
@@ -1222,12 +1261,20 @@ function buildProfileAppDepthVariables(
     "--app-surface-panel": panel,
     "--app-surface-sidebar": sidebar,
     "--app-surface-topbar": topbar,
+    "--app-surface-toolbar": topbar,
+    "--app-surface-toolbar-active": resolvedTokens.derived.buttonSecondaryBackgroundActive,
+    "--app-surface-toolbar-border": resolvedTokens.derived.border,
+    "--app-surface-toolbar-hover": resolvedTokens.derived.buttonSecondaryBackgroundHover,
     "--app-terminal-search-active-match-bg": activeSearchBackground,
     "--app-terminal-search-active-match-border": warningColor,
     "--app-terminal-search-active-match-overview": warningColor,
     "--app-terminal-search-match-bg": cardHeader,
     "--app-terminal-search-match-border": pack.theme.accent,
     "--app-terminal-search-match-overview": pack.theme.semanticColors.diffAdded,
+    "--app-work-row-bg": formatRgba(parseHexColor(panel), variant === "dark" ? 0.82 : 0.88),
+    "--app-work-row-border": resolvedTokens.derived.borderLight,
+    "--app-work-row-hover-bg": resolvedTokens.derived.elevatedSecondary,
+    "--app-work-row-icon": formatRgba(ink, variant === "dark" ? 0.48 : 0.52),
     "--app-wordmark-prefix": APP_WORDMARK_PREFIX_BLOOD_RED,
   };
 }

From fc7a65f91de3ee035e48cedd8d326b2a5b6b07e2 Mon Sep 17 00:00:00 2001
From: Jay1 <j-chiasson@outlook.com>
Date: Sun, 31 May 2026 18:39:02 -0400
Subject: [PATCH 2/6] web: theme app chrome controls

---
 apps/web/src/components/BranchToolbar.tsx     | 55 +++++++++----------
 apps/web/src/components/ChatView.tsx          | 12 ++--
 apps/web/src/components/GitActionsControl.tsx |  4 +-
 apps/web/src/components/chat/ChatHeader.tsx   |  6 +-
 4 files changed, 38 insertions(+), 39 deletions(-)

diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx
index 5478ce9cd..ca14bfecb 100644
--- a/apps/web/src/components/BranchToolbar.tsx
+++ b/apps/web/src/components/BranchToolbar.tsx
@@ -77,16 +77,11 @@ export function RuntimeUsageControls({
   className,
 }: RuntimeUsageControlsProps) {
   return (
-    <div
-      className={cn(
-        "flex items-center gap-1.5 text-[var(--color-text-foreground-secondary)]",
-        className,
-      )}
-    >
+    <div className={cn("flex items-center gap-1.5 text-(--app-metadata-muted-fg)", className)}>
       {runtimeMode && onRuntimeModeChange ? (
         <button
           type="button"
-          className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[length:var(--app-font-size-ui-xs,10px)] font-normal transition-colors hover:text-[var(--color-text-foreground)]"
+          className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[length:var(--app-font-size-ui-xs,10px)] font-normal transition-colors hover:text-(--app-metadata-fg)"
           onClick={() =>
             onRuntimeModeChange(runtimeMode === "full-access" ? "approval-required" : "full-access")
           }
@@ -284,7 +279,7 @@ export default function BranchToolbar({
       <div className="flex items-center gap-2">
         {showEnvPicker ? (
           <Popover open={envPickerOpen} onOpenChange={setEnvPickerOpen}>
-            <PopoverTrigger className="inline-flex cursor-pointer items-center gap-1 rounded-md px-2 py-1 text-[length:var(--app-font-size-ui-xs,10px)] font-normal text-[var(--color-text-foreground-secondary)] transition-colors hover:bg-[var(--color-background-elevated-secondary)] hover:text-[var(--color-text-foreground)]">
+            <PopoverTrigger className="inline-flex cursor-pointer items-center gap-1 rounded-md px-2 py-1 text-[length:var(--app-font-size-ui-xs,10px)] font-normal text-(--app-metadata-muted-fg) transition-colors hover:bg-(--app-chrome-control-hover-bg) hover:text-(--app-metadata-fg)">
               {environmentPresentation.mode === "local" ? (
                 <PiLaptop className="size-3.5" />
               ) : (
@@ -300,15 +295,17 @@ export default function BranchToolbar({
               className="w-56 [&_[data-slot=popover-viewport]]:py-0 [&_[data-slot=popover-viewport]]:[--viewport-inline-padding:0px]"
             >
               <div className="py-1.5">
-                <p className="px-3 pb-1 pt-1 text-[11px] font-medium text-[var(--color-text-foreground-secondary)]">
+                <p className="px-3 pb-1 pt-1 text-[11px] font-medium text-(--app-metadata-muted-fg)">
                   Continue in
                 </p>
                 {environmentPresentation.mode === "local" ? (
                   <div className="flex w-full items-center gap-2 px-3 py-1.5 text-sm">
-                    <PiLaptop className="size-4 text-[var(--color-text-foreground-secondary)]" />
-                    <span>{environmentPresentation.localOptionLabel}</span>
+                    <PiLaptop className="size-4 text-(--app-work-row-icon)" />
+                    <span className="text-(--app-metadata-fg)">
+                      {environmentPresentation.localOptionLabel}
+                    </span>
                     <svg
-                      className="ml-auto size-4 text-[var(--color-text-foreground)]"
+                      className="ml-auto size-4 text-(--app-metadata-fg)"
                       viewBox="0 0 24 24"
                       fill="none"
                       stroke="currentColor"
@@ -322,35 +319,37 @@ export default function BranchToolbar({
                 ) : (
                   <button
                     type="button"
-                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-[var(--color-text-foreground)] transition-colors hover:bg-[var(--color-background-elevated-secondary)]"
+                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-(--app-metadata-fg) transition-colors hover:bg-(--app-work-row-hover-bg)"
                     onClick={() => {
                       setEnvPickerOpen(false);
                       onEnvModeChange("local");
                     }}
                   >
-                    <PiLaptop className="size-4 text-[var(--color-text-foreground-secondary)]" />
+                    <PiLaptop className="size-4 text-(--app-work-row-icon)" />
                     <span>{environmentPresentation.localOptionLabel}</span>
                   </button>
                 )}
                 {canSwitchToWorktree ? (
                   <button
                     type="button"
-                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-[var(--color-text-foreground)] transition-colors hover:bg-[var(--color-background-elevated-secondary)]"
+                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-(--app-metadata-fg) transition-colors hover:bg-(--app-work-row-hover-bg)"
                     onClick={() => {
                       setEnvPickerOpen(false);
                       onEnvModeChange("worktree");
                     }}
                   >
-                    <WorktreeGlyph className="size-4 text-[var(--color-text-foreground-secondary)]" />
+                    <WorktreeGlyph className="size-4 text-(--app-work-row-icon)" />
                     <span>New worktree</span>
                   </button>
                 ) : null}
                 {effectiveEnvMode === "worktree" && !canHandoffToLocal ? (
                   <div className="flex w-full items-center gap-2 px-3 py-1.5 text-sm">
-                    <WorktreeGlyph className="size-4 text-[var(--color-text-foreground-secondary)]" />
-                    <span>{environmentPresentation.worktreeOptionLabel}</span>
+                    <WorktreeGlyph className="size-4 text-(--app-work-row-icon)" />
+                    <span className="text-(--app-metadata-fg)">
+                      {environmentPresentation.worktreeOptionLabel}
+                    </span>
                     <svg
-                      className="ml-auto size-4 text-[var(--color-text-foreground)]"
+                      className="ml-auto size-4 text-(--app-metadata-fg)"
                       viewBox="0 0 24 24"
                       fill="none"
                       stroke="currentColor"
@@ -365,40 +364,40 @@ export default function BranchToolbar({
                 {canHandoffToWorktree && onHandoffToWorktree ? (
                   <button
                     type="button"
-                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-[var(--color-text-foreground)] transition-colors hover:bg-[var(--color-background-elevated-secondary)] disabled:pointer-events-none disabled:opacity-50"
+                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-(--app-metadata-fg) transition-colors hover:bg-(--app-work-row-hover-bg) disabled:pointer-events-none disabled:opacity-50"
                     disabled={handoffBusy}
                     onClick={() => {
                       setEnvPickerOpen(false);
                       onHandoffToWorktree();
                     }}
                   >
-                    <WorktreeGlyph className="size-4 text-[var(--color-text-foreground-secondary)]" />
+                    <WorktreeGlyph className="size-4 text-(--app-work-row-icon)" />
                     <span>Hand off to new worktree</span>
                   </button>
                 ) : null}
                 {canHandoffToLocal && onHandoffToLocal ? (
                   <button
                     type="button"
-                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-[var(--color-text-foreground)] transition-colors hover:bg-[var(--color-background-elevated-secondary)] disabled:pointer-events-none disabled:opacity-50"
+                    className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-left text-sm text-(--app-metadata-fg) transition-colors hover:bg-(--app-work-row-hover-bg) disabled:pointer-events-none disabled:opacity-50"
                     disabled={handoffBusy}
                     onClick={() => {
                       setEnvPickerOpen(false);
                       onHandoffToLocal();
                     }}
                   >
-                    <HandoffIcon className="size-4 text-[var(--color-text-foreground-secondary)]" />
+                    <HandoffIcon className="size-4 text-(--app-work-row-icon)" />
                     <span>Hand off to local</span>
                   </button>
                 ) : null}
               </div>
 
-              <div className="mx-3 border-t border-[color:var(--color-border-light)]" />
+              <div className="mx-3 border-t border-(--app-work-row-border)" />
 
               <div className="py-1.5">
                 <Collapsible open={rateLimitsOpen} onOpenChange={setRateLimitsOpen}>
-                  <CollapsibleTrigger className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-sm text-[var(--color-text-foreground)] transition-colors hover:bg-[var(--color-background-elevated-secondary)]">
+                  <CollapsibleTrigger className="flex w-full items-center gap-2 rounded-md px-3 py-1.5 text-sm text-(--app-metadata-fg) transition-colors hover:bg-(--app-work-row-hover-bg)">
                     <svg
-                      className="size-4 text-[var(--color-text-foreground-secondary)]"
+                      className="size-4 text-(--app-work-row-icon)"
                       viewBox="0 0 24 24"
                       fill="none"
                       stroke="currentColor"
@@ -412,7 +411,7 @@ export default function BranchToolbar({
                     <span>Rate limits remaining</span>
                     <ChevronRightIcon
                       className={cn(
-                        "ml-auto size-3.5 text-[var(--color-text-foreground-secondary)] transition-transform duration-150",
+                        "ml-auto size-3.5 text-(--app-work-row-icon) transition-transform duration-150",
                         rateLimitsOpen && "rotate-90",
                       )}
                     />
@@ -433,7 +432,7 @@ export default function BranchToolbar({
             </PopoverPopup>
           </Popover>
         ) : (
-          <span className="inline-flex items-center gap-1 px-1.5 text-[length:var(--app-font-size-ui-xs,10px)] font-normal text-[var(--color-text-foreground-secondary)]">
+          <span className="inline-flex items-center gap-1 px-1.5 text-[length:var(--app-font-size-ui-xs,10px)] font-normal text-(--app-metadata-muted-fg)">
             <WorktreeGlyph className="size-3.5" />
             {environmentPresentation.shortLabel}
           </span>
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 1d9267a95..0ddaf0060 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -768,7 +768,7 @@ function ComposerControlSkeleton(props: { widthClassName: string }) {
     <div
       aria-hidden="true"
       className={cn(
-        "flex h-8 shrink-0 items-center rounded-md border border-border/50 px-2",
+        "flex h-8 shrink-0 items-center rounded-md border border-(--app-chrome-control-border) px-2",
         props.widthClassName,
       )}
     >
@@ -782,7 +782,7 @@ function ComposerModelLoadingControl(props: { widthClassName: string }) {
     <div
       aria-label="Loading models"
       className={cn(
-        "flex h-8 shrink-0 items-center gap-2 rounded-md border border-border/50 px-2 text-muted-foreground",
+        "flex h-8 shrink-0 items-center gap-2 rounded-md border border-(--app-chrome-control-border) px-2 text-(--app-chrome-control-fg)",
         props.widthClassName,
       )}
     >
@@ -7471,7 +7471,7 @@ export default function ChatView({
                   </button>
                   <button
                     type="button"
-                    className="inline-flex size-6 items-center justify-center rounded-lg text-[var(--color-text-foreground-secondary)] transition-colors hover:bg-[var(--app-state-hover)] hover:text-[var(--color-text-foreground)]"
+                    className="inline-flex size-6 items-center justify-center rounded-lg text-(--app-chrome-control-fg) transition-colors hover:bg-(--app-chrome-control-hover-bg) hover:text-(--app-chrome-control-hover-fg)"
                     aria-label="Delete queued follow-up"
                     onClick={() => removeQueuedComposerTurn(queuedTurn.id)}
                   >
@@ -7482,7 +7482,7 @@ export default function ChatView({
                       render={
                         <button
                           type="button"
-                          className="inline-flex size-6 items-center justify-center rounded-lg text-[var(--color-text-foreground-secondary)] transition-colors hover:bg-[var(--app-state-hover)] hover:text-[var(--color-text-foreground)]"
+                          className="inline-flex size-6 items-center justify-center rounded-lg text-(--app-chrome-control-fg) transition-colors hover:bg-(--app-chrome-control-hover-bg) hover:text-(--app-chrome-control-hover-fg)"
                           aria-label="Queued follow-up actions"
                         />
                       }
@@ -8204,7 +8204,7 @@ export default function ChatView({
                               </button>
                               <button
                                 type="button"
-                                className="inline-flex size-6 items-center justify-center rounded-lg text-[var(--color-text-foreground-secondary)] transition-colors hover:bg-[var(--app-state-hover)] hover:text-[var(--color-text-foreground)]"
+                                className="inline-flex size-6 items-center justify-center rounded-lg text-(--app-chrome-control-fg) transition-colors hover:bg-(--app-chrome-control-hover-bg) hover:text-(--app-chrome-control-hover-fg)"
                                 aria-label="Delete queued follow-up"
                                 onClick={() => removeQueuedComposerTurn(queuedTurn.id)}
                               >
@@ -8215,7 +8215,7 @@ export default function ChatView({
                                   render={
                                     <button
                                       type="button"
-                                      className="inline-flex size-6 items-center justify-center rounded-lg text-[var(--color-text-foreground-secondary)] transition-colors hover:bg-[var(--app-state-hover)] hover:text-[var(--color-text-foreground)]"
+                                      className="inline-flex size-6 items-center justify-center rounded-lg text-(--app-chrome-control-fg) transition-colors hover:bg-(--app-chrome-control-hover-bg) hover:text-(--app-chrome-control-hover-fg)"
                                       aria-label="Queued follow-up actions"
                                     />
                                   }
diff --git a/apps/web/src/components/GitActionsControl.tsx b/apps/web/src/components/GitActionsControl.tsx
index 160f56a1b..b519a81b2 100644
--- a/apps/web/src/components/GitActionsControl.tsx
+++ b/apps/web/src/components/GitActionsControl.tsx
@@ -1205,7 +1205,7 @@ export default function GitActionsControl({
   if (!gitCwd) return null;
 
   const headerGhostClass =
-    "bg-transparent not-disabled:before:shadow-none dark:not-disabled:before:shadow-none [:hover,[data-pressed]]:bg-[var(--sidebar-accent)] dark:[:hover,[data-pressed]]:bg-[var(--sidebar-accent)]";
+    "border-(--app-chrome-control-border) bg-(--app-chrome-control-bg) text-(--app-chrome-control-fg) not-disabled:before:shadow-none dark:not-disabled:before:shadow-none [:hover,[data-pressed]]:bg-(--app-chrome-control-hover-bg) [:hover,[data-pressed]]:text-(--app-chrome-control-hover-fg) dark:[:hover,[data-pressed]]:bg-(--app-chrome-control-hover-bg) data-pressed:bg-(--app-chrome-control-active-bg)";
 
   return (
     <>
@@ -1286,7 +1286,7 @@ export default function GitActionsControl({
             <MenuPopup
               align="end"
               side="bottom"
-              className="w-50 rounded-lg border-[color:var(--color-border)] bg-[var(--composer-surface)] shadow-lg"
+              className="w-50 rounded-lg border-(--app-chrome-control-border) bg-(--app-work-row-bg) shadow-lg"
             >
               <MenuGroup>
                 <MenuGroupLabel>Git actions</MenuGroupLabel>
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
index d815c20c8..be8630488 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -250,7 +250,7 @@ export const ChatHeader = memo(function ChatHeader({
                 className={cn(
                   "flex min-w-0 items-center gap-2",
                   showSidechatTitleChip &&
-                    "rounded-lg bg-secondary py-1 pl-2 pr-1 text-secondary-foreground",
+                    "rounded-lg bg-(--app-chrome-control-bg) py-1 pl-2 pr-1 text-(--app-chrome-control-fg)",
                 )}
               >
                 {threadIconKind === "none" ? null : (
@@ -282,7 +282,7 @@ export const ChatHeader = memo(function ChatHeader({
                       render={
                         <button
                           type="button"
-                          className="inline-flex size-5 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-background/55 hover:text-foreground [-webkit-app-region:no-drag]"
+                          className="inline-flex size-5 shrink-0 items-center justify-center rounded-md text-(--app-chrome-control-fg) transition-colors hover:bg-(--app-chrome-control-hover-bg) hover:text-(--app-chrome-control-hover-fg) [-webkit-app-region:no-drag]"
                           aria-label="Close selected sidechat"
                           onClick={(event) => {
                             event.stopPropagation();
@@ -335,7 +335,7 @@ export const ChatHeader = memo(function ChatHeader({
                         size="xs"
                         variant="outline"
                         className={cn(
-                          "shrink-0 bg-transparent not-disabled:before:shadow-none dark:not-disabled:before:shadow-none [:hover,[data-pressed]]:bg-[var(--sidebar-accent)] dark:[:hover,[data-pressed]]:bg-[var(--sidebar-accent)]",
+                          "shrink-0 border-(--app-chrome-control-border) bg-(--app-chrome-control-bg) text-(--app-chrome-control-fg) not-disabled:before:shadow-none dark:not-disabled:before:shadow-none [:hover,[data-pressed]]:bg-(--app-chrome-control-hover-bg) [:hover,[data-pressed]]:text-(--app-chrome-control-hover-fg) dark:[:hover,[data-pressed]]:bg-(--app-chrome-control-hover-bg) data-pressed:bg-(--app-chrome-control-active-bg)",
                           compact ? "gap-1" : "gap-1.5",
                         )}
                         aria-label={handoffActionLabel}

From 56bfa729489bb40d7e1cd717107a8ba83a33cdcb Mon Sep 17 00:00:00 2001
From: Jay1 <j-chiasson@outlook.com>
Date: Sun, 31 May 2026 18:39:10 -0400
Subject: [PATCH 3/6] web: theme chat work surfaces

---
 apps/web/src/components/Sidebar.tsx           |  4 +-
 .../components/chat/MessageActionButton.tsx   |  2 +-
 .../src/components/chat/MessagesTimeline.tsx  | 71 ++++++++++---------
 3 files changed, 40 insertions(+), 37 deletions(-)

diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 91c101ea4..031d38cda 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -4017,7 +4017,7 @@ export default function Sidebar() {
         aria-label="Archive thread"
         title="Archive thread"
         className={cn(
-          "sidebar-icon-button inline-flex justify-center hover:text-foreground/89",
+          "sidebar-icon-button inline-flex justify-center",
           compact ? "size-[18px]" : "size-5",
           toneClassName,
         )}
@@ -5682,7 +5682,7 @@ export default function Sidebar() {
                                     )}
                                     <button
                                       type="button"
-                                      className="sidebar-icon-button ml-auto inline-flex size-5 shrink-0 text-muted-foreground/50 opacity-0 transition-opacity group-hover/ws:opacity-100"
+                                      className="sidebar-icon-button ml-auto inline-flex size-5 shrink-0 opacity-0 transition-opacity group-hover/ws:opacity-100"
                                       aria-label="Delete workspace"
                                       onClick={(event) => {
                                         event.stopPropagation();
diff --git a/apps/web/src/components/chat/MessageActionButton.tsx b/apps/web/src/components/chat/MessageActionButton.tsx
index 2f4cd157d..c981a0926 100644
--- a/apps/web/src/components/chat/MessageActionButton.tsx
+++ b/apps/web/src/components/chat/MessageActionButton.tsx
@@ -8,7 +8,7 @@ import { cn } from "~/lib/utils";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 
 export const MESSAGE_ACTION_BUTTON_CLASS_NAME =
-  "sidebar-icon-button inline-flex size-5 cursor-pointer border border-transparent bg-transparent shadow-none disabled:cursor-default disabled:opacity-45";
+  "sidebar-icon-button inline-flex size-5 cursor-pointer border border-(--app-chrome-control-border) shadow-none disabled:cursor-default disabled:opacity-45";
 
 type MessageActionButtonProps = Omit<
   ComponentProps<"button">,
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index f82dcbe33..2513d60bc 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -841,8 +841,8 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                     correspondingUserMessageId != null &&
                     revertTurnCountByUserMessageId.has(correspondingUserMessageId);
                   return (
-                    <div className="mt-5 overflow-hidden rounded-xl border border-[color:var(--color-border-light)] bg-[var(--app-diff-card-bg)]">
-                      <div className="flex items-center justify-between gap-2 border-b border-[color:var(--color-border-light)] bg-[var(--app-diff-card-header-bg)] px-3 py-2">
+                    <div className="mt-5 overflow-hidden rounded-xl border border-[color:var(--app-work-row-border)] bg-[var(--app-diff-card-bg)]">
+                      <div className="flex items-center justify-between gap-2 border-b border-[color:var(--app-work-row-border)] bg-[var(--app-diff-card-header-bg)] px-3 py-2">
                         <span
                           className="truncate font-normal text-foreground/92"
                           style={{ fontSize: chatTypographyStyle.fontSize }}
@@ -854,7 +854,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                         <div className="flex items-center gap-4">
                           <button
                             type="button"
-                            className="inline-flex items-center justify-center rounded-md p-1 text-muted-foreground/70 transition-colors hover:bg-[var(--app-state-hover)] hover:text-foreground/80"
+                            className="inline-flex items-center justify-center rounded-md p-1 text-[var(--app-metadata-muted-fg)] transition-colors hover:bg-[var(--app-work-row-hover-bg)] hover:text-[var(--app-metadata-fg)]"
                             aria-expanded={fileChangesExpanded}
                             aria-label={
                               fileChangesExpanded
@@ -869,13 +869,13 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                           >
                             <DisclosureChevron
                               open={fileChangesExpanded}
-                              className="dark:text-muted-foreground/50"
+                              className="text-[var(--app-work-row-icon)]"
                             />
                           </button>
                           {canUndo && (
                             <button
                               type="button"
-                              className="flex items-center gap-1 text-muted-foreground transition-colors hover:text-foreground"
+                              className="flex items-center gap-1 text-[var(--app-metadata-muted-fg)] transition-colors hover:text-[var(--app-metadata-fg)]"
                               style={{ fontSize: chatTypographyStyle.fontSize }}
                               onClick={() => onRevertUserMessage(correspondingUserMessageId)}
                             >
@@ -891,14 +891,14 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                             <button
                               key={file.path}
                               type="button"
-                              className="group flex w-full items-center gap-2 border-t border-[color:var(--color-border-light)] px-3 py-1.5 text-left first:border-t-0 transition-colors hover:bg-[var(--app-state-hover)]"
+                              className="group flex w-full items-center gap-2 border-t border-[color:var(--app-work-row-border)] bg-[var(--app-work-row-bg)] px-3 py-1.5 text-left first:border-t-0 transition-colors hover:bg-[var(--app-work-row-hover-bg)]"
                               onClick={() => onOpenTurnDiff(turnSummary.turnId, file.path)}
                             >
                               <FileEntryIcon
                                 pathValue={file.path}
                                 kind="file"
                                 theme={resolvedTheme}
-                                className="size-4 shrink-0 opacity-50 dark:opacity-30"
+                                className="size-4 shrink-0 text-[var(--app-work-row-icon)]"
                               />
                               <span
                                 className="font-system-ui truncate font-normal underline-offset-2 group-hover:underline group-focus-visible:underline"
@@ -929,7 +929,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                 })()}
                 <div className="mt-0.5 flex items-center gap-2">
                   <p
-                    className="font-system-ui tabular-nums text-muted-foreground/45"
+                    className="font-system-ui tabular-nums text-[var(--app-metadata-muted-fg)]"
                     style={{ fontSize: `${appTypographyScale.uiTimestampPx}px` }}
                   >
                     {assistantMeta}
@@ -940,7 +940,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
                         text={assistantCopyState.text ?? ""}
                         size="icon-xs"
                         variant="outline"
-                        className="border-border/50 bg-background/35 text-muted-foreground/45 shadow-none hover:border-border/70 hover:bg-background/55 hover:text-muted-foreground/70"
+                        className="border-[color:var(--app-chrome-control-border)] bg-[var(--app-chrome-control-bg)] text-[var(--app-chrome-control-fg)] shadow-none hover:border-[color:var(--app-chrome-control-border)] hover:bg-[var(--app-chrome-control-hover-bg)] hover:text-[var(--app-chrome-control-hover-fg)]"
                       />
                     </div>
                   ) : null}
@@ -963,7 +963,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
 
       {row.kind === "working" && (
         <div
-          className="flex items-center gap-1 pt-1 pl-1 text-muted-foreground/70 font-system-ui"
+          className="flex items-center gap-1 pt-1 pl-1 text-[var(--app-metadata-muted-fg)] font-system-ui"
           style={{ fontSize: `${appTypographyScale.uiSmPx}px` }}
         >
           <span>
@@ -981,9 +981,9 @@ export const MessagesTimeline = memo(function MessagesTimeline({
             )}
           </span>
           <span className="inline-flex items-center gap-1">
-            <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse" />
-            <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse [animation-delay:200ms]" />
-            <span className="h-1 w-1 rounded-full bg-muted-foreground/30 animate-pulse [animation-delay:400ms]" />
+            <span className="h-1 w-1 rounded-full bg-[var(--app-work-row-icon)] animate-pulse" />
+            <span className="h-1 w-1 rounded-full bg-[var(--app-work-row-icon)] animate-pulse [animation-delay:200ms]" />
+            <span className="h-1 w-1 rounded-full bg-[var(--app-work-row-icon)] animate-pulse [animation-delay:400ms]" />
           </span>
         </div>
       )}
@@ -1880,7 +1880,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                   "group flex w-full max-w-full items-baseline gap-1 text-left transition-opacity duration-150",
                   compact
                     ? "px-0 py-[1px] hover:opacity-95"
-                    : "rounded-md border border-border/45 bg-background/65 px-2 py-1 hover:bg-background/80",
+                    : "rounded-md border border-[color:var(--app-work-row-border)] bg-[var(--app-work-row-bg)] px-2 py-1 hover:bg-[var(--app-work-row-hover-bg)]",
                   canOpenEditedDiff ? "cursor-pointer" : "cursor-default",
                 )}
                 title={changedFilePath}
@@ -1891,7 +1891,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                 }}
               >
                 <span
-                  className="font-system-ui shrink-0 font-medium text-muted-foreground/72"
+                  className="font-system-ui shrink-0 font-medium text-[var(--app-metadata-muted-fg)]"
                   style={{ fontSize: `${rowFontSizePx}px` }}
                 >
                   Edited
@@ -1930,7 +1930,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
           >
             <span
               className={cn(
-                "flex shrink-0 items-center justify-center text-muted-foreground/40",
+                "flex shrink-0 items-center justify-center text-[var(--app-work-row-icon)]",
                 compact ? "size-4" : "size-5",
               )}
             >
@@ -1940,7 +1940,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
               <p
                 className={cn(
                   compact ? "truncate leading-5" : "truncate leading-6",
-                  "font-medium text-foreground/72",
+                  "font-medium text-[var(--app-metadata-fg)]",
                 )}
                 style={{ fontSize: `${rowFontSizePx}px` }}
                 title={hoverText}
@@ -1949,7 +1949,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
               </p>
               {subagentMeta ? (
                 <p
-                  className="truncate leading-4 text-muted-foreground/32"
+                  className="truncate leading-4 text-[var(--app-metadata-muted-fg)]"
                   style={{ fontSize: `${Math.max(11, rowFontSizePx - 1)}px` }}
                   title={subagentMeta}
                 >
@@ -1961,7 +1961,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
           {visibleSubagents.length > 0 || hiddenSubagentCount > 0 ? (
             <div
               className={cn(
-                "space-y-[5px] rounded-[14px] border border-border/45 bg-background/50 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]",
+                "space-y-[5px] rounded-[14px] border border-[color:var(--app-work-row-border)] bg-[var(--app-work-row-bg)] shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]",
                 compact ? "px-2.5 py-2" : "px-3 py-[9px]",
               )}
             >
@@ -1976,7 +1976,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                 return (
                   <div
                     key={`${workEntry.id}:${subagent.threadId}`}
-                    className="flex items-start gap-2.5 rounded-xl border border-border/28 bg-background/82 px-[11px] py-2"
+                    className="flex items-start gap-2.5 rounded-xl border border-[color:var(--app-work-row-border)] bg-[var(--app-work-row-bg)] px-[11px] py-2"
                   >
                     <span
                       className={cn(
@@ -1988,7 +1988,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                     />
                     <div className="min-w-0 flex-1">
                       <div
-                        className="truncate font-semibold leading-[18px] text-foreground/90"
+                        className="truncate font-semibold leading-[18px] text-[var(--app-metadata-fg)]"
                         style={{ fontSize: `${rowFontSizePx}px` }}
                         title={presentation.fullLabel}
                       >
@@ -1996,14 +1996,14 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                           {presentation.nickname ?? primaryLabel}
                         </span>
                         {presentation.role ? (
-                          <span className="ml-1 text-[11px] font-medium text-muted-foreground/48">
+                          <span className="ml-1 text-[11px] font-medium text-[var(--app-metadata-muted-fg)]">
                             ({presentation.role})
                           </span>
                         ) : null}
                       </div>
                       {secondaryLabel ? (
                         <div
-                          className="truncate pt-0.5 leading-4 text-muted-foreground/56"
+                          className="truncate pt-0.5 leading-4 text-[var(--app-metadata-muted-fg)]"
                           style={{ fontSize: `${Math.max(11, rowFontSizePx - 1)}px` }}
                           title={secondaryLabel}
                         >
@@ -2012,11 +2012,11 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                       ) : null}
                       {subagent.latestUpdate ? (
                         <div
-                          className="flex items-baseline gap-1.5 pt-1 text-muted-foreground/42"
+                          className="flex items-baseline gap-1.5 pt-1 text-[var(--app-metadata-muted-fg)]"
                           style={{ fontSize: `${Math.max(10, rowFontSizePx - 2)}px` }}
                           title={subagent.latestUpdate}
                         >
-                          <span className="shrink-0 uppercase tracking-[0.14em] text-muted-foreground/30">
+                          <span className="shrink-0 uppercase tracking-[0.14em] text-[var(--app-work-row-icon)]">
                             Latest
                           </span>
                           <span className="truncate">{subagent.latestUpdate}</span>
@@ -2041,9 +2041,9 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                       <button
                         type="button"
                         className={cn(
-                          "shrink-0 rounded-full border border-border/45 px-2.5 py-1 text-[9px] font-medium uppercase tracking-[0.12em] text-muted-foreground/62 transition-colors",
+                          "shrink-0 rounded-full border border-[color:var(--app-work-row-border)] px-2.5 py-1 text-[9px] font-medium uppercase tracking-[0.12em] text-[var(--app-metadata-muted-fg)] transition-colors",
                           canOpenThread
-                            ? "hover:border-foreground/15 hover:text-foreground/84"
+                            ? "hover:border-[color:var(--app-work-row-border)] hover:bg-[var(--app-work-row-hover-bg)] hover:text-[var(--app-metadata-fg)]"
                             : "cursor-default opacity-50",
                         )}
                         disabled={!canOpenThread}
@@ -2060,7 +2060,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                 );
               })}
               {hiddenSubagentCount > 0 ? (
-                <div className="pl-4 text-[10px] uppercase tracking-[0.12em] text-muted-foreground/46">
+                <div className="pl-4 text-[10px] uppercase tracking-[0.12em] text-[var(--app-metadata-muted-fg)]">
                   +{hiddenSubagentCount} more
                 </div>
               ) : null}
@@ -2080,7 +2080,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
               {showIconLeft && (
                 <span
                   className={cn(
-                    "flex shrink-0 items-center justify-center text-muted-foreground/40",
+                    "flex shrink-0 items-center justify-center text-[var(--app-work-row-icon)]",
                     compact ? "size-4" : "size-5",
                   )}
                 >
@@ -2091,13 +2091,13 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                 <p
                   className={cn(
                     compact ? "truncate leading-5" : "truncate leading-6",
-                    "text-muted-foreground/50",
+                    "text-[var(--app-metadata-muted-fg)]",
                   )}
                   style={{ fontSize: `${rowFontSizePx}px` }}
                 >
                   {showInlineWebSearchIcon || showInlineGitHubIcon || showInlineMcpIcon ? (
                     <span
-                      className="mr-1 inline-flex align-[-0.125em] text-muted-foreground/38"
+                      className="mr-1 inline-flex align-[-0.125em] text-[var(--app-work-row-icon)]"
                       data-inline-tool-icon={
                         showInlineGitHubIcon ? "github" : showInlineMcpIcon ? "mcp" : "web-search"
                       }
@@ -2128,11 +2128,14 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
                       ) : null}
                     </span>
                   ) : null}
-                  <span className="text-muted-foreground/48" data-work-entry-display-text="true">
+                  <span
+                    className="text-[var(--app-metadata-muted-fg)]"
+                    data-work-entry-display-text="true"
+                  >
                     {displayTextParts ? (
                       <>
                         <span
-                          className="font-medium text-muted-foreground/72"
+                          className="font-medium text-[var(--app-metadata-fg)]"
                           data-work-entry-action-word="true"
                         >
                           {displayTextParts.action}
@@ -2147,7 +2150,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
               </div>
               {showIconRight && (
                 <span
-                  className="flex shrink-0 items-center justify-center text-muted-foreground/40"
+                  className="flex shrink-0 items-center justify-center text-[var(--app-work-row-icon)]"
                   style={{ width: rowFontSizePx, height: rowFontSizePx }}
                 >
                   <EntryIcon style={{ width: rowFontSizePx, height: rowFontSizePx }} />

From 996f07484920e8996d448977cb48dc1b8a761a97 Mon Sep 17 00:00:00 2001
From: Jay1 <j-chiasson@outlook.com>
Date: Sun, 31 May 2026 18:39:17 -0400
Subject: [PATCH 4/6] docs: document theme surface tokens

---
 docs/architecture/README.md               | 16 +++---
 docs/architecture/theme-surface-tokens.md | 70 +++++++++++++++++++++++
 2 files changed, 79 insertions(+), 7 deletions(-)
 create mode 100644 docs/architecture/theme-surface-tokens.md

diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 6087f0ed6..ed0dc7514 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -15,17 +15,19 @@
 
 ## Start Here By Scenario
 
-| If you are doing this         | Start here                                                                     | Then check                                                   |
-| ----------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------ |
-| Getting oriented              | [System Overview](system-overview.md)                                          | [`../../AGENTS.md`](../../AGENTS.md)                         |
-| Checking workspace boundaries | [Runtime Boundaries](runtime-boundaries.md)                                    | [System Overview](system-overview.md)                        |
-| Changing providers            | [Provider Runtime Architecture](provider-runtime.md)                           | [`../../apps/server/AGENTS.md`](../../apps/server/AGENTS.md) |
-| Changing server boundaries    | [Server Architecture Migration Inventory](../server-architecture-migration.md) | [Testing Strategy](../testing/strategy.md)                   |
-| Recording a durable decision  | [ADR Index](../adr/README.md)                                                  | [Repo Governance](../governance/repo-governance.md)          |
+| If you are doing this         | Start here                                                                     | Then check                                                            |
+| ----------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| Getting oriented              | [System Overview](system-overview.md)                                          | [`../../AGENTS.md`](../../AGENTS.md)                                  |
+| Checking workspace boundaries | [Runtime Boundaries](runtime-boundaries.md)                                    | [System Overview](system-overview.md)                                 |
+| Changing providers            | [Provider Runtime Architecture](provider-runtime.md)                           | [`../../apps/server/AGENTS.md`](../../apps/server/AGENTS.md)          |
+| Changing server boundaries    | [Server Architecture Migration Inventory](../server-architecture-migration.md) | [Testing Strategy](../testing/strategy.md)                            |
+| Changing theme surface tokens | [Theme Surface Token Rules](theme-surface-tokens.md)                           | [Appearance Regression Testing](../testing/appearance-regressions.md) |
+| Recording a durable decision  | [ADR Index](../adr/README.md)                                                  | [Repo Governance](../governance/repo-governance.md)                   |
 
 ## Documents
 
 - [System Overview](system-overview.md)
 - [Runtime Boundaries](runtime-boundaries.md)
 - [Provider Runtime Architecture](provider-runtime.md)
+- [Theme Surface Token Rules](theme-surface-tokens.md)
 - [Server Architecture Migration Inventory](../server-architecture-migration.md)
diff --git a/docs/architecture/theme-surface-tokens.md b/docs/architecture/theme-surface-tokens.md
new file mode 100644
index 000000000..d24a2a2b1
--- /dev/null
+++ b/docs/architecture/theme-surface-tokens.md
@@ -0,0 +1,70 @@
+# Theme Surface Token Rules
+
+| Field           | Value                                                                                                                                                                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Status          | Active                                                                                                                                                               |
+| Type            | Architecture reference                                                                                                                                               |
+| Owner           | Engineering                                                                                                                                                          |
+| Audience        | Web UI engineers, reviewers, and automation agents                                                                                                                   |
+| Scope           | Theme surface, chrome control, metadata, work row, and status token ownership for `apps/web`                                                                         |
+| Canonical path  | `docs/architecture/theme-surface-tokens.md`                                                                                                                          |
+| Last reviewed   | 2026-05-31                                                                                                                                                           |
+| Review cadence  | Event-driven; review when theme token derivation, semantic CSS variables, Appearance settings, or shared chrome components change                                    |
+| Source of truth | `apps/web/src/theme/theme.logic.ts`, `apps/web/src/theme/theme.logic.test.ts`, `apps/web/src/index.css`, and components that consume semantic `--app-*` tokens       |
+| Verification    | Cross-check token derivation and component class usage; keep Appearance contracts aligned with [Appearance Regression Testing](../testing/appearance-regressions.md) |
+
+## Purpose
+
+Theme surface tokens give the web UI one shared language for app depth, compact controls, metadata, work rows, and status markers. They keep theme math in the theme layer and keep component classes focused on semantic intent.
+
+Use this page when changing theme color derivation, adding a visible chrome surface, or reviewing component classes that use `--app-*` CSS variables.
+
+## Token Layers And Ownership
+
+| Layer                       | Owner            | Source                                                                                                                           | Rule                                                                                                                       |
+| --------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Theme state and seed inputs | Theme logic      | `apps/web/src/theme/theme.logic.ts`                                                                                              | `ChromeTheme`, bundled seeds, and seed patch metadata own stored or imported theme values.                                 |
+| Derived app surface tokens  | Theme logic      | `buildThemeCssVariables`, `buildProfileAppDepthVariables`, Catppuccin branch in `apps/web/src/theme/theme.logic.ts`              | Theme code derives semantic `--app-*` variables from the resolved theme, not from component local choices.                 |
+| CSS component helpers       | Base stylesheet  | `apps/web/src/index.css`                                                                                                         | Shared CSS helpers, such as `.sidebar-icon-button`, may compose semantic tokens with fallbacks for common chrome.          |
+| Component classes           | React components | `ChatHeader.tsx`, `GitActionsControl.tsx`, `BranchToolbar.tsx`, `MessagesTimeline.tsx`, `MessageActionButton.tsx`, `Sidebar.tsx` | Components should consume semantic tokens that describe the UI role they are rendering.                                    |
+| Token contract tests        | Theme tests      | `apps/web/src/theme/theme.logic.test.ts`                                                                                         | Tests lock required app depth tokens and example values for derived surfaces, controls, metadata, work rows, and statuses. |
+
+## Surface Families
+
+| Family          | Tokens                                                                                                                                                                                                                                                                                              | Use for                                                                                                                      | Source evidence                                                                                                                                                                                                  |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| App surfaces    | `--app-surface-canvas`, `--app-surface-sidebar`, `--app-surface-topbar`, `--app-surface-panel`, `--app-surface-card`, `--app-surface-card-header`, `--app-surface-composer`, `--app-surface-toolbar`, `--app-surface-toolbar-hover`, `--app-surface-toolbar-active`, `--app-surface-toolbar-border` | App shell depth, panels, cards, composer surfaces, and compact toolbar chrome                                                | Derived in `apps/web/src/theme/theme.logic.ts`; required by `REQUIRED_APP_DEPTH_TOKENS` in `apps/web/src/theme/theme.logic.test.ts`; used by toolbar and git action classes.                                     |
+| Chrome controls | `--app-chrome-control-bg`, `--app-chrome-control-border`, `--app-chrome-control-fg`, `--app-chrome-control-hover-bg`, `--app-chrome-control-hover-fg`, `--app-chrome-control-active-bg`                                                                                                             | Compact controls embedded in app chrome where background, border, foreground, hover, and active states need to move together | Derived in `buildProfileAppDepthVariables`; tested in the Catppuccin token expectations.                                                                                                                         |
+| Metadata text   | `--app-metadata-fg`, `--app-metadata-muted-fg`, `--app-text-metadata`, `--app-text-metadata-strong`                                                                                                                                                                                                 | Secondary labels, compact badges, headers, environment labels, and stronger metadata text                                    | Derived from theme ink alpha in `apps/web/src/theme/theme.logic.ts`; used by `BranchToolbar.tsx`.                                                                                                                |
+| Control icons   | `--app-control-icon-bg`, `--app-control-icon-border`, `--app-control-icon-fg`, `--app-control-icon-hover-bg`, `--app-control-icon-hover-fg`                                                                                                                                                         | Small icon buttons and compact message actions                                                                               | Derived in theme logic; `.sidebar-icon-button` in `apps/web/src/index.css` applies the shared icon background, text, hover, and focus tokens; `MessageActionButton.tsx` adds the shared border token.            |
+| Work rows       | `--app-work-row-bg`, `--app-work-row-hover-bg`, `--app-work-row-border`, `--app-work-row-icon`                                                                                                                                                                                                      | Branch/worktree picker rows plus chat file-change, subagent, tool, environment, handoff, and related work row affordances    | Derived from the current panel and ink colors in `apps/web/src/theme/theme.logic.ts`; used by `BranchToolbar.tsx` and `MessagesTimeline.tsx`.                                                                    |
+| Status tokens   | `--app-status-{kind}-fg`, `--app-status-{kind}-dot`, `--app-status-{kind}-bg`, `--app-status-{kind}-border`                                                                                                                                                                                         | Thread, terminal, PR, plan, input, warning, success, working, error, and muted status markers                                | `APP_STATUS_TOKEN_KINDS` defines `working`, `success`, `warning`, `input`, `plan`, `error`, and `muted`; `buildStatusVariables` emits each state shape; `Sidebar.tsx` consumes status foreground and dot tokens. |
+
+## Component Usage Rules
+
+| Rule                                                                                      | Why                                                                                                                           | Verify in source                                                                                                      |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Use `--app-surface-*` tokens for app depth, not raw palette names or generic card tokens. | Surface tokens preserve depth differences across custom themes and special palette branches.                                  | `GitActionsControl.tsx` uses toolbar surface, hover, active, and border tokens for header controls.                   |
+| Use `--app-text-metadata*` or `--app-metadata-*` for secondary chrome text.               | Metadata text alpha is derived from theme ink and stays readable across light and dark variants.                              | `BranchToolbar.tsx` uses metadata text tokens for runtime, environment, and picker labels.                            |
+| Use `.sidebar-icon-button` or `--app-control-icon-*` for compact icon actions.            | Shared control icon tokens keep border, background, hover, and focus behavior consistent.                                     | `apps/web/src/index.css` defines `.sidebar-icon-button`; `MessageActionButton.tsx` composes it with the border token. |
+| Use `--app-work-row-*` for rows that represent a working context.                         | Work rows need a distinct row background, hover background, border, and icon tint without copying panel math into components. | `BranchToolbar.tsx` uses work row icon and row hover tokens in environment and worktree choices.                      |
+| Use `--app-status-*` tokens for status meaning, not one-off semantic colors.              | Status foreground, dot, background, and border values are emitted as a set for each status kind.                              | `Sidebar.tsx` uses status tokens for fork, sidechat, terminal, PR, and thread activity markers.                       |
+
+## Accessibility And Contrast Guardrails
+
+| Guardrail                                                                                                 | Reason                                                                                                                                 | Source-grounded check                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Keep foreground tokens derived from theme ink, accent, or semantic status colors.                         | Components should inherit theme contrast decisions instead of hardcoding per-component text colors.                                    | `--app-text-metadata`, `--app-text-metadata-strong`, and `--app-chrome-control-fg` are derived in `apps/web/src/theme/theme.logic.ts`. |
+| Keep hover and active tokens paired with their base surface.                                              | Interaction states must remain visible without changing the component's semantic role.                                                 | Toolbar and control hover tokens are emitted beside base toolbar and control tokens.                                                   |
+| Keep focus styling tied to `--app-state-focus`.                                                           | Keyboard focus should follow the active theme and stay separate from hover or selected states.                                         | `.sidebar-icon-button` in `apps/web/src/index.css` uses `--app-state-focus` for its focus ring.                                        |
+| Do not use status foreground tokens as large backgrounds without the matching background or border token. | Status foreground colors are optimized for marks and text. The generated `bg` and `border` tokens carry the proper alpha for surfaces. | `buildStatusVariables` emits `fg`, `dot`, `bg`, and `border` for each status kind.                                                     |
+
+## Testing And Verification Expectations
+
+| Change                                                                                  | Expected verification                                                                                                                                  |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Add, rename, or remove a required surface token                                         | Update `REQUIRED_APP_DEPTH_TOKENS` and matching expectations in `apps/web/src/theme/theme.logic.test.ts`.                                              |
+| Change token derivation math                                                            | Cross-check `buildThemeCssVariables`, the Catppuccin branch, and `buildProfileAppDepthVariables` for both general themes and special palette handling. |
+| Reroute a visible component class to semantic tokens                                    | Check the touched component class and the shared helper in `apps/web/src/index.css` when applicable.                                                   |
+| Change Appearance settings, theme import behavior, or browser-visible token inheritance | Review [Appearance Regression Testing](../testing/appearance-regressions.md) and keep its contract chain current.                                      |
+| Documentation-only edits                                                                | Follow `docs/AGENTS.md`: run `git diff --check` and inspect changed relative links.                                                                    |

From fa1534e92ba958b4ee5fbd6b27253b93797d18be Mon Sep 17 00:00:00 2001
From: Jay1 <j-chiasson@outlook.com>
Date: Sun, 31 May 2026 18:39:26 -0400
Subject: [PATCH 5/6] docs: dedupe testing index

---
 docs/testing/README.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/testing/README.md b/docs/testing/README.md
index 4e31c392b..ab8dcc6f1 100644
--- a/docs/testing/README.md
+++ b/docs/testing/README.md
@@ -26,4 +26,3 @@
 
 - [Testing Strategy](strategy.md)
 - [Appearance Regression Testing](appearance-regressions.md)
-- [Appearance Regression Testing](appearance-regressions.md)

From 009cf9d00dab739fc311405aa8ff41a5bbed2245 Mon Sep 17 00:00:00 2001
From: Jay1 <j-chiasson@outlook.com>
Date: Sun, 31 May 2026 19:55:26 -0400
Subject: [PATCH 6/6] test: update themed work row expectation

---
 apps/web/src/components/chat/MessagesTimeline.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index 2c54aa623..fffdd0a19 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -1156,7 +1156,7 @@ describe("MessagesTimeline", () => {
     );
 
     expect(markup).toContain(
-      '<span class="font-medium text-muted-foreground/72" data-work-entry-action-word="true">Searched</span> 2 files found',
+      '<span class="font-medium text-[var(--app-metadata-fg)]" data-work-entry-action-word="true">Searched</span> 2 files found',
     );
   });