stylix: add 'stylix.enable' option (#244)

Add a 'stylix.enable' option to enable or disable all Stylix modules in
order to resolve issues similar to [2].

To align with the default 'lib.mkEnableOption' [1] behavior,
'stylix.enable' defaults to 'false'.

BREAKING CHANGE: Stylix is disabled by default. To enable it, use:

    stylix.enable = true;

[1]: https://github.com/NixOS/nixpkgs/blob/23.11/lib/options.nix#L91-L105
[2]: https://github.com/danth/stylix/issues/216

Co-authored-by: Daniel Thwaites <danthwaites30@btinternet.com>
Co-authored-by: Jalil David Salamé Messina <jalil.salame@gmail.com>
Co-authored-by: NAHO <90870942+trueNAHO@users.noreply.github.com>

README.md

@@ -34,6 +34,12 @@ For a visual guide, watch the [*Ricing Linux Has Never Been Easier | NixOS +
 Stylix*](https://youtu.be/ljHkWgBaQWU) YouTube video by
 [Vimjoyer](https://www.youtube.com/@vimjoyer).
 
+> [!NOTE]
+>
+> It's now necessary to include `stylix.enable = true` in your configuration
+> for any other settings to take effect. This is not mentioned in the video
+> linked above.
+
 If you have any questions, you are welcome to
 join our [Matrix room](https://matrix.to/#/#stylix:danth.me),
 or ask on [GitHub Discussions](https://github.com/danth/stylix/discussions).

docs/default.nix

@@ -47,6 +47,14 @@ in pkgs.stdenvNoCC.mkDerivation {
     cp ${../kde.png} src/kde.png
     cp ${../CONTRIBUTING.md} src/contributing.md
 
+    # mdBook doesn't support this Markdown extension yet
+    substituteInPlace **/*.md \
+      --replace-quiet '> [!NOTE]' '> **Note**' \
+      --replace-quiet '> [!TIP]' '> **Tip**' \
+      --replace-quiet '> [!IMPORTANT]' '> **Important**' \
+      --replace-quiet '> [!WARNING]' '> **Warning**' \
+      --replace-quiet '> [!CAUTION]' '> **Caution**'
+
     # The "declared by" links point to a file which only exists when the docs
     # are built locally. This removes the links.
     sed '/*Declared by:*/,/^$/d' <${nixos.optionsCommonMark} >>src/options/nixos.md

docs/src/configuration.md

@@ -1,5 +1,21 @@
 # Configuration
 
+## Enable
+
+To enable the Stylix module, declare:
+
+```nix
+{
+  stylix.enable = true;
+}
+```
+
+> [!NOTE]
+>
+> The global enable option was recently added, so you may come across old
+> examples which don't include it. No other settings will take effect unless
+> `stylix.enable` is set to `true`.
+
 ## Wallpaper
 
 To start theming, you need to set a wallpaper image.

docs/src/installation.md

@@ -119,7 +119,10 @@ let
 in {
     imports = [ (import stylix).homeManagerModules.stylix ];
 
-    stylix.image = ./wallpaper.jpg;
+    stylix = {
+      enable = true;
+      image = ./wallpaper.jpg;
+    };
 }
 
 ```

docs/src/modules.md

@@ -37,6 +37,7 @@ All modules should have an enable option created using `mkEnableTarget`.
 This is similar to
 [`mkEnableOption`](https://nix-community.github.io/docnix/reference/lib/options/lib-options-mkenableoption/)
 from the standard library, however it integrates with
+[`stylix.enable`](./options/nixos.md#stylixenable) and
 [`stylix.autoEnable`](./options/nixos.md#stylixautoenable)
 and generates more specific documentation.
 
@@ -46,16 +47,29 @@ A general format for modules is shown below.
 { config, lib, ... }:
 
 {
-  stylix.targets.«name».enable = config.lib.stylix.mkEnableTarget "«human readable name»";
+  options.stylix.targets.«name».enable =
+    config.lib.stylix.mkEnableTarget "«human readable name»" true;
 
-  config = lib.mkIf config.stylix.targets.«name».enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.«name».enable) {
+    programs.«name».backgroundColor = config.lib.stylix.colors.base00;
   };
 }
 ```
 
-The human readable name must fit into the following sentence:
+The human readable name will be inserted into the following sentence:
 
-> Whether to style «human readable name».
+> Whether to enable theming for «human readable name».
+
+If your module will touch options outside of `programs.«name»` or `services.«name»`,
+it should include an additional condition in `mkIf` to prevent any effects
+when the target is not installed.
+
+The boolean value after `mkEnableTarget` should be changed to `false` if
+one of the following applies:
+
+- The module requires further manual setup to work correctly.
+- There is no reliable way to detect whether the target is installed, *and*
+  enabling it unconditionally would cause problems.
 
 ## How to apply colors
 

modules/alacritty/hm.nix

@@ -9,7 +9,7 @@ in
 {
   options.stylix.targets.alacritty.enable = config.lib.stylix.mkEnableTarget "Alacritty" true;
 
-  config = lib.mkIf config.stylix.targets.alacritty.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.alacritty.enable) {
     programs.alacritty.settings = {
       font = with config.stylix.fonts; {
         normal = {

modules/avizo/hm.nix

@@ -10,7 +10,7 @@ in
     config.lib.stylix.mkEnableTarget "Avizo" true;
 
   # Referenced https://github.com/stacyharper/base16-mako
-  config = lib.optionalAttrs (options.services ? avizo) (lib.mkIf config.stylix.targets.avizo.enable {
+  config = lib.optionalAttrs (options.services ? avizo) (lib.mkIf (config.stylix.enable && config.stylix.targets.avizo.enable) {
     services.avizo = {
         settings = {
             default = {

modules/bat/hm.nix

@@ -2,9 +2,9 @@
 
 {
   options.stylix.targets.bat.enable =
-    config.lib.stylix.mkEnableTarget "Bat" config.programs.bat.enable;
+    config.lib.stylix.mkEnableTarget "Bat" true;
 
-  config = lib.mkIf config.stylix.targets.bat.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.bat.enable) {
     programs.bat = {
       # This theme is reused for yazi. Changes to the template 
       # will need to be applied to modules/yazi/hm.nix

modules/bemenu/hm.nix

@@ -25,7 +25,7 @@ in {
     };
   };
 
-  config = lib.mkIf config.stylix.targets.bemenu.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.bemenu.enable) {
     programs.bemenu.settings = with config.stylix.targets.bemenu; {
       tb = "${base01}${bemenuOpacity}"; # Title bg
       nb = "${base01}${bemenuOpacity}"; # Normal bg

modules/bspwm/hm.nix

@@ -6,7 +6,7 @@ in {
   options.stylix.targets.bspwm.enable =
     config.lib.stylix.mkEnableTarget "bspwm" true;
 
-  config = lib.mkIf config.stylix.targets.bspwm.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.bspwm.enable) {
     xsession.windowManager.bspwm.settings = {
       normal_border_color = colors.base03;
       active_border_color = colors.base0C;

modules/btop/hm.nix

@@ -3,9 +3,9 @@
 let
     colors = config.lib.stylix.colors.withHashtag;
 in {
-    options.stylix.targets.btop.enable = config.lib.stylix.mkEnableTarget "btop" config.programs.btop.enable;
+    options.stylix.targets.btop.enable = config.lib.stylix.mkEnableTarget "btop" true;
 
-      config = lib.mkIf config.stylix.targets.btop.enable {
+      config = lib.mkIf (config.stylix.enable && config.stylix.targets.btop.enable && config.programs.btop.enable) {
 
         programs.btop.settings = {
             color_theme = "stylix";

modules/chromium/nixos.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.chromium.enable =
     config.lib.stylix.mkEnableTarget "Chromium, Google Chrome and Brave" true;
 
-  config.programs.chromium = lib.mkIf config.stylix.targets.chromium.enable {
+  config.programs.chromium = lib.mkIf (config.stylix.enable && config.stylix.targets.chromium.enable) {
     # This enables policies without installing the browser. Policies take up a
     # negligible amount of space, so it's reasonable to have this always on.
     enable = true;

modules/console/nixos.nix

@@ -6,7 +6,7 @@ with config.lib.stylix.colors;
   options.stylix.targets.console.enable =
     config.lib.stylix.mkEnableTarget "the Linux kernel console" true;
 
-  config.console.colors = lib.mkIf config.stylix.targets.console.enable [
+  config.console.colors = lib.mkIf (config.stylix.enable && config.stylix.targets.console.enable) [
     base00-hex
     red
     green

modules/dunst/hm.nix

@@ -8,7 +8,7 @@ in {
   options.stylix.targets.dunst.enable =
     config.lib.stylix.mkEnableTarget "Dunst" true;
 
-  config = lib.mkIf config.stylix.targets.dunst.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.dunst.enable) {
     services.dunst.settings = {
       global = {
         separator_color = base02;

modules/emacs/hm.nix

@@ -8,9 +8,9 @@ let
 in
 {
   options.stylix.targets.emacs.enable =
-    config.lib.stylix.mkEnableTarget "Emacs" config.programs.emacs.enable;
+    config.lib.stylix.mkEnableTarget "Emacs" true;
 
-  config = lib.mkIf config.stylix.targets.emacs.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.emacs.enable) {
     programs.emacs = {
       extraPackages = epkgs:
         [

modules/feh/hm.nix

@@ -4,13 +4,20 @@
   options.stylix.targets.feh.enable =
     config.lib.stylix.mkEnableTarget
     "the desktop background using Feh"
-    (with config.xsession.windowManager; bspwm.enable
-                                      || herbstluftwm.enable
-                                      || i3.enable
-                                      || spectrwm.enable
-                                      || xmonad.enable);
+    true;
 
   config.xsession.initExtra =
-    lib.mkIf config.stylix.targets.feh.enable
+    lib.mkIf (
+      config.stylix.enable
+      && config.stylix.targets.feh.enable
+      && (
+        with config.xsession.windowManager;
+        bspwm.enable
+        || herbstluftwm.enable
+        || i3.enable
+        || spectrwm.enable
+        || xmonad.enable
+      )
+    )
     "${pkgs.feh}/bin/feh --no-fehbg --bg-scale ${config.stylix.image}";
 }

modules/feh/nixos.nix

@@ -4,9 +4,17 @@
   options.stylix.targets.feh.enable =
     config.lib.stylix.mkEnableTarget
     "the desktop background using Feh"
-    (with config.services.xserver.windowManager; xmonad.enable || i3.enable);
+    true;
 
   config.services.xserver.displayManager.sessionCommands =
-    lib.mkIf config.stylix.targets.feh.enable
+    lib.mkIf (
+      config.stylix.enable
+      && config.stylix.targets.feh.enable
+      && (
+        with config.services.xserver.windowManager;
+        xmonad.enable
+        || i3.enable
+      )
+    )
     "${pkgs.feh}/bin/feh --no-fehbg --bg-scale ${config.stylix.image}";
 }

modules/firefox/hm.nix

@@ -13,7 +13,7 @@ let
 in {
   options.stylix.targets.firefox = {
     enable =
-      config.lib.stylix.mkEnableTarget "Firefox" config.programs.firefox.enable;
+      config.lib.stylix.mkEnableTarget "Firefox" true;
 
     profileNames = lib.mkOption {
       description = "The Firefox profile names to apply styling on.";
@@ -22,7 +22,7 @@ in {
     };
   };
 
-  config = lib.mkIf config.stylix.targets.firefox.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.firefox.enable) {
     programs.firefox.profiles = lib.listToAttrs
       (map makeProfileSettingsPair config.stylix.targets.firefox.profileNames);
   };

modules/fish/hm.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.fish.enable =
     config.lib.stylix.mkEnableTarget "Fish" true;
 
-  config = lib.mkIf config.stylix.targets.fish.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.fish.enable) {
     programs.fish.interactiveShellInit = import ./prompt.nix { inherit pkgs config; };
   };
 }

modules/fish/nixos.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.fish.enable =
     config.lib.stylix.mkEnableTarget "Fish" true;
 
-  config = lib.mkIf config.stylix.targets.fish.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.fish.enable) {
     programs.fish.promptInit = import ./prompt.nix { inherit pkgs config; };
   };
 }

modules/fuzzel/hm.nix

@@ -7,10 +7,10 @@ let
 
 in {
   options.stylix.targets.fuzzel.enable =
-    config.lib.stylix.mkEnableTarget "Fuzzel" config.programs.fuzzel.enable;
+    config.lib.stylix.mkEnableTarget "Fuzzel" true;
 
   config.programs.fuzzel.settings =
-    lib.mkIf config.stylix.targets.fuzzel.enable {
+    lib.mkIf (config.stylix.enable && config.stylix.targets.fuzzel.enable) {
       colors = {
         background = "${base00-hex}${opacity}";
         text = "${base05-hex}ff";

modules/fzf/hm.nix

@@ -20,10 +20,10 @@ let
 in
 {
   options.stylix.targets.fzf = {
-    enable = config.lib.stylix.mkEnableTarget "Fzf" config.programs.fzf.enable;
+    enable = config.lib.stylix.mkEnableTarget "Fzf" true;
   };
 
-  config = lib.mkIf config.stylix.targets.fzf.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.fzf.enable) {
     programs.fzf.defaultOptions = lib.mkAfter [ "--color=${colorConfig}" ];
   };
 }

modules/gedit/hm.nix

@@ -10,7 +10,7 @@ in {
   options.stylix.targets.gedit.enable =
     config.lib.stylix.mkEnableTarget "GEdit" true;
 
-  config = lib.mkIf config.stylix.targets.gedit.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.gedit.enable) {
     xdg.dataFile = {
       "gedit/styles/stylix.xml".source = style;
     };

modules/gitui/hm.nix

@@ -14,7 +14,7 @@ in
   options.stylix.targets.gitui.enable =
     config.lib.stylix.mkEnableTarget "GitUI" true;
 
-  config = lib.mkIf config.stylix.targets.gitui.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.gitui.enable) {
     programs.gitui.theme = ''
       (
           selected_tab: Some(Reset),

modules/gnome/hm.nix

@@ -6,7 +6,7 @@ with lib;
   options.stylix.targets.gnome.enable =
     config.lib.stylix.mkEnableTarget "GNOME" true;
 
-  config = mkIf config.stylix.targets.gnome.enable {
+  config = mkIf (config.stylix.enable && config.stylix.targets.gnome.enable) {
     dconf.settings = {
       "org/gnome/desktop/background" = {
         color-shading-type = "solid";

modules/gnome/nixos.nix

@@ -5,11 +5,13 @@ let
 
 in {
   options.stylix.targets.gnome.enable =
-    config.lib.stylix.mkEnableTarget
-    "GNOME and GDM"
-    config.services.xserver.desktopManager.gnome.enable;
+    config.lib.stylix.mkEnableTarget "GNOME and GDM" true;
 
-  config = lib.mkIf config.stylix.targets.gnome.enable {
+  config = lib.mkIf (
+    config.stylix.enable
+    && config.stylix.targets.gnome.enable
+    && config.services.xserver.desktopManager.gnome.enable
+  ) {
     # As Stylix is controlling the wallpaper, there is no need for this
     # pack of default wallpapers to be installed.
     # If you want to use one, you can set stylix.image to something like

modules/grub/nixos.nix

@@ -34,7 +34,7 @@ in {
     };
   };
 
-  config.boot.loader.grub = lib.mkIf config.stylix.targets.grub.enable {
+  config.boot.loader.grub = lib.mkIf (config.stylix.enable && config.stylix.targets.grub.enable) {
     backgroundColor = base00;
     # Need to override the NixOS splash, this will match the background
     splashImage = pixel "base00";

modules/gtk/nixos.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.gtk.enable =
     config.lib.stylix.mkEnableTarget "all GTK3, GTK4 and Libadwaita apps" true;
 
-  config = lib.mkIf config.stylix.targets.gtk.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.gtk.enable) {
     # Required for Home Manager's GTK settings to work
     programs.dconf.enable = true;
   };

modules/helix/hm.nix

@@ -14,9 +14,9 @@ let
 
 in {
   options.stylix.targets.helix.enable =
-    config.lib.stylix.mkEnableTarget "Helix" config.programs.helix.enable;
+    config.lib.stylix.mkEnableTarget "Helix" true;
 
-  config = lib.mkIf config.stylix.targets.helix.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.helix.enable && config.programs.helix.enable) {
     programs.helix.settings.theme = "stylix";
 
     xdg.configFile."helix/themes/stylix.toml".source =

modules/hyprland/hm.nix

@@ -25,5 +25,5 @@ in {
     config.lib.stylix.mkEnableTarget "Hyprland" true;
 
   config.wayland.windowManager.hyprland.settings =
-    lib.mkIf config.stylix.targets.hyprland.enable settings;
+    lib.mkIf (config.stylix.enable && config.stylix.targets.hyprland.enable) settings;
 }

modules/kde/hm.nix

@@ -222,9 +222,9 @@ let
 
 in {
   options.stylix.targets.kde.enable =
-    config.lib.stylix.mkEnableTarget "KDE" pkgs.stdenv.hostPlatform.isLinux;
+    config.lib.stylix.mkEnableTarget "KDE" true;
 
-  config = lib.mkIf config.stylix.targets.kde.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.kde.enable && pkgs.stdenv.hostPlatform.isLinux) {
     home.packages = [ themePackage ];
     xdg.systemDirs.config = [ "${configPackage}" ];
 

modules/kmscon/nixos.nix

@@ -3,7 +3,7 @@
   options.stylix.targets.kmscon.enable =
     config.lib.stylix.mkEnableTarget "the kmscon virtual console" true;
 
-  config.services.kmscon = lib.mkIf config.stylix.targets.kmscon.enable {
+  config.services.kmscon = lib.mkIf (config.stylix.enable && config.stylix.targets.kmscon.enable) {
     fonts = [config.stylix.fonts.monospace];
     extraConfig =
     let

modules/lazygit/hm.nix

@@ -5,9 +5,9 @@
 }: let
   colors = config.lib.stylix.colors.withHashtag;
 in {
-  options.stylix.targets.lazygit.enable = config.lib.stylix.mkEnableTarget "lazygit" config.programs.lazygit.enable;
+  options.stylix.targets.lazygit.enable = config.lib.stylix.mkEnableTarget "lazygit" true;
 
-  config = lib.mkIf config.stylix.targets.lazygit.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.lazygit.enable) {
     programs.lazygit.settings.gui.theme = {
       activeBorderColor = [
         colors.base07

modules/lightdm/nixos.nix

@@ -5,5 +5,5 @@
     config.lib.stylix.mkEnableTarget "LightDM" true;
 
   config.services.xserver.displayManager.lightdm.background =
-    lib.mkIf config.stylix.targets.lightdm.enable config.stylix.image;
+    lib.mkIf (config.stylix.enable && config.stylix.targets.lightdm.enable) config.stylix.image;
 }

modules/mako/hm.nix

@@ -9,7 +9,7 @@ in {
     config.lib.stylix.mkEnableTarget "Mako" true;
 
   # Referenced https://github.com/stacyharper/base16-mako
-  config = lib.optionalAttrs (options.services ? mako) (lib.mkIf config.stylix.targets.mako.enable {
+  config = lib.optionalAttrs (options.services ? mako) (lib.mkIf (config.stylix.enable && config.stylix.targets.mako.enable) {
     services.mako = {
       backgroundColor = base00 + makoOpacity;
       borderColor = base0D;

modules/mangohud/hm.nix

@@ -5,9 +5,9 @@ let
     colors = config.lib.stylix.colors;
     opacity = config.stylix.opacity;
 in {
-    options.stylix.targets.mangohud.enable = config.lib.stylix.mkEnableTarget "mangohud" config.programs.mangohud.enable;
+    options.stylix.targets.mangohud.enable = config.lib.stylix.mkEnableTarget "mangohud" true;
 
-    config = lib.mkIf config.stylix.targets.mangohud.enable {
+    config = lib.mkIf (config.stylix.enable && config.stylix.targets.mangohud.enable) {
         programs.mangohud.settings = with colors; {
             font_size = fonts.sizes.applications;
             font_size_text = fonts.sizes.applications;

modules/nixos-icons/nixos.nix

@@ -6,7 +6,7 @@ with config.lib.stylix.colors;
   options.stylix.targets.nixos-icons.enable =
     config.lib.stylix.mkEnableTarget "the NixOS logo" true;
 
-  config.nixpkgs.overlays = lib.mkIf config.stylix.targets.nixos-icons.enable [(self: super: {
+  config.nixpkgs.overlays = lib.mkIf (config.stylix.enable && config.stylix.targets.nixos-icons.enable) [(self: super: {
     nixos-icons = super.nixos-icons.overrideAttrs (oldAttrs: {
       src = pkgs.applyPatches {
         src = oldAttrs.src;

modules/nixvim/nixvim.nix

@@ -6,14 +6,14 @@
 }: {
   options.stylix.targets.nixvim = {
     enable =
-      config.lib.stylix.mkEnableTarget "nixvim" (config.programs ? nixvim);
+      config.lib.stylix.mkEnableTarget "nixvim" true;
     transparent_bg = {
       main = lib.mkEnableOption "background transparency for the main NeoVim window";
       sign_column = lib.mkEnableOption "background transparency for the NeoVim sign column";
     };
   };
 
-  config = lib.mkIf ((config.programs ? nixvim) && config.stylix.targets.nixvim.enable) (
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.nixvim.enable && (config.programs ? nixvim)) (
     lib.optionalAttrs (builtins.hasAttr "nixvim" options.programs) {
       programs.nixvim = {
         colorschemes.base16 = {

modules/nushell/hm.nix

@@ -4,10 +4,10 @@ with config.lib.stylix.colors.withHashtag;
 
 {
   options.stylix.targets.nushell.enable =
-    config.lib.stylix.mkEnableTarget "Nushell" config.programs.nushell.enable;
+    config.lib.stylix.mkEnableTarget "Nushell" true;
 
   # Adapted from https://www.nushell.sh/book/coloring_and_theming.html#theming
-  config.programs.nushell.extraConfig = lib.mkIf config.stylix.targets.nushell.enable ''
+  config.programs.nushell.extraConfig = lib.mkIf (config.stylix.enable && config.stylix.targets.nushell.enable) ''
     $env.config.color_config = {
       seperator: "${base03}"
       leading_trailing_space_bg: "${base04}"

modules/qutebrowser/hm.nix

@@ -21,7 +21,7 @@ in {
   options.stylix.targets.qutebrowser.enable =
     config.lib.stylix.mkEnableTarget "Qutebrowser" true;
 
-  config = lib.mkIf config.stylix.targets.qutebrowser.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.qutebrowser.enable) {
     programs.qutebrowser.settings = {
       colors = {
         completion = {

modules/rofi/hm.nix

@@ -20,7 +20,7 @@ in
   options.stylix.targets.rofi.enable =
     config.lib.stylix.mkEnableTarget "Rofi" true;
 
-  config = lib.mkIf config.stylix.targets.rofi.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.rofi.enable) {
     programs.rofi = {
       font = "${monospace.name} ${toString sizes.popups}";
       theme = {

modules/sway/hm.nix

@@ -18,7 +18,7 @@ in {
     config.lib.stylix.mkEnableTarget "Sway" true;
 
   config = lib.mkMerge [
-    (lib.mkIf config.stylix.targets.sway.enable {
+    (lib.mkIf (config.stylix.enable && config.stylix.targets.sway.enable) {
       wayland.windowManager.sway.config = {
         inherit fonts;
 

modules/swaylock/hm.nix

@@ -12,7 +12,7 @@ let
 
 in {
   options.stylix.targets.swaylock = {
-    enable = config.lib.stylix.mkEnableTarget "Swaylock" pkgs.stdenv.hostPlatform.isLinux;
+    enable = config.lib.stylix.mkEnableTarget "Swaylock" true;
     useImage = lib.mkOption {
       description = ''
         Whether to use your wallpaper image for the Swaylock background.
@@ -23,7 +23,7 @@ in {
     };
   };
 
-  config = lib.mkIf config.stylix.targets.swaylock.enable
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.swaylock.enable && pkgs.stdenv.hostPlatform.isLinux)
     # See https://github.com/danth/stylix/issues/8#issuecomment-1194484544
     # This check can be removed when programs.swaylock is in a stable release
     (lib.optionalAttrs (options.programs ? swaylock) {

modules/sxiv/hm.nix

@@ -7,7 +7,7 @@ in {
   options.stylix.targets.sxiv.enable =
     config.lib.stylix.mkEnableTarget "Sxiv" true;
 
-  config = lib.mkIf config.stylix.targets.sxiv.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.sxiv.enable) {
     xresources = {
       properties = {
         "Sxiv.foreground" = "#${colors.base01}";

modules/tmux/hm.nix

@@ -7,9 +7,9 @@ let
 
 in {
   options.stylix.targets.tmux.enable =
-    config.lib.stylix.mkEnableTarget "Tmux" config.programs.tmux.enable;
+    config.lib.stylix.mkEnableTarget "Tmux" true;
 
-  config = lib.mkIf config.stylix.targets.tmux.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.tmux.enable) {
     programs.tmux.extraConfig = ''
     source-file ${theme}
     '';

modules/tofi/hm.nix

@@ -7,7 +7,7 @@ with config.lib.stylix.colors.withHashtag; {
   options.stylix.targets.tofi.enable =
     config.lib.stylix.mkEnableTarget "Tofi" true;
 
-  config = lib.mkIf config.stylix.targets.tofi.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.tofi.enable) {
     programs.tofi.settings =
       let
         opacity = lib.toHexString ((((builtins.ceil (config.stylix.opacity.popups * 100)) * 255) / 100));

modules/vesktop/hm.nix

@@ -8,7 +8,7 @@ in
 {
   options.stylix.targets.vesktop.enable = config.lib.stylix.mkEnableTarget "Vesktop" true;
 
-  config = lib.mkIf config.stylix.targets.vesktop.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.vesktop.enable) {
     home.file."${config.xdg.configHome}/vesktop/themes/stylix.theme.css" = {
       source = themeFile;
     };

modules/vim/hm.nix

@@ -55,7 +55,7 @@ in {
   options.stylix.targets.vim.enable =
     config.lib.stylix.mkEnableTarget "Vim and/or Neovim" true;
 
-  config = lib.mkIf config.stylix.targets.vim.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.vim.enable) {
     programs.vim = vimOptions;
     programs.neovim = vimOptions;
   };

modules/vscode/hm.nix

@@ -22,7 +22,7 @@ in {
   options.stylix.targets.vscode.enable =
     config.lib.stylix.mkEnableTarget "VSCode" true;
 
-  config = lib.mkIf config.stylix.targets.vscode.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.vscode.enable) {
     programs.vscode = {
       extensions = [ themeExtension ];
       userSettings = {

modules/waybar/hm.nix

@@ -32,7 +32,7 @@ in
     };
   };
 
-  config = lib.mkIf config.stylix.targets.waybar.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.waybar.enable) {
     programs.waybar.style = ''
       @define-color base00 ${base00}; @define-color base01 ${base01}; @define-color base02 ${base02}; @define-color base03 ${base03};
       @define-color base04 ${base04}; @define-color base05 ${base05}; @define-color base06 ${base06}; @define-color base07 ${base07};

modules/wezterm/hm.nix

@@ -3,9 +3,9 @@
 let colors = config.lib.stylix.colors.withHashtag;
 in {
   options.stylix.targets.wezterm.enable =
-    config.lib.stylix.mkEnableTarget "wezterm" config.programs.wezterm.enable;
+    config.lib.stylix.mkEnableTarget "wezterm" true;
 
-  config = lib.mkIf config.stylix.targets.wezterm.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.wezterm.enable && config.programs.wezterm.enable) {
 
     programs.wezterm.colorSchemes.stylix = with colors; {
       ansi = [ base00 base08 base0B base0A base0D base0E base0C base05 ];

modules/wpaperd/hm.nix

@@ -3,7 +3,7 @@
 {
   options.stylix.targets.wpaperd.enable = config.lib.stylix.mkEnableTarget "wpaperd" true;
 
-  config = lib.mkIf config.stylix.targets.wpaperd.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.wpaperd.enable) {
     programs.wpaperd.settings.any.path = "${config.stylix.image}";
   };
 }

modules/xfce/hm.nix

@@ -5,7 +5,7 @@
   options.stylix.targets.xfce.enable =
     config.lib.stylix.mkEnableTarget "Xfce" false;
 
-  config = lib.mkIf config.stylix.targets.xfce.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.xfce.enable) {
     xfconf.settings = with config.stylix.fonts; {
       xfwm4 = {
         "general/title_font" = "${sansSerif.name} ${toString sizes.desktop}";

modules/xresources/hm.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.xresources.enable =
     config.lib.stylix.mkEnableTarget "Xresources" true;
 
-  config = lib.mkIf config.stylix.targets.xresources.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.xresources.enable) {
     xresources.properties = with config.lib.stylix.colors.withHashtag; with config.stylix.fonts; {
       "*.faceName" = monospace.name;
       "*.faceSize" = sizes.terminal;

modules/yazi/hm.nix

@@ -5,10 +5,10 @@
   ...
 }: {
   options.stylix.targets.yazi = {
-    enable = config.lib.stylix.mkEnableTarget "Yazi" config.programs.yazi.enable;
+    enable = config.lib.stylix.mkEnableTarget "Yazi" true;
   };
 
-  config = lib.mkIf config.stylix.targets.yazi.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.yazi.enable) {
     programs.yazi.theme = with config.lib.stylix.colors.withHashtag; let
       mkFg = fg: {inherit fg;};
       mkBg = bg: {inherit bg;};

modules/zathura/hm.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.zathura.enable =
     config.lib.stylix.mkEnableTarget "Zathura" true;
 
-  config = lib.mkIf config.stylix.targets.zathura.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.zathura.enable) {
     programs.zathura.options = let
       highlightTransparency = "0.5";
       getColorCh = colorName: channel: config.lib.stylix.colors."${colorName}-rgb-${channel}";

modules/zellij/hm.nix

@@ -2,9 +2,9 @@
 
 {
   options.stylix.targets.zellij.enable =
-    config.lib.stylix.mkEnableTarget "zellij" config.programs.zellij.enable ;
+    config.lib.stylix.mkEnableTarget "zellij" true;
 
-  config = lib.mkIf config.stylix.targets.zellij.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.zellij.enable) {
     programs.zellij.settings = {
         theme = "stylix";
         themes.stylix = with config.lib.stylix.colors.withHashtag; {

stylix/darwin/fonts.nix

@@ -1,10 +1,10 @@
-{ config, ... }:
+{ config, lib, ... }:
 
 let
   cfg = config.stylix.fonts;
 in {
   imports = [ ../fonts.nix ];
-  config.fonts = {
+  config.fonts = lib.mkIf config.stylix.enable {
     fontDir.enable = true;
     fonts = cfg.packages;
   };

stylix/darwin/palette.nix

@@ -1,10 +1,10 @@
 args:
-{ config, ... }:
+{ config, lib, ... }:
 
 {
   imports = [ (import ../palette.nix args) ];
 
-  config = {
+  config = lib.mkIf config.stylix.enable {
     environment.etc = config.stylix.generated.fileTree;
   };
 }

stylix/fonts.nix

@@ -104,7 +104,7 @@ in {
     };
   };
 
-  config = {
+  config = lib.mkIf config.stylix.enable {
     stylix.fonts.packages = [
       cfg.monospace.package
       cfg.serif.package

stylix/hm/cursor.nix

@@ -7,7 +7,7 @@ let
 in {
   imports = [ ../cursor.nix ];
 
-  config = mkIf pkgs.stdenv.hostPlatform.isLinux {
+  config = mkIf (config.stylix.enable && pkgs.stdenv.hostPlatform.isLinux) {
     home.pointerCursor = {
       name = cfg.name;
       package = cfg.package;

stylix/hm/fonts.nix

@@ -1,10 +1,10 @@
-{ config, ... }:
+{ config, lib, ... }:
 
 let
   cfg = config.stylix.fonts;
 in {
   imports = [ ../fonts.nix ];
-  config = {
+  config = lib.mkIf config.stylix.enable {
     fonts.fontconfig.enable = true;
     home.packages = cfg.packages;
   };

stylix/hm/palette.nix

@@ -1,10 +1,10 @@
 args:
-{ config, ... }:
+{ config, lib, ... }:
 
 {
   imports = [ (import ../palette.nix args) ];
 
-  config = {
+  config = lib.mkIf config.stylix.enable {
     xdg.configFile = config.stylix.generated.fileTree;
   };
 }

stylix/nixos/cursor.nix

@@ -1,10 +1,10 @@
-{ config, ... }:
+{ config, lib, ... }:
 
 let
   cfg = config.stylix.cursor;
 in {
   imports = [ ../cursor.nix ];
-  config = {
+  config = lib.mkIf config.stylix.enable {
     environment.variables.XCURSOR_SIZE = toString cfg.size;
   };
 }

stylix/nixos/fonts.nix

@@ -1,10 +1,10 @@
-{ config, ... }:
+{ config, lib, ... }:
 
 let
   cfg = config.stylix.fonts;
 in {
   imports = [ ../fonts.nix ];
-  config.fonts = {
+  config.fonts = lib.mkIf config.stylix.enable {
     packages = cfg.packages;
 
     fontconfig.defaultFonts = {

stylix/nixos/palette.nix

@@ -1,10 +1,10 @@
 args:
-{ config, ... }:
+{ config, lib, ... }:
 
 {
   imports = [ (import ../palette.nix args) ];
 
-  config = {
+  config = lib.mkIf config.stylix.enable {
     environment.etc = config.stylix.generated.fileTree;
   };
 }

stylix/target.nix

@@ -3,32 +3,48 @@
 with lib;
 
 {
-  options.stylix.autoEnable =
-    mkEnableOption
-    "styling installed targets"
-    // {
+  options.stylix = {
+    enable = mkOption {
+      description = ''
+        Whether to enable Stylix.
+
+        When this is `false`, all theming is disabled and all other options
+        are ignored.
+      '';
+      type = types.bool;
+      default = import ./fromos.nix { inherit lib args; } [ "enable" ] false;
+      example = true;
+    };
+
+    autoEnable = mkOption {
+      description = ''
+        Whether to enable targets by default.
+
+        When this is `false`, all targets are disabled unless explicitly enabled.
+
+        When this is `true`, most targets are enabled by default. A small number
+        remain off by default, because they require further manual setup, or
+        they are only applicable in specific circumstances which cannot be
+        detected automatically.
+      '';
+      type = types.bool;
       default = import ./fromos.nix { inherit lib args; } [ "autoEnable" ] true;
       example = false;
     };
+  };
 
-  config.lib.stylix.mkEnableTarget =
+  config.lib.stylix.mkEnableTarget = let
+    cfg = config.stylix;
+  in
     humanName:
-
-    # If the module only touches options under its target (programs.target.*)
-    # then this can simply be `true`, as those options are already gated by the
-    # upstream enable option.
-    #
-    # Otherwise, use `config` to check whether the target is enabled.
-    #
-    # If some manual setup is required, or the module leads to the target
-    # being installed if it wasn't already, set this to `false`.
     autoEnable:
       mkEnableOption
-      "styling for ${humanName}"
+      "theming for ${humanName}"
       // {
-        default = config.stylix.autoEnable && autoEnable;
+        default = cfg.enable && cfg.autoEnable && autoEnable;
+        example = !autoEnable;
       }
       // optionalAttrs autoEnable {
-        defaultText = literalExpression "stylix.autoEnable";
+        defaultText = literalMD "same as [`stylix.autoEnable`](#stylixautoenable)";
       };
 }