gtk4: don't enable theme by default

This is not officially supported and causes issues in some cases.
Also adds a warning to the option.

docs/release-notes/rl-2605.md

@@ -12,3 +12,6 @@ This release has the following notable changes:
 The state version in this release includes the changes below. These
 changes are only active if the `home.stateVersion` option is set to
 \"26.05\" or later.
+
+- The `gtk.gtk4.theme` option does not mirror `gtk.theme` by default
+  anymore.

modules/misc/gtk.nix

@@ -59,7 +59,7 @@ in
     theme = mkOption {
       type = types.nullOr themeType;
       default = null;
-      description = "Default theme for all GTK versions.";
+      description = "Default theme for GTK 2/3.";
     };
 
     iconTheme = mkOption {

modules/misc/gtk/gtk4.nix

@@ -45,9 +45,17 @@ in
           packageExample = "pkgs.gnome.gnome-themes-extra";
         }
       );
-      default = cfg.theme;
+      default = if lib.versionOlder config.home.stateVersion "26.05" then cfg.theme else null;
-      defaultText = literalExpression "config.gtk.theme";
+      defaultText = literalExpression ''if lib.versionOlder config.home.stateVersion "26.05" then cfg.theme else null'';
-      description = "Theme for GTK 4 applications.";
+      description = ''
+        Theme for GTK 4 applications.
+
+        Warning: This is not officially supported and applied using a workaround.
+        It may cause issues with some apps.
+
+        For context, see [Please don’t theme our apps](https://stopthemingmy.app/)
+        and [Restyling apps at scale](https://blogs.gnome.org/tbernard/2018/10/15/restyling-apps-at-scale/).
+      '';
     };
 
     iconTheme = mkOption {

modules/misc/news/2025/11/2025-11-26_11-55-28.nix

@@ -0,0 +1,11 @@
+{
+  time = "2025-11-26T10:55:28+00:00";
+  condition = true;
+  message = ''
+    The option 'gtk.theme' does not apply to GTK 4 automatically anymore for new
+    installations (with `home.stateVersion` >= "26.05"). Using a custom theme is
+    not officially supported by GTK 4, and implemented by home-manager using a
+    workaround that may cause issues in some cases. If you still want to use a GTK
+    4 theme, you need to explicitly set 'gtk.gtk4.theme'.
+  '';
+}

tests/modules/misc/gtk/gtk-global-inheritance-gtk4-css-expected.css

@@ -1,5 +0,0 @@
-/**
- * GTK 4 reads the theme configured by gtk-theme-name, but ignores it.
- * It does however respect user CSS, so import the theme from here.
-**/
-@import url("file://@gnome-themes-extra@/share/themes/Adwaita-dark/gtk-4.0/gtk.css");

tests/modules/misc/gtk/gtk-global-inheritance-gtk4-expected.ini

@@ -5,4 +5,3 @@ gtk-cursor-theme-size=24
 gtk-font-name=Ubuntu 12
 gtk-icon-theme-name=Adwaita
 gtk-interface-color-scheme=2
-gtk-theme-name=Adwaita-dark

tests/modules/misc/gtk/gtk-global-inheritance.nix

@@ -1,5 +1,7 @@
 { pkgs, ... }:
 {
+  home.stateVersion = "26.05";
+
   gtk = {
     enable = true;
     font = {
@@ -37,9 +39,5 @@
     assertFileExists home-files/.config/gtk-4.0/settings.ini
     assertFileContent home-files/.config/gtk-4.0/settings.ini \
       ${./gtk-global-inheritance-gtk4-expected.ini}
-
-    # Check GTK4 CSS with theme import
-    assertFileExists home-files/.config/gtk-4.0/gtk.css
-    assertFileContent home-files/.config/gtk-4.0/gtk.css ${./gtk-global-inheritance-gtk4-css-expected.css}
   '';
 }

tests/modules/misc/gtk/gtk-per-version-override-gtk4-expected.ini

@@ -3,4 +3,3 @@ gtk-cursor-theme-name=Global-Cursor
 gtk-font-name=GTK4-Font 11
 gtk-icon-theme-name=Global-Icons
 gtk-recent-files-limit=20
-gtk-theme-name=Global-Theme

tests/modules/misc/gtk/gtk-per-version-override.nix

@@ -1,4 +1,6 @@
 {
+  home.stateVersion = "26.05";
+
   gtk = {
     enable = true;
     # Global defaults
@@ -46,7 +48,7 @@
     assertFileContent home-files/.config/gtk-3.0/gtk.css \
       ${./gtk-per-version-override-gtk3-css-expected.css}
 
-    # GTK4 should use overridden font, global theme/icons/cursor
+    # GTK4 should use overridden font, global icons/cursor
     assertFileExists home-files/.config/gtk-4.0/settings.ini
     assertFileContent home-files/.config/gtk-4.0/settings.ini \
       ${./gtk-per-version-override-gtk4-expected.ini}

tests/modules/misc/gtk/gtk4/gtk4-basic-settings.nix

@@ -2,11 +2,11 @@
 {
   gtk = {
     enable = true;
-    theme = {
-      name = "catppuccin-macchiato-blue-standard";
-      package = pkgs.catppuccin-gtk;
-    };
     gtk4 = {
+      theme = {
+        name = "catppuccin-macchiato-blue-standard";
+        package = pkgs.catppuccin-gtk;
+      };
       extraConfig = {
         gtk-cursor-blink = false;
         gtk-recent-files-limit = 20;