danth · SomeGuyNamedMay · Mar 29, 2023 · Mar 29, 2023 · Mar 29, 2023 · Mar 29, 2023
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+result
+result-*
diff --git a/README.md b/README.md
@@ -1,18 +1,8 @@
 # Stylix
 
-Stylix is a NixOS module which applies the same colour scheme, font and
-wallpaper to a range of applications and desktop environments.
-
-## What's this?
-
-[base16.nix](https://github.com/SenchoPens/base16.nix#readme) allows you to
-import colours from [base16](https://github.com/chriskempson/base16#readme)
-into Nix code. Stylix takes this a step further:
-
-- Automatically colours and changes the font of apps
-- Sets your wallpaper
-- Exports the colour scheme to be used manually for anything we missed
-- Can also generate themes based on an image
+Stylix is a module which applies a chosen color scheme, font and
+wallpaper to [supported 
+software](https://github.com/danth/stylix/tree/master/modules).
 
 For those not familiar with [NixOS](https://nixos.org/) and
 [Home Manager](https://github.com/nix-community/home-manager#readme):
@@ -22,17 +12,16 @@ For those not familiar with [NixOS](https://nixos.org/) and
 - Both use the Nix language and package manager
 - Both let you install programs and change settings via code
 
-Stylix supports either NixOS + Home Manager, or Home Manager on its own.
-Certain features are only available with NixOS.
-
-## Resources
+Stylix supports Home Manager on its own, but certain features are only
+possible when combined with NixOS.
 
-Please refer to the [Stylix book](https://danth.github.io/stylix/)
-for instructions and a list of supported apps.
+Please refer to the
+[Stylix book](https://danth.github.io/stylix/installation.html)
+for instructions and a list supported apps.
 
 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).
+or use [GitHub Discussions](https://github.com/danth/stylix/discussions).
 
 ## Example configurations
 

diff --git a/docs/settings.nix b/docs/settings.nix
@@ -1,26 +1,12 @@
-# Dummy values to avoid errors when generating the documentation.
+# Dummy wallpaper to avoid errors when generating the documentation.
 
-{
-  stylix = {
-    image = "/a/b/c";
+{ pkgs, config, ... }:
 
-    base16Scheme = {
-      base00 = "ffffff";
-      base01 = "ffffff";
-      base02 = "ffffff";
-      base03 = "ffffff";
-      base04 = "ffffff";
-      base05 = "ffffff";
-      base06 = "ffffff";
-      base07 = "ffffff";
-      base08 = "ffffff";
-      base09 = "ffffff";
-      base0A = "ffffff";
-      base0B = "ffffff";
-      base0C = "ffffff";
-      base0D = "ffffff";
-      base0E = "ffffff";
-      base0F = "ffffff";
+{
+  stylix.wallpaper = config.lib.stylix.types.wallpaper.from.image {
+    file = pkgs.fetchurl {
+      url = "https://picsum.photos/seed/stylix/1920/1080.jpg";
+      sha256 = "tow7DBO+/tgkDDD8diif+0V/6aDzrYl02/J7SCA8RCU=";
     };
   };
 }
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -10,6 +10,7 @@
 
 - [NixOS options](options/nixos.md)
 - [Home Manager options](options/hm.md)
+- [Wallpaper support](wallpaper-support.md)
 
 # Contributing
 

diff --git a/docs/src/configuration.md b/docs/src/configuration.md
@@ -1,163 +1,45 @@
 # Configuration
 
-## Wallpaper
+## Getting started
 
-To start theming, you need to set a wallpaper image.
+The options you will be most interested in are as follows:
 
-```nix
-{
-  stylix.image = ./wallpaper.png;
-}
-```
+- Choosing a wallpaper: [`stylix.wallpaper`](./options/nixos.html#stylixwallpaper)
+- Choosing a color scheme: [`stylix.colors`](./options/nixos.html#stylixcolors)
+- Changing fonts: [`stylix.fonts.*`](./options/nixos.html#stylixfontsemoji)
+- Making apps transparent: [`stylix.opacity.*`](./options/nixos.html#stylixopacityapplications)
 
-The option accepts derivations as well as paths, so you can fetch an image
-directly from the internet:
+Only the wallpaper is required as the others default to something reasonable.
 
-```nix
-{
-  stylix.image = pkgs.fetchurl {
-    url = "https://www.pixelstalk.net/wp-content/uploads/2016/05/Epic-Anime-Awesome-Wallpapers.jpg";
-    sha256 = "enQo3wqhgf0FEPHj2coOCvo7DuZv+x5rL/WIo4qPI50=";
-  };
-}
-```
+Rebuild the configuration to apply any changed settings. Most software needs to
+be restarted for a new theme to take effect, so you may wish to reboot too.
 
-## Color scheme
-
-### Generated schemes
-
-If you only set a wallpaper, Stylix will use a
-[genetic algorithm](https://en.wikipedia.org/wiki/Genetic_algorithm)
-to create a color scheme. The quality of these schemes can vary, but more
-colorful images tend to have better results.
-
-You can force a light or dark scheme using the polarity option:
-
-```nix
-{
-  stylix.polarity = "dark";
-}
-```
-
-The current scheme can be previewed in a web browser at either
-[`/etc/stylix/palette.html`](file:///etc/stylix/palette.html) for NixOS, or
-`~/.config/stylix/palette.html` for Home Manager.
-
-### Handmade schemes
-
-If you prefer a handmade color scheme, you can choose anything from
-[the Tinted Theming repository](https://github.com/tinted-theming/base16-schemes):
-
-```nix
-{
-  stylix.base16Scheme = "${pkgs.base16-schemes}/share/themes/gruvbox-dark-hard.yaml";
-}
-```
-
-This option also accepts other files and formats supported by
-[`mkSchemeAttrs`](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs).
-
-### Overriding
-
-For convenience, it is possible to override parts of `stylix.base16Scheme` using
-`stylix.override`. Anything that
-[base16.nix](https://github.com/SenchoPens/base16.nix) accepts as override is
-valid.
-
-When using both the Home Manager and NixOS modules, both the system overrides
-and the user-provided one are used in the user configuration if
-`stylix.base16Scheme` is not changed in the user config. If that is the case,
-only the user override is used.
-
-## Fonts
-
-The default combination of fonts is:
-
-```nix
-{
-  stylix.fonts = {
-    serif = {
-      package = pkgs.dejavu_fonts;
-      name = "DejaVu Serif";
-    };
-
-    sansSerif = {
-      package = pkgs.dejavu_fonts;
-      name = "DejaVu Sans";
-    };
-
-    monospace = {
-      package = pkgs.dejavu_fonts;
-      name = "DejaVu Sans Mono";
-    };
-
-    emoji = {
-      package = pkgs.noto-fonts-emoji;
-      name = "Noto Color Emoji";
-    };
-  };
-}
-```
-
-These can be changed as you like.
+## Turning targets on and off
 
-To make things look more uniform, you could replace the serif font with
-the sans-serif font:
+A target is anything which can have colors, fonts or a wallpaper applied to
+it.
 
-```nix
-{
-  stylix.fonts.serif = config.stylix.fonts.sansSerif;
-}
-```
+Each target has an option like `stylix.targets.«target».enable` to choose
+whether it gets themed. By default, targets are enabled automatically when
+they are installed - you can opt out of this via
+[`stylix.autoEnable`](./options/nixos.html#stylixautoenable).
 
-Or even choose monospace for everything:
+The available targets differ between Home Manager and NixOS. If a target
+is available in both, it is always fine to enable both.
 
-```nix
-{
-  stylix.fonts = {
-    serif = config.stylix.fonts.monospace;
-    sansSerif = config.stylix.fonts.monospace;
-    emoji = config.stylix.fonts.monospace;
-  };
-}
-```
+The reference pages have a list of targets for [NixOS](options/nixos.md) and
+[Home Manager](options/hm.md) respectively.
 
 ## Multi-user configurations
 
-For those apps which are configured through Home Manager, Stylix allows you to
-choose a different theme for each user. This can be done by setting the theme
-within Home Manager for that user rather than at the system level.
-
-By default, all users follow the system theme. This can be turned off by
-setting `stylix.homeManagerIntegration.followSystem = false`, in which case you
-must explicitly set a theme for each user. Setting that option is not required
-just to be able to override an individual theme.
+For those apps which are configured through Home Manager, Stylix can set a
+different theme for each user.
 
-If you would like to disable all Home Manager activity for a user, you can set
-`stylix.homeManagerIntegration.autoImport = false`, then manually import the
-Home Manager module for the users for which it should be enabled.
+If Home Manager and NixOS are configured together, then the system theme will
+be copied into the Home Manager configuration for each user. You can adjust
+the settings in Home Manager for a particular user, and this will override the
+system theme.
 
-Note that if the wallpaper image for a user is different to the rest of the
-system, a separate theme will always be generated for them, even though their
-`base16Scheme` option has not been overridden. If you want that user to follow
-the system theme while having a different wallpaper, you will need to manually
-copy the system theme into their configuration. (This behaviour is necessary as
-otherwise it would be impossible to use a generated theme for a user while
-having a manually created theme for the rest of the system.)
-
-## Turning targets on and off
-
-In Stylix terms, a target is anything which can have colors, fonts or a
-wallpaper applied to it. Each module in this repository should correspond to a
-target of the same name.
-
-Each target has an option like `stylix.targets.«target».enable` to turn its
-styling on or off. Normally, it's turned on automatically when the target is
-installed. You can set `stylix.autoEnable = false` to opt out of this
-behaviour, in which case you'll need to manually enable each target you want to
-be styled.
-
-Targets are different between Home Manager and NixOS, and sometimes available
-in both cases. If both are available, it is always correct to enable both.
-The reference pages have a list of targets for [NixOS](options/nixos.md) and
-[Home Manager](options/hm.md) respectively.
+If you only want Stylix to affect certain accounts, you can set
+`stylix.homeManagerIntegration.autoImport = false`, then manually import Stylix
+into Home Manager for the accounts which should be themed.
diff --git a/docs/src/installation.md b/docs/src/installation.md
@@ -119,7 +119,9 @@ let
 in {
     imports = [ (import stylix).homeManagerModules.stylix ];
 
-    stylix.image = ./wallpaper.jpg;
+    stylix.wallpaper = config.lib.stylix.types.wallpaper.from.image {
+      file = ./wallpaper.jpg;
+    };
 }
 
 ```

diff --git a/docs/src/modules.md b/docs/src/modules.md
@@ -62,14 +62,12 @@ The human readable name must fit into the following sentence:
 Refer to the [style guide](./styling.md) to see how colors are named,
 and where to use each one.
 
-The colors are exported under `config.lib.stylix.colors`, which originates from
-[`mkSchemeAttrs`](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs).
-
-You can use the values directly:
+The colors are exported under `config.stylix.colors`. You can use the values
+directly:
 
 ```nix
 {
-  environment.variables.MY_APPLICATION_COLOR = config.lib.stylix.colors.base05;
+  some.program.color = config.stylix.colors.base05;
 }
 ```
 
@@ -78,8 +76,8 @@ it as a function. This returns a derivation which builds the template.
 
 ```nix
 {
-  environment.variables.MY_APPLICATION_CONFIG_FILE =
-    let configFile = config.lib.stylix.colors {
+  some.program.configPath =
+    let configFile = config.stylix.colors {
       template = ./config.toml.mustache;
       extension = ".toml";
     };
@@ -94,7 +92,40 @@ individually.
 Also note that reading generated files with `builtins.readFile` can be very
 slow and should be avoided.
 
+## How to apply wallpapers
+
+If your module will only support image wallpapers, then you can use
+the image as follows:
+
+```nix
+{
+  some.program.wallpaper = config.stylix.wallpaper.as.image.file;
+}
+```
+
+Otherwise, use `unpack`:
+
+```nix
+{
+  some.program.wallpaperURIs = config.stylix.wallpaper.unpack {
+    slideshow =
+      { files, ... }:
+      map (f: "file://${f}") files;
+
+    image =
+      { file, ... }:
+      [ "file://${file}" ];
+  };
+}
+```
+
+This calls the corresponding function for the type of wallpaper which the user
+selected, kind of like [pattern matching](https://stackoverflow.com/a/2225811).
+
+It's essential that still images are handled correctly, since any other missing
+types can be converted to that.
+
 ## How to apply other things
 
-For everything else, like fonts and wallpapers, you can just take option values
+For everything else, like fonts, you can just take option values
 directly from `config`. See the reference pages for a list of options.
diff --git a/docs/src/tricks.md b/docs/src/tricks.md
@@ -16,9 +16,11 @@ let
   fillColor = "black"
 in
 {
-  stylix.image = pkgs.runCommand "dimmed-background.png" { } ''
-    ${pkgs.imagemagick}/bin/convert "${inputImage}" -brightness-contrast ${brightness},${contrast} -fill ${fillColor} $out
-  '';
+  stylix.wallpaper = config.lib.stylix.types.wallpaper.from.image {
+    file = pkgs.runCommand "dimmed-background.png" { } ''
+      ${pkgs.imagemagick}/bin/convert "${inputImage}" -brightness-contrast ${brightness},${contrast} -fill ${fillColor} $out
+    '';
+  };
 }
 ```
 

diff --git a/docs/src/wallpaper-support.md b/docs/src/wallpaper-support.md
@@ -0,0 +1,15 @@
+# Wallpaper support
+
+|              | Image | Slideshow | Animation | Video |
+|--------------|-------|-----------|-----------|-------|
+| bspwm        | ✔️     | ✔️         | ✔️         | ✔️     |
+| GNOME        | ✔️     | ✔️         | ❌         | ❌     |
+| GRUB         | ✔️     | ❌         | ❌         | ❌     |
+| herbstluftwm | ✔️     | ✔️         | ✔️         | ✔️     |
+| Hyprland     | ✔️     | ✔️         | ✔️         | ✔️     |
+| i3           | ✔️     | ✔️         | ✔️         | ✔️     |
+| KDE          | ✔️     | ❌         | ❌         | ❌     |
+| LightDM      | ✔️     | ❌         | ❌         | ❌     |
+| spectrwm     | ✔️     | ✔️         | ✔️         | ✔️     |
+| Sway         | ✔️     | ✔️         | ✔️         | ✔️     |
+| Xmonad       | ✔️     | ✔️         | ✔️         | ✔️     |