diff --git a/docs/manual/release-notes/rl-26.12.md b/docs/manual/release-notes/rl-26.12.md
index 91d10fd3f..3a307aea2 100644
--- a/docs/manual/release-notes/rl-26.12.md
+++ b/docs/manual/release-notes/rl-26.12.md
@@ -7,6 +7,13 @@
 - Dropping all old deprecations from 26.07 backwards. This is done to keep the
   codebase maintainable.
 
+- `theme`: replace the single-theme configuration with `vim.theme.themes` and
+  `vim.theme.default`. The legacy `name`, `style`, and `transparent` options
+  remain available temporarily with a migration warning.
+
+  Catppuccin integrations are now opt-in through
+  `vim.theme.catppuccin.integrations.<plugin>.enable`.
+
 [snoweuph](https://github.com/snoweuph)
 
 - splitting `languages/json5` from `languages/json`, because most `json` and
diff --git a/modules/plugins/lsp/lspsaga/lspsaga.nix b/modules/plugins/lsp/lspsaga/lspsaga.nix
index f70c8c9d0..39ce62980 100644
--- a/modules/plugins/lsp/lspsaga/lspsaga.nix
+++ b/modules/plugins/lsp/lspsaga/lspsaga.nix
@@ -6,16 +6,6 @@
   inherit (lib.modules) mkRemovedOptionModule;
   inherit (lib.options) mkOption mkEnableOption;
   inherit (lib.nvim.types) borderType mkPluginSetupOption;
-  inherit (lib.nvim.lua) mkLuaInline;
-
-  uiKindSetupOpts =
-    if config.vim.theme.enable && config.vim.theme.name == "catppuccin"
-    then {
-      ui.kind = mkLuaInline ''
-        require("catppuccin.groups.integrations.lsp_saga").custom_kind()
-      '';
-    }
-    else {};
 in {
   imports = [
     (mkRemovedOptionModule ["vim" "lsp" "lspsaga" "mappings"] ''
@@ -31,14 +21,12 @@ in {
   options.vim.lsp.lspsaga = {
     enable = mkEnableOption "LSP Saga";
 
-    setupOpts =
-      mkPluginSetupOption "lspsaga" {
-        border_style = mkOption {
-          type = borderType;
-          default = config.vim.ui.borders.globalStyle;
-          description = "Border type, see {command}`:help nvim_open_win`";
-        };
-      }
-      // uiKindSetupOpts;
+    setupOpts = mkPluginSetupOption "lspsaga" {
+      border_style = mkOption {
+        type = borderType;
+        default = config.vim.ui.borders.globalStyle;
+        description = "Border type, see {command}`:help nvim_open_win`";
+      };
+    };
   };
 }
diff --git a/modules/plugins/statusline/lualine/lualine.nix b/modules/plugins/statusline/lualine/lualine.nix
index 3411749c5..4a55eee1e 100644
--- a/modules/plugins/statusline/lualine/lualine.nix
+++ b/modules/plugins/statusline/lualine/lualine.nix
@@ -3,10 +3,8 @@
   lib,
   ...
 }: let
-  inherit (builtins) elem;
   inherit (lib.options) mkOption mkEnableOption;
   inherit (lib.types) int bool str listOf enum;
-  inherit (lib.lists) optional;
   inherit (lib.nvim.types) mkPluginSetupOption;
 
   supported_themes = import ./supported_themes.nix;
@@ -124,16 +122,11 @@ in {
       '';
     };
 
-    theme = let
-      themeSupported = elem config.vim.theme.name supported_themes;
-      themesConcatted = builtin_themes ++ optional themeSupported config.vim.theme.name;
-    in
-      mkOption {
-        type = enum themesConcatted;
-        default = "auto";
-        defaultText = ''`config.vim.theme.name` if theme supports lualine else "auto"'';
-        description = "Theme for lualine";
-      };
+    theme = mkOption {
+      type = enum (builtin_themes ++ supported_themes);
+      default = "auto";
+      description = "Theme for lualine";
+    };
 
     sectionSeparator = {
       left = mkOption {
diff --git a/modules/plugins/tabline/nvim-bufferline/nvim-bufferline.nix b/modules/plugins/tabline/nvim-bufferline/nvim-bufferline.nix
index 4f33ed860..fcaca9a1d 100644
--- a/modules/plugins/tabline/nvim-bufferline/nvim-bufferline.nix
+++ b/modules/plugins/tabline/nvim-bufferline/nvim-bufferline.nix
@@ -3,7 +3,7 @@
   lib,
   ...
 }: let
-  inherit (lib.options) mkOption mkEnableOption literalExpression literalMD;
+  inherit (lib.options) mkOption mkEnableOption literalExpression;
   inherit (lib.types) enum bool either nullOr str int listOf attrs;
   inherit (lib.generators) mkLuaInline;
   inherit (lib.nvim.types) mkPluginSetupOption luaInline;
@@ -27,25 +27,7 @@ in {
     setupOpts = mkPluginSetupOption "bufferline-nvim" {
       highlights = mkOption {
         type = either attrs luaInline;
-        default =
-          if config.vim.theme.enable && config.vim.theme.name == "catppuccin"
-          then
-            mkLuaInline ''
-              (function()
-                local integration = require("catppuccin.special.bufferline")
-                return (integration.get_theme or integration.get)()
-              end)()
-            ''
-          else {};
-        defaultText = literalMD ''
-          ```lua
-          (function()
-            local integration = require("catppuccin.special.bufferline")
-            return (integration.get_theme or integration.get)()
-          end)()
-          ```
-          if the active theme is Catppuccin, `{}` otherwise.
-        '';
+        default = {};
         description = ''
           Overrides the highlight groups of bufferline.
 
diff --git a/modules/plugins/theme/supported-themes.nix b/modules/plugins/theme/supported-themes.nix
index 14ebc9360..923a217b1 100644
--- a/modules/plugins/theme/supported-themes.nix
+++ b/modules/plugins/theme/supported-themes.nix
@@ -8,34 +8,31 @@
   inherit (lib.trivial) boolToString warnIf;
   inherit (lib.nvim.lua) toLuaObject;
 in {
+  # FIXME: those all need to be converted to setupOpts format
+  # or else we explode...
   base16 = {
-    setup = {base16-colors, ...}: ''
+    setup = setupOpts: ''
       -- Base16 theme
-      require('base16-colorscheme').setup(${toLuaObject base16-colors})
+      require('base16-colorscheme').setup(${toLuaObject setupOpts})
     '';
   };
+
   mini-base16 = {
-    setup = {base16-colors, ...}: ''
+    setup = setupOpts: ''
       -- Base16 theme
       require('mini.base16').setup({
-        palette = ${toLuaObject base16-colors}
+        palette = ${toLuaObject setupOpts}
       })
     '';
   };
+
   onedark = {
-    setup = {
-      style ? "dark",
-      transparent,
-      ...
-    }: ''
+    styles = ["dark" "darker" "cool" "deep" "warm" "warmer"];
+    setup = setupOpts: ''
       -- OneDark theme
-      require('onedark').setup {
-        transparent = ${boolToString transparent},
-        style = "${style}"
-      }
+      require('onedark').setup(${toLuaObject setupOpts})
       require('onedark').load()
     '';
-    styles = ["dark" "darker" "cool" "deep" "warm" "warmer"];
   };
   gruber-darker = {
     setup = _: ''
@@ -62,81 +59,30 @@ in {
   };
 
   tokyonight = {
-    setup = {
-      style ? "night",
-      transparent,
-      ...
-    }: ''
-      require('tokyonight').setup {
-        transparent = ${boolToString transparent};
-        styles = {
-          sidebars = ${
-        if transparent
-        then ''"transparent"''
-        else ''"dark"''
-      },
-          floats = ${
-        if transparent
-        then ''"transparent"''
-        else ''"dark"''
-      },
-        },
-      }
-      vim.cmd[[colorscheme tokyonight-${style}]]
-    '';
     styles = ["day" "night" "storm" "moon"];
+    setup = setupOpts: ''
+      require('tokyonight').setup(${toLuaObject setupOpts})
+      vim.cmd[[colorscheme tokyonight-${setupOpts.style or "night"}]]
+    '';
   };
 
   dracula = {
-    setup = {transparent, ...}: ''
-      require('dracula').setup({
-        transparent_bg = ${boolToString transparent},
-      });
+    setup = setupOpts: let
+      cleanedOpts =
+        (removeAttrs setupOpts ["transparent"])
+        // {
+          transparent_bg = setupOpts.transparent or false;
+        };
+    in ''
+      require('dracula').setup(${toLuaObject cleanedOpts});
       require('dracula').load();
     '';
   };
 
   catppuccin = {
-    setup = {
-      style ? "mocha",
-      transparent ? false,
-      ...
-    }: ''
+    setup = setupOpts: ''
       -- Catppuccin theme
-      require('catppuccin').setup {
-        flavour = "${style}",
-        transparent_background = ${boolToString transparent},
-        float = {
-          transparent = ${boolToString transparent},
-        },
-        term_colors = true,
-        integrations = {
-          nvimtree = {
-            enabled = true,
-            transparent_panel = ${boolToString transparent},
-            show_root = true,
-          },
-
-          hop = true,
-          gitsigns = true,
-          telescope = true,
-          treesitter = true,
-          treesitter_context = true,
-          ts_rainbow = true,
-          fidget = true,
-          alpha = true,
-          leap = true,
-          lsp_saga = true,
-          markdown = true,
-          noice = true,
-          notify = true, -- nvim-notify
-          which_key = true,
-          navic = {
-            enabled = true,
-            custom_bg = "NONE", -- "lualine" will set background to mantle
-          },
-        },
-      }
+      require('catppuccin').setup(${toLuaObject setupOpts})
       -- setup must be called before loading
       vim.cmd.colorscheme "catppuccin"
     '';
@@ -144,17 +90,14 @@ in {
   };
 
   oxocarbon = {
-    setup = {
-      style ? "dark",
-      transparent ? false,
-      ...
-    }: let
-      style' =
-        warnIf (style == "light") "oxocarbon: light theme is not well-supported" style;
+    setup = setupOpts: let
+      style = setupOpts.style or "dark";
+      style' = warnIf (style == "light") "oxocarbon: light theme is not well-supported" style;
+      transparent = setupOpts.transparent or false;
     in ''
       require('oxocarbon')
       vim.opt.background = "${style'}"
-      vim.cmd.colorscheme = "oxocarbon"
+      vim.cmd.colorscheme "oxocarbon"
       ${optionalString transparent ''
         vim.api.nvim_set_hl(0, "Normal", { bg = "none" })
         vim.api.nvim_set_hl(0, "NormalFloat", { bg = "none" })
@@ -169,93 +112,99 @@ in {
   };
 
   gruvbox = {
-    setup = {
-      style ? "dark",
-      transparent ? false,
-      ...
-    }: ''
+    setup = setupOpts: let
+      cleanedOpts =
+        (removeAttrs setupOpts ["transparent" "style"])
+        // {
+          terminal_colors = true; # add neovim terminal colors
+          undercurl = true;
+          underline = true;
+          bold = true;
+          italic = {
+            strings = true;
+            emphasis = true;
+            comments = true;
+            operators = false;
+            folds = true;
+          };
+          strikethrough = true;
+          invert_selection = false;
+          invert_signs = false;
+          invert_tabline = false;
+          invert_intend_guides = false;
+          inverse = true;
+          contrast = "";
+          palette_overrides = {};
+          overrides = {};
+          dim_inactive = false;
+          transparent_mode = setupOpts.transparent or false;
+        };
+      style = setupOpts.style or "dark";
+    in ''
+          styles = ["dark" "light"];
       -- Gruvbox theme
-      require("gruvbox").setup({
-        terminal_colors = true, -- add neovim terminal colors
-        undercurl = true,
-        underline = true,
-        bold = true,
-        italic = {
-        strings = true,
-        emphasis = true,
-        comments = true,
-        operators = false,
-        folds = true,
-        },
-        strikethrough = true,
-        invert_selection = false,
-        invert_signs = false,
-        invert_tabline = false,
-        invert_intend_guides = false,
-        inverse = true,
-        contrast = "",
-        palette_overrides = {},
-        overrides = {},
-        dim_inactive = false,
-        transparent_mode = ${boolToString transparent},
-      })
+      require("gruvbox").setup(${toLuaObject cleanedOpts})
       vim.o.background = "${style}"
       vim.cmd("colorscheme gruvbox")
     '';
-    styles = ["dark" "light"];
   };
-  rose-pine = {
-    setup = {
-      style ? "main",
-      transparent ? false,
-      ...
-    }: ''
-      require("rose-pine").setup({
-        dark_variant = "${style}", -- main, moon, or dawn
-        dim_inactive_windows = false,
-        extend_background_behind_borders = true,
 
-        enable = {
-          terminal = true,
-          migrations = true,
-        },
+  rose-pine = {
+    setup = setupOpts: let
+      cleanedOpts =
+        (removeAttrs setupOpts ["style" "transparent"])
+        // {
+          dark_variant = setupOpts.style or "main"; # main, moon, or dawn
+          dim_inactive_windows = false;
+          extend_background_behind_borders = true;
 
-        styles = {
-          bold = false,
-          italic = false, -- I would like to add more options for this
-          transparency = ${boolToString transparent},
-        },
-      })
+          enable = {
+            terminal = true;
+            migrations = true;
+          };
 
+          styles = {
+            bold = false;
+            italic = false; # I would like to add more options for this
+            transparency = setupOpts.transparent or false;
+          };
+        };
+    in ''
+      require("rose-pine").setup(${toLuaObject cleanedOpts})
       vim.cmd("colorscheme rose-pine")
     '';
     styles = ["main" "moon" "dawn"];
   };
-  nord = {
-    setup = {transparent ? false, ...}: ''
-      require("nord").setup({
-        transparent = ${boolToString transparent},
-        search = "vscode", -- [vim|vscode]
-      })
 
+  nord = {
+    setup = setupOpts: let
+      cleanedOpts =
+        (removeAttrs setupOpts ["transparent"])
+        // {
+          transparent = setupOpts.transparent or false;
+          search = "vscode"; # [vim|vscode]
+        };
+    in ''
+      require("nord").setup(${toLuaObject cleanedOpts})
       vim.cmd.colorscheme("nord")
     '';
   };
-  github = {
-    setup = {
-      style ? "dark",
-      transparent ? false,
-      ...
-    }: ''
-      require('github-theme').setup({
-        options = {
-          transparent = ${boolToString transparent},
-        },
-      })
 
+  github = {
+    styles = ["dark" "light" "dark_dimmed" "dark_default" "light_default" "dark_high_contrast" "light_high_contrast" "dark_colorblind" "light_colorblind" "dark_tritanopia" "light_tritanopia"];
+    setup = setupOpts: let
+      cleanedOpts =
+        (removeAttrs setupOpts ["transparent" "style"])
+        // {
+          options = {
+            transparent = setupOpts.transparent or false;
+          };
+        };
+      style = setupOpts.style or "dark";
+    in ''
+      require('github-theme').setup(${toLuaObject cleanedOpts})
       vim.cmd[[colorscheme github_${style}]]
     '';
-    styles = ["dark" "light" "dark_dimmed" "dark_default" "light_default" "dark_high_contrast" "light_high_contrast" "dark_colorblind" "light_colorblind" "dark_tritanopia" "light_tritanopia"];
   };
 
   solarized = let
@@ -263,11 +212,8 @@ in {
     palettes = ["solarized" "selenized"];
     variants = ["spring" "summer" "autumn" "winter"];
   in {
-    setup = {
-      style ? "", # use plugin defaults
-      transparent ? false,
-      ...
-    }: let
+    setup = setupOpts: let
+      style = setupOpts.style or "";
       parts = splitString "-" style;
       detect = list: let
         intersection = intersectLists parts list;
@@ -278,15 +224,28 @@ in {
       background = detect backgrounds;
       palette = detect palettes;
       variant = detect variants;
+      baseSetup =
+        {
+          transparent = {
+            enabled = setupOpts.transparent or false;
+          };
+        }
+        // (removeAttrs setupOpts ["style" "transparent"]);
+      finalSetup =
+        baseSetup
+        // (
+          if palette != null
+          then {palette = palette;}
+          else {}
+        )
+        // (
+          if variant != null
+          then {variant = variant;}
+          else {}
+        );
     in ''
       -- Solarized theme
-      require('solarized').setup {
-        transparent = {
-          enabled = ${boolToString transparent},
-        },
-        ${optionalString (palette != null) ''palette = "${palette}",''}
-        ${optionalString (variant != null) ''variant = "${variant}",''}
-      }
+      require('solarized').setup(${toLuaObject finalSetup})
       ${optionalString (background != null) ''vim.opt.background = "${background}"''}
       vim.cmd.colorscheme "solarized"
     '';
@@ -307,25 +266,28 @@ in {
   };
 
   solarized-osaka = {
-    setup = {transparent ? false, ...}: ''
-      require("solarized-osaka").setup({
-        transparent = ${boolToString transparent},
-        styles = {
-          comments = { italic = false },
-          keywords = { italic = false },
-        }
-      })
-
+    setup = setupOpts: let
+      cleanedOpts =
+        (removeAttrs setupOpts ["transparent"])
+        // {
+          transparent = setupOpts.transparent or false;
+          styles = {
+            comments = {italic = false;};
+            keywords = {italic = false;};
+          };
+        };
+    in ''
+      require("solarized-osaka").setup(${toLuaObject cleanedOpts})
       vim.cmd.colorscheme("solarized-osaka")
     '';
   };
 
   everforest = {
-    setup = {
-      style ? "medium",
-      transparent ? false,
-      ...
-    }: ''
+    styles = ["hard" "medium" "soft"];
+    setup = setupOpts: let
+      style = setupOpts.style or "medium";
+      transparent = setupOpts.transparent or false;
+    in ''
       vim.g.everforest_background = "${style}"
       vim.g.everforest_transparent_background = ${
         if transparent
@@ -335,8 +297,6 @@ in {
 
       vim.cmd.colorscheme("everforest")
     '';
-
-    styles = ["hard" "medium" "soft"];
   };
 
   mellow = {
diff --git a/modules/plugins/theme/theme.nix b/modules/plugins/theme/theme.nix
index d670c5554..6f4d4fd56 100644
--- a/modules/plugins/theme/theme.nix
+++ b/modules/plugins/theme/theme.nix
@@ -4,13 +4,13 @@
   ...
 }: let
   inherit (lib.options) mkOption mkEnableOption;
-  inherit (lib.attrsets) attrNames;
+  inherit (lib.modules) mkIf mkMerge;
+  inherit (lib.types) bool lines enum submodule attrsOf nullOr;
+  inherit (lib.attrsets) attrNames filterAttrs;
   inherit (lib.strings) hasPrefix;
-  inherit (lib.types) bool lines enum;
-  inherit (lib.modules) mkIf;
   inherit (lib.nvim.attrsets) mapListToAttrs;
   inherit (lib.nvim.dag) entryBefore;
-  inherit (lib.nvim.types) hexColor;
+  inherit (lib.nvim.types) hexColor mkPluginSetupOption;
 
   cfg = config.vim.theme;
   supportedThemes = import ./supported-themes.nix {
@@ -31,42 +31,342 @@
       };
     })
     numbers;
+
+  # Get all enabled themes
+  enabledThemes = filterAttrs (_: themeCfg: themeCfg.enable) cfg.themes;
+  nonDefaultThemes = filterAttrs (name: _: name != cfg.default) enabledThemes;
+  newConfigUsed = enabledThemes != {};
+  catppuccinIntegrationNames = [
+    "aerial"
+    "alpha"
+    "blink_cmp"
+    "bufferline"
+    "cmp"
+    "dap"
+    "dap_ui"
+    "dashboard"
+    "diffview"
+    "fidget"
+    "flash"
+    "gitsigns"
+    "grug_far"
+    "harpoon"
+    "hop"
+    "indent_blankline"
+    "leap"
+    "lsp_saga"
+    "lsp_trouble"
+    "mini"
+    "neogit"
+    "neotree"
+    "navic"
+    "noice"
+    "notify"
+    "nvim_surround"
+    "nvimtree"
+    "telescope"
+    "treesitter"
+    "treesitter_context"
+    "ufo"
+    "which_key"
+  ];
+  tokyonightIntegrationNames = [
+    "aerial"
+    "alpha"
+    "blink"
+    "bufferline"
+    "copilot"
+    "dashboard"
+    "flash"
+    "gitsigns"
+    "grug-far"
+    "hop"
+    "indent-blankline"
+    "leap"
+    "lspsaga"
+    "neo-tree"
+    "neogit"
+    "noice"
+    "cmp"
+    "dap"
+    "navic"
+    "notify"
+    "nvim-tree"
+    "snacks"
+    "supermaven"
+    "telescope"
+    "treesitter-context"
+    "trouble"
+    "which-key"
+  ];
+  hasEnabledIntegration = integrations: builtins.any (integration: integration.enable) (builtins.attrValues integrations);
+  themeIntegrationEnabled = theme: integrations:
+    cfg.enable
+    && cfg.default == theme
+    && (enabledThemes ? ${theme})
+    && hasEnabledIntegration integrations;
+  catppuccinIntegrationEnabled = themeIntegrationEnabled "catppuccin" cfg.catppuccin.integrations;
+  tokyonightIntegrationEnabled = themeIntegrationEnabled "tokyonight" cfg.tokyonight.integrations;
+  solarizedOsakaIntegrationEnabled = themeIntegrationEnabled "solarized-osaka" cfg.solarized-osaka.integrations;
+  catppuccinIntegrations = filterAttrs (name: integration: catppuccinIntegrationEnabled && builtins.elem name catppuccinIntegrationNames && integration.enable) cfg.catppuccin.integrations;
+  tokyonightIntegrations = filterAttrs (name: integration: tokyonightIntegrationEnabled && builtins.elem name tokyonightIntegrationNames && integration.enable) cfg.tokyonight.integrations;
+  solarizedOsakaIntegrations = filterAttrs (name: integration: solarizedOsakaIntegrationEnabled && builtins.elem name tokyonightIntegrationNames && integration.enable) cfg.solarized-osaka.integrations;
+  withPluginIntegrations = themeCfg: integrations:
+    themeCfg.setupOpts
+    // {
+      plugins =
+        {
+          all = themeCfg.setupOpts.plugins.all or false;
+          auto = themeCfg.setupOpts.plugins.auto or false;
+        }
+        // (themeCfg.setupOpts.plugins or {})
+        // lib.mapAttrs (_: _: true) integrations;
+    };
+  themeSetupAdapters = {
+    catppuccin = themeCfg:
+      themeCfg.setupOpts
+      // lib.optionalAttrs (!(themeCfg.setupOpts ? default_integrations)) {
+        default_integrations = false;
+      }
+      // lib.optionalAttrs (catppuccinIntegrations != {}) {
+        integrations = (themeCfg.setupOpts.integrations or {}) // lib.mapAttrs (_: _: true) catppuccinIntegrations;
+      };
+    tokyonight = themeCfg: withPluginIntegrations themeCfg tokyonightIntegrations;
+    solarized-osaka = themeCfg: withPluginIntegrations themeCfg solarizedOsakaIntegrations;
+  };
+  themeSetupOpts = name: themeCfg: (themeSetupAdapters.${name} or (x: x.setupOpts)) themeCfg;
+
+  # Get the default theme configuration
+  defaultTheme =
+    if cfg.default != null && enabledThemes ? ${cfg.default}
+    then enabledThemes.${cfg.default}
+    else null;
 in {
   options.vim.theme = {
     enable = mkEnableOption "theming";
+
+    default = mkOption {
+      type = nullOr (enum (attrNames supportedThemes));
+      default = null;
+      description = ''
+        The default theme to load in the built configuration. While this option
+        is set and the matching theme is enabled in {option}`vim.theme.themes`
+        the theme specified by this option will be set automatically as the
+        default theme. If `null`, the user is responsible for setting their
+        preferred theme either by explicitly setting this option, or using Lua.
+      '';
+    };
+
+    themes = let
+      themeType = {name, ...}: {
+        options = {
+          enable = mkEnableOption "the ${name} theme";
+          setupOpts = mkPluginSetupOption name {};
+        };
+      };
+    in
+      mkOption {
+        type = attrsOf (submodule themeType);
+        default = {};
+        example = {
+          tokyonight = {
+            enable = true;
+            setupOpts = {
+              style = "night";
+              transparent = true;
+            };
+          };
+
+          catppuccin = {
+            enable = true;
+            setupOpts = {
+              flavour = "mocha";
+              transparent_background = true;
+              integrations = {
+                nvimtree = {
+                  enabled = true;
+                  transparent_panel = true;
+                };
+                telescope = true;
+                treesitter = true;
+              };
+            };
+          };
+
+          onedark = {
+            enable = false; # Available but not loaded
+            setupOpts = {
+              style = "darker";
+              transparent = false;
+            };
+          };
+        };
+
+        description = ''
+          Configure multiple themes at once. All enabled themes are loaded in
+          the configuration. While {option}`vim.theme.default` is set, that
+          theme is selected automatically.
+        '';
+      };
+
+    catppuccin.integrations =
+      {
+        lualine.enable = mkEnableOption "the Catppuccin lualine integration";
+      }
+      // mapListToAttrs (name: {
+        inherit name;
+        value.enable = mkEnableOption "the Catppuccin ${name} integration";
+      })
+      catppuccinIntegrationNames;
+
+    tokyonight.integrations =
+      {
+        lualine.enable = mkEnableOption "the TokyoNight lualine integration";
+      }
+      // mapListToAttrs (name: {
+        inherit name;
+        value.enable = mkEnableOption "the TokyoNight ${name} integration";
+      })
+      tokyonightIntegrationNames;
+
+    solarized-osaka.integrations =
+      mapListToAttrs (name: {
+        inherit name;
+        value.enable = mkEnableOption "the Solarized Osaka ${name} integration";
+      })
+      tokyonightIntegrationNames;
+
+    # Legacy options for backwards compatibility
+    # FIXME: this could have been handled directly with mkRenamedOptionModule
+    # or similar, but I found it too difficult to handle it gracefully. Those
+    # are kept here **with a warning** but without completely removing the
+    # relevant options. Worth completely dropping in the future.
     name = mkOption {
       type = enum (attrNames supportedThemes);
+      default = "onedark";
       description = ''
         Supported themes can be found in {file}`supportedThemes.nix`.
         Setting the theme to "base16" enables base16 theming and
         requires all of the colors in {option}`vim.theme.base16-colors` to be set.
       '';
     };
-    base16-colors = base16Options;
 
     style = mkOption {
       type = enum supportedThemes.${cfg.name}.styles;
+      default = builtins.head supportedThemes.${cfg.name}.styles;
       description = "Specific style for theme if it supports it";
     };
+
     transparent = mkOption {
       type = bool;
       default = false;
       description = "Whether or not transparency should be enabled. Has no effect for themes that do not support transparency";
     };
 
+    base16-colors = base16Options;
+
     extraConfig = mkOption {
       type = lines;
-      description = "Additional lua configuration to add before setup";
+      default = "";
+      description = "Additional Lua configuration to add before setup";
     };
   };
 
-  config = mkIf cfg.enable {
-    vim = {
-      startPlugins = [cfg.name];
-      luaConfigRC.theme = entryBefore ["pluginConfigs" "lazyConfigs"] ''
-        ${cfg.extraConfig}
-        ${supportedThemes.${cfg.name}.setup {inherit (cfg) style transparent base16-colors;}}
-      '';
-    };
-  };
+  config = mkMerge [
+    {
+      assertions = [
+        {
+          assertion = !cfg.enable -> cfg.default == null;
+          message = "vim.theme.default requires vim.theme.enable.";
+        }
+        {
+          assertion = cfg.default == null || (enabledThemes ? ${cfg.default});
+          message = "vim.theme.default must name an enabled theme.";
+        }
+        {
+          assertion = !hasEnabledIntegration cfg.catppuccin.integrations || catppuccinIntegrationEnabled;
+          message = "Catppuccin integrations require Catppuccin to be the enabled default theme.";
+        }
+        {
+          assertion = !hasEnabledIntegration cfg.tokyonight.integrations || tokyonightIntegrationEnabled;
+          message = "TokyoNight integrations require TokyoNight to be the enabled default theme.";
+        }
+        {
+          assertion = !hasEnabledIntegration cfg.solarized-osaka.integrations || solarizedOsakaIntegrationEnabled;
+          message = "Solarized Osaka integrations require Solarized Osaka to be the enabled default theme.";
+        }
+      ];
+    }
+    (mkIf cfg.enable {
+      vim = {
+        startPlugins =
+          attrNames enabledThemes
+          ++ lib.optional (!newConfigUsed) cfg.name;
+
+        luaConfigRC.theme = entryBefore ["pluginConfigs" "lazyConfigs"] ''
+          -- Theme configurations
+          ${cfg.extraConfig}
+
+          ${lib.concatStringsSep "\n" (lib.mapAttrsToList (
+              themeName: themeCfg: ''
+                -- Setup ${themeName} theme
+                ${supportedThemes.${themeName}.setup (themeSetupOpts themeName themeCfg)}
+              ''
+            )
+            nonDefaultThemes)}
+
+          ${lib.optionalString (!newConfigUsed) (supportedThemes.${cfg.name}.setup (
+            {
+              inherit (cfg) style transparent;
+            }
+            // lib.optionalAttrs (cfg.name == "base16" || cfg.name == "mini-base16") {
+              inherit (cfg) base16-colors;
+            }
+          ))}
+
+          ${lib.optionalString (defaultTheme != null) (supportedThemes.${cfg.default}.setup (themeSetupOpts cfg.default defaultTheme))}
+        '';
+      };
+
+      warnings = let
+        legacyUsed =
+          cfg.name
+          != "onedark"
+          || cfg.style != builtins.head supportedThemes.${cfg.name}.styles
+          || cfg.transparent
+          || cfg.extraConfig != "";
+      in
+        mkIf (legacyUsed && !newConfigUsed) [
+          ''
+            The theming module has been refactored to allow more powerful configurations  and multiple theme setups
+            through the module system. This warning indicates that you are using the legacy API and have not
+            yet used any of the new APIs. Please migrate your configuration to 'vim.theme.themes' API.
+
+            Refer to the documentation for more details.
+          ''
+        ];
+    })
+    (mkIf (catppuccinIntegrationEnabled && cfg.catppuccin.integrations.lualine.enable) {
+      vim.statusline.lualine.theme = lib.mkDefault "catppuccin";
+    })
+    (mkIf (tokyonightIntegrationEnabled && cfg.tokyonight.integrations.lualine.enable) {
+      vim.statusline.lualine.theme = lib.mkDefault "tokyonight";
+    })
+    (mkIf (catppuccinIntegrationEnabled && cfg.catppuccin.integrations.bufferline.enable) {
+      vim.tabline.nvimBufferline.setupOpts.highlights = lib.mkDefault (lib.nvim.lua.mkLuaInline ''
+        (function()
+          local integration = require("catppuccin.special.bufferline")
+          return (integration.get_theme or integration.get)()
+        end)()
+      '');
+    })
+    (mkIf (catppuccinIntegrationEnabled && cfg.catppuccin.integrations.lsp_saga.enable) {
+      vim.lsp.lspsaga.setupOpts.ui.kind = lib.mkDefault (lib.nvim.lua.mkLuaInline ''
+        require("catppuccin.groups.integrations.lsp_saga").custom_kind()
+      '');
+    })
+    (mkIf (catppuccinIntegrationEnabled && cfg.catppuccin.integrations.fidget.enable) {
+      vim.visuals.fidget-nvim.setupOpts.notification.window.winblend = lib.mkDefault 0;
+    })
+  ];
 }