diff --git a/plugins/colorschemes/rose-pine.nix b/plugins/colorschemes/rose-pine.nix
index 9954cac6..b5458810 100644
--- a/plugins/colorschemes/rose-pine.nix
+++ b/plugins/colorschemes/rose-pine.nix
@@ -1,54 +1,141 @@
 {
   lib,
   helpers,
-  config,
   pkgs,
+  config,
   ...
 }:
-with lib; let
-  cfg = config.colorschemes.rose-pine;
-in {
-  options = {
-    colorschemes.rose-pine = {
-      enable = mkEnableOption "rose-pine";
+with lib;
+  helpers.neovim-plugin.mkNeovimPlugin config {
+    name = "rose-pine";
+    isColorscheme = true;
+    defaultPackage = pkgs.vimPlugins.rose-pine;
 
-      package = helpers.mkPackageOption "rose-pine" pkgs.vimPlugins.rose-pine;
+    maintainers = [maintainers.GaetanLepage];
 
-      style = helpers.defaultNullOpts.mkEnumFirstDefault ["main" "moon" "dawn"] "Theme style";
+    # TODO introduced 2024-04-15: remove 2024-06-15
+    optionsRenamedToSettings = [
+      "groups"
+      "highlightGroups"
+    ];
+    imports = let
+      basePluginPath = ["colorschemes" "rose-pine"];
+    in [
+      (
+        mkRenamedOptionModule
+        (basePluginPath ++ ["style"])
+        (basePluginPath ++ ["settings" "dark_variant"])
+      )
+      (
+        mkRenamedOptionModule
+        (basePluginPath ++ ["dimInactive"])
+        (basePluginPath ++ ["settings" "dim_inactive_windows"])
+      )
+      (
+        mkRemovedOptionModule
+        (basePluginPath ++ ["disableItalics"])
+        "Use `colorschemes.rose-pine.settings.enable.italics` instead."
+      )
+      (
+        mkRemovedOptionModule
+        (basePluginPath ++ ["boldVerticalSplit"])
+        "Use `colorschemes.rose-pine.settings.highlight_groups` instead."
+      )
+      (
+        mkRemovedOptionModule
+        (basePluginPath ++ ["transparentFloat"])
+        "Use `colorschemes.rose-pine.settings.highlight_groups.NormalFloat` instead."
+      )
+      (
+        mkRenamedOptionModule
+        (basePluginPath ++ ["transparentBackground"])
+        (basePluginPath ++ ["settings" "enable" "transparency"])
+      )
+    ];
 
-      boldVerticalSplit = helpers.defaultNullOpts.mkBool false "Bolds vertical splits";
+    settingsOptions = {
+      variant = helpers.mkNullOrOption (types.enum ["auto" "main" "moon" "dawn"]) ''
+        Set the desired variant: "auto" will follow the vim background, defaulting to `dark_variant`
+        or "main" for dark and "dawn" for light.
+      '';
 
-      dimInactive = helpers.defaultNullOpts.mkBool false "Dims inactive windows";
+      dark_variant = helpers.defaultNullOpts.mkEnumFirstDefault ["main" "moon" "dawn"] ''
+        Set the desired dark variant when `settings.variant` is set to "auto".
+      '';
 
-      disableItalics = helpers.defaultNullOpts.mkBool false "Disables italics";
+      dim_inactive_windows = helpers.defaultNullOpts.mkBool false ''
+        Differentiate between active and inactive windows and panels.
+      '';
 
-      groups = helpers.mkNullOrOption types.attrs "rose-pine highlight groups";
+      extend_background_behind_borders = helpers.defaultNullOpts.mkBool true ''
+        Extend background behind borders.
+        Appearance differs based on which border characters you are using.
+      '';
 
-      highlightGroups = helpers.mkNullOrOption types.attrs "Custom highlight groups";
+      enable = {
+        legacy_highlights = helpers.defaultNullOpts.mkBool true "Enable legacy highlights.";
 
-      transparentBackground = helpers.defaultNullOpts.mkBool false "Disable setting background";
+        migrations = helpers.defaultNullOpts.mkBool true "Enable migrations.";
 
-      transparentFloat = helpers.defaultNullOpts.mkBool false "Disable setting background for floating windows";
-    };
-  };
-
-  config = mkIf cfg.enable {
-    colorscheme = "rose-pine";
-    extraPlugins = [cfg.package];
-    opts.termguicolors = true;
-    extraConfigLuaPre = let
-      setupOptions = with cfg; {
-        inherit groups;
-        dark_variant = style;
-        bold_vert_split = boldVerticalSplit;
-        disable_background = transparentBackground;
-        disable_float_background = transparentFloat;
-        disable_italics = disableItalics;
-        dim_nc_background = dimInactive;
-        highlight_groups = highlightGroups;
+        terminal = helpers.defaultNullOpts.mkBool true "Enable terminal.";
       };
-    in ''
-      require("rose-pine").setup(${helpers.toLuaObject setupOptions})
-    '';
-  };
-}
+
+      styles = {
+        bold = helpers.defaultNullOpts.mkBool true "Enable bold.";
+
+        italic = helpers.defaultNullOpts.mkBool true "Enable italic.";
+
+        transparency = helpers.defaultNullOpts.mkBool true "Enable transparency.";
+      };
+
+      groups = helpers.mkNullOrOption (with types; attrsOf (either str (attrsOf str))) ''
+        Highlight groups.
+
+        default: see [source](https://github.com/rose-pine/neovim/blob/main/lua/rose-pine/config.lua)
+      '';
+
+      highlight_groups = helpers.defaultNullOpts.mkAttrsOf helpers.nixvimTypes.highlight "{}" ''
+        Custom highlight groups.
+      '';
+
+      before_highlight = helpers.defaultNullOpts.mkLuaFn "function(group, highlight, palette) end" ''
+        Called before each highlight group, before setting the highlight.
+
+        `function(group, highlight, palette)`
+
+        ```lua
+          @param group string
+          @param highlight Highlight
+          @param palette Palette
+        ```
+      '';
+    };
+
+    settingsExample = {
+      variant = "auto";
+      dark_variant = "moon";
+      dim_inactive_windows = true;
+      extend_background_behind_borders = true;
+      enable = {
+        legacy_highlights = false;
+        migrations = true;
+        terminal = false;
+      };
+      styles = {
+        bold = false;
+        italic = true;
+        transparency = true;
+      };
+      groups = {
+        border = "muted";
+        link = "iris";
+        panel = "surface";
+      };
+      highlight_groups = {};
+      before_highlight = "function(group, highlight, palette) end";
+    };
+
+    extraConfig = cfg: {
+      opts.termguicolors = mkDefault true;
+    };
+  }
diff --git a/tests/test-sources/plugins/colorschemes/rose-pine.nix b/tests/test-sources/plugins/colorschemes/rose-pine.nix
index 8a3d0afa..9fc33c03 100644
--- a/tests/test-sources/plugins/colorschemes/rose-pine.nix
+++ b/tests/test-sources/plugins/colorschemes/rose-pine.nix
@@ -6,24 +6,48 @@
   defaults = {
     colorschemes.rose-pine = {
       enable = true;
-      style = "main";
-      boldVerticalSplit = false;
-      dimInactive = false;
-      disableItalics = false;
-      groups = {
-        background = "base";
-        background_nc = "_experimental_nc";
-        panel = "surface";
-        panel_nc = "base";
-        border = "highlight_med";
-        comment = "muted";
-        link = "iris";
-        punctuation = "subtle";
-        error = "love";
-        hint = "iris";
-        info = "foam";
-        warn = "gold";
-        headings = {
+
+      settings = {
+        variant = "auto";
+        dark_variant = "main";
+        dim_inactive_windows = false;
+        extend_background_behind_borders = true;
+
+        enable = {
+          legacy_highlights = true;
+          migrations = true;
+          terminal = true;
+        };
+
+        styles = {
+          bold = true;
+          italic = true;
+          transparency = true;
+        };
+
+        groups = {
+          border = "muted";
+          link = "iris";
+          panel = "surface";
+
+          error = "love";
+          hint = "iris";
+          info = "foam";
+          note = "pine";
+          todo = "rose";
+          warn = "gold";
+
+          git_add = "foam";
+          git_change = "rose";
+          git_delete = "love";
+          git_dirty = "rose";
+          git_ignore = "muted";
+          git_merge = "iris";
+          git_rename = "pine";
+          git_stage = "iris";
+          git_text = "rose";
+          git_untracked = "subtle";
+
           h1 = "iris";
           h2 = "foam";
           h3 = "rose";
@@ -31,21 +55,20 @@
           h5 = "pine";
           h6 = "foam";
         };
-      };
-      highlightGroups = {
-        ColorColumn = {bg = "rose";};
-        CursorLine = {
-          bg = "foam";
-          blend = 10;
-        };
-        StatusLine = {
-          fg = "love";
-          bg = "love";
-          blend = 10;
+        highlight_groups = {
+          ColorColumn.bg = "rose";
+          CursorLine = {
+            bg = "foam";
+            blend = 10;
+          };
+          StatusLine = {
+            fg = "love";
+            bg = "love";
+            blend = 10;
+          };
         };
+        before_highlight = "function(group, highlight, palette) end";
       };
-      transparentBackground = false;
-      transparentFloat = false;
     };
   };
 }