diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx
index ce4db4e2be..cbe8ff39c6 100644
--- a/docs/next/website/src/content/docs/configuration.mdx
+++ b/docs/next/website/src/content/docs/configuration.mdx
@@ -255,6 +255,23 @@ yellow = "#f9e2af"
 
 Color values accept hex, named colors, `rgb(r,g,b)`, or reset aliases like `reset`, `default`, `none`, and `transparent`.
 
+When `auto_switch` is enabled, optional light and dark subtables layer on top of the shared custom colors:
+
+```toml
+[theme.custom]
+accent = "#89b4fa"
+
+[theme.custom.light]
+panel_bg = "#eff1f5"
+text = "#4c4f69"
+
+[theme.custom.dark]
+panel_bg = "#1e1e2e"
+text = "#cdd6f4"
+```
+
+The active palette is applied in this order: built-in theme, `[theme.custom]`, then `[theme.custom.light]` or `[theme.custom.dark]`. Omitting the mode subtables preserves the existing shared override behavior.
+
 ## UI and sidebar
 
 The sidebar is the main Herdr dashboard. Search `ui.` in the [Config reference](/docs/config-reference/) for sizing, collapsed mode, Agent panel ordering, mouse behavior, pane borders, and other presentation settings.
diff --git a/docs/next/website/src/data/config-reference.json b/docs/next/website/src/data/config-reference.json
index e7a0539b38..ab0e84d67c 100644
--- a/docs/next/website/src/data/config-reference.json
+++ b/docs/next/website/src/data/config-reference.json
@@ -141,6 +141,210 @@
           "type": "color",
           "default": "unset",
           "description": "Override the peach color token on top of the base theme. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.accent",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the accent color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.panel_bg",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the panel_bg color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.sidebar_bg",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the sidebar_bg color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.surface0",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the surface0 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.surface1",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the surface1 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.surface_dim",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the surface_dim color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.overlay0",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the overlay0 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.overlay1",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the overlay1 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.text",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the text color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.subtext0",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the subtext0 color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.mauve",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the mauve color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.green",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the green color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.yellow",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the yellow color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.red",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the red color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.blue",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the blue color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.teal",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the teal color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.light.peach",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the peach color token when auto_switch selects a light appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.accent",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the accent color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.panel_bg",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the panel_bg color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.sidebar_bg",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the sidebar_bg color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.surface0",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the surface0 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.surface1",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the surface1 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.surface_dim",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the surface_dim color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.overlay0",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the overlay0 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.overlay1",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the overlay1 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.text",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the text color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.subtext0",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the subtext0 color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.mauve",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the mauve color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.green",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the green color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.yellow",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the yellow color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.red",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the red color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.blue",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the blue color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.teal",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the teal color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
+        },
+        {
+          "key": "theme.custom.dark.peach",
+          "type": "color",
+          "default": "unset",
+          "description": "Override the peach color token when auto_switch selects a dark appearance. Applied after theme.custom. Accepts hex, named colors, rgb(r,g,b), or reset aliases."
         }
       ]
     },
diff --git a/src/app/mod.rs b/src/app/mod.rs
index 5e3c86de0f..4bb7aeee2c 100644
--- a/src/app/mod.rs
+++ b/src/app/mod.rs
@@ -320,6 +320,7 @@ fn resolve_palette_for_theme_name(
     name: &str,
     fallback_name: &str,
     runtime: &state::ThemeRuntimeConfig,
+    mode_custom: Option<&crate::config::ModeThemeColors>,
 ) -> state::Palette {
     let mut palette = state::Palette::from_name(name).unwrap_or_else(|| {
         tracing::warn!(
@@ -336,6 +337,9 @@ fn resolve_palette_for_theme_name(
     if let Some(accent) = &runtime.legacy_accent {
         palette.accent = crate::config::parse_color(accent);
     }
+    if let Some(custom) = mode_custom {
+        palette = palette.with_mode_overrides(custom);
+    }
 
     palette
 }
@@ -344,18 +348,30 @@ fn resolve_effective_theme(
     runtime: &state::ThemeRuntimeConfig,
     appearance: Option<crate::terminal_theme::HostAppearance>,
 ) -> (state::Palette, String) {
-    let (name, fallback) = if runtime.auto_switch {
+    let (name, fallback, mode_custom) = if runtime.auto_switch {
         match appearance.unwrap_or(crate::terminal_theme::HostAppearance::Dark) {
-            crate::terminal_theme::HostAppearance::Dark => (&runtime.dark_name, "catppuccin"),
-            crate::terminal_theme::HostAppearance::Light => {
-                (&runtime.light_name, "catppuccin-latte")
-            }
+            crate::terminal_theme::HostAppearance::Dark => (
+                &runtime.dark_name,
+                "catppuccin",
+                runtime
+                    .custom
+                    .as_ref()
+                    .and_then(|custom| custom.dark.as_ref()),
+            ),
+            crate::terminal_theme::HostAppearance::Light => (
+                &runtime.light_name,
+                "catppuccin-latte",
+                runtime
+                    .custom
+                    .as_ref()
+                    .and_then(|custom| custom.light.as_ref()),
+            ),
         }
     } else {
-        (&runtime.manual_name, "catppuccin")
+        (&runtime.manual_name, "catppuccin", None)
     };
     (
-        resolve_palette_for_theme_name(name, fallback, runtime),
+        resolve_palette_for_theme_name(name, fallback, runtime, mode_custom),
         name.clone(),
     )
 }
@@ -2730,6 +2746,50 @@ mod tests {
         );
     }
 
+    #[test]
+    fn theme_auto_switch_layers_active_mode_overrides_last() {
+        let mut config = Config::default();
+        config.theme.name = Some("gruvbox".to_string());
+        config.theme.auto_switch = true;
+        config.theme.custom = Some(crate::config::CustomThemeColors {
+            accent: Some("#010203".to_string()),
+            text: Some("#040506".to_string()),
+            light: Some(crate::config::ModeThemeColors {
+                accent: Some("#070809".to_string()),
+                ..Default::default()
+            }),
+            dark: Some(crate::config::ModeThemeColors {
+                text: Some("#0a0b0c".to_string()),
+                sidebar_bg: Some("#0d0e0f".to_string()),
+                ..Default::default()
+            }),
+            ..Default::default()
+        });
+        let (_api_tx, api_rx) = tokio::sync::mpsc::unbounded_channel();
+        let mut app = App::new(&config, true, None, api_rx, crate::api::EventHub::default());
+
+        assert_eq!(
+            app.state.palette.accent,
+            ratatui::style::Color::Rgb(1, 2, 3)
+        );
+        assert_eq!(
+            app.state.palette.text,
+            ratatui::style::Color::Rgb(10, 11, 12)
+        );
+        assert_eq!(
+            app.state.palette.sidebar_bg,
+            ratatui::style::Color::Rgb(13, 14, 15)
+        );
+
+        app.set_host_terminal_appearance(crate::terminal_theme::HostAppearance::Light, true);
+
+        assert_eq!(
+            app.state.palette.accent,
+            ratatui::style::Color::Rgb(7, 8, 9)
+        );
+        assert_eq!(app.state.palette.text, ratatui::style::Color::Rgb(4, 5, 6));
+    }
+
     #[test]
     fn inferred_background_appearance_does_not_override_explicit_report() {
         let mut config = Config::default();
diff --git a/src/app/state.rs b/src/app/state.rs
index ca1b919b9f..e7078cf4a4 100644
--- a/src/app/state.rs
+++ b/src/app/state.rs
@@ -637,6 +637,62 @@ impl Palette {
         }
         self
     }
+
+    pub fn with_mode_overrides(mut self, custom: &crate::config::ModeThemeColors) -> Self {
+        use crate::config::parse_color;
+        if let Some(c) = &custom.accent {
+            self.accent = parse_color(c);
+        }
+        if let Some(c) = &custom.panel_bg {
+            self.panel_bg = parse_color(c);
+        }
+        if let Some(c) = &custom.sidebar_bg {
+            self.sidebar_bg = parse_color(c);
+        }
+        if let Some(c) = &custom.surface0 {
+            self.surface0 = parse_color(c);
+        }
+        if let Some(c) = &custom.surface1 {
+            self.surface1 = parse_color(c);
+        }
+        if let Some(c) = &custom.surface_dim {
+            self.surface_dim = parse_color(c);
+        }
+        if let Some(c) = &custom.overlay0 {
+            self.overlay0 = parse_color(c);
+        }
+        if let Some(c) = &custom.overlay1 {
+            self.overlay1 = parse_color(c);
+        }
+        if let Some(c) = &custom.text {
+            self.text = parse_color(c);
+        }
+        if let Some(c) = &custom.subtext0 {
+            self.subtext0 = parse_color(c);
+        }
+        if let Some(c) = &custom.mauve {
+            self.mauve = parse_color(c);
+        }
+        if let Some(c) = &custom.green {
+            self.green = parse_color(c);
+        }
+        if let Some(c) = &custom.yellow {
+            self.yellow = parse_color(c);
+        }
+        if let Some(c) = &custom.red {
+            self.red = parse_color(c);
+        }
+        if let Some(c) = &custom.blue {
+            self.blue = parse_color(c);
+        }
+        if let Some(c) = &custom.teal {
+            self.teal = parse_color(c);
+        }
+        if let Some(c) = &custom.peach {
+            self.peach = parse_color(c);
+        }
+        self
+    }
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
diff --git a/src/config.rs b/src/config.rs
index 858ca63239..212a8821a2 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -30,7 +30,7 @@ pub use self::{
         SpaceSidebarToken, SpacesSidebarConfig,
     },
     sound::SoundConfig,
-    theme::{parse_color, CustomThemeColors, ThemeConfig, THEME_NAMES},
+    theme::{parse_color, CustomThemeColors, ModeThemeColors, ThemeConfig, THEME_NAMES},
 };
 
 pub(crate) use self::keybinds::parse_key_combo;
diff --git a/src/config/theme.rs b/src/config/theme.rs
index e89fe99cca..8af920a29e 100644
--- a/src/config/theme.rs
+++ b/src/config/theme.rs
@@ -117,6 +117,33 @@ pub struct CustomThemeColors {
     pub blue: Option<String>,
     pub teal: Option<String>,
     pub peach: Option<String>,
+    /// Overrides applied when `auto_switch` selects a light appearance.
+    pub light: Option<ModeThemeColors>,
+    /// Overrides applied when `auto_switch` selects a dark appearance.
+    pub dark: Option<ModeThemeColors>,
+}
+
+/// Per-token color overrides for one auto-switch appearance.
+#[derive(Debug, Clone, Default, Deserialize)]
+#[serde(default)]
+pub struct ModeThemeColors {
+    pub accent: Option<String>,
+    pub panel_bg: Option<String>,
+    pub sidebar_bg: Option<String>,
+    pub surface0: Option<String>,
+    pub surface1: Option<String>,
+    pub surface_dim: Option<String>,
+    pub overlay0: Option<String>,
+    pub overlay1: Option<String>,
+    pub text: Option<String>,
+    pub subtext0: Option<String>,
+    pub mauve: Option<String>,
+    pub green: Option<String>,
+    pub yellow: Option<String>,
+    pub red: Option<String>,
+    pub blue: Option<String>,
+    pub teal: Option<String>,
+    pub peach: Option<String>,
 }
 
 /// Parse a color string into a ratatui Color.
@@ -277,6 +304,31 @@ red = "rgb(255, 85, 85)"
         assert!(custom.green.is_none());
     }
 
+    #[test]
+    fn theme_custom_mode_overrides_parse() {
+        let toml = r##"
+[theme.custom]
+accent = "#010203"
+
+[theme.custom.light]
+accent = "#040506"
+text = "#070809"
+
+[theme.custom.dark]
+panel_bg = "#0a0b0c"
+sidebar_bg = "#0d0e0f"
+"##;
+        let config: Config = toml::from_str(toml).unwrap();
+        let custom = config.theme.custom.as_ref().unwrap();
+        assert_eq!(custom.accent.as_deref(), Some("#010203"));
+        let light = custom.light.as_ref().unwrap();
+        assert_eq!(light.accent.as_deref(), Some("#040506"));
+        assert_eq!(light.text.as_deref(), Some("#070809"));
+        let dark = custom.dark.as_ref().unwrap();
+        assert_eq!(dark.panel_bg.as_deref(), Some("#0a0b0c"));
+        assert_eq!(dark.sidebar_bg.as_deref(), Some("#0d0e0f"));
+    }
+
     #[test]
     fn theme_defaults_when_missing() {
         let config: Config = toml::from_str("").unwrap();
diff --git a/src/main.rs b/src/main.rs
index 7f79730d54..cbb86d5e3d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -134,6 +134,15 @@ const DEFAULT_CONFIG: &str = r##"# herdr configuration
 # red = "#ff6188"
 # green = "#a6e3a1"
 
+# Layer appearance-specific overrides on top when auto_switch is enabled.
+# [theme.custom.light]
+# panel_bg = "#eff1f5"
+# text = "#4c4f69"
+#
+# [theme.custom.dark]
+# panel_bg = "#1e1e2e"
+# text = "#cdd6f4"
+
 [terminal]
 # Executable used for new interactive panes.
 # Empty means $SHELL, then /bin/sh.