Stylix

Stylix uses specific semantic terms to describe how colors should be applied to UI elements to maintain a cohesive theme:

• Alternate: Used for elements that need to look separate but not drastically different from the main UI (e.g., section backgrounds in a settings menu). Use the alternate color for the smaller or less common element.
• On/Off: Used for toggles or status indicators with binary states.
• Lists and Selections: Used for selectable items (like browser tabs). The selection color identifies the active or selected item(s).

If Home Manager is used as part of NixOS, Stylix is automatically installed for all users, inheriting the NixOS theme.

Key Behaviors:

• Multi-user systems: You can override settings in Home Manager to provide unique themes per user.
• Breaking inheritance: If you change stylix.base16Scheme or stylix.override in a Home Manager configuration, it will stop inheriting those specific values from NixOS.
• Wallpaper exception: If you change the wallpaper in Home Manager, it will stop inheriting the color scheme from NixOS, allowing the automatic palette generator to run independently.
• Customization: Use stylix.homeManagerIntegration.autoImport and stylix.homeManagerIntegration.followSystem to control this behavior.

Stylix uses an autoload system based on file naming conventions. Modules must follow the pattern modules/«name»/«platform».nix to be imported automatically.

Supported platforms:

• nixos (NixOS)
• hm (Home Manager)
• darwin (Nix-Darwin)
• droid (Nix-on-Droid)

Example: modules/avizo/hm.nix is a Home Manager module for Avizo. Other files related to the module can reside in the modules/«name» directory as long as they don't match the platform names.

A 'target' is any application or component that can be styled (e.g., Firefox, Alacritty).

• Automatic Enabling: By default, Stylix automatically enables styling for a target whenever that target is installed.
• Manual Control: You can disable this automatic behavior globally by setting stylix.autoEnable = false. In this case, you must manually enable each target using stylix.targets.<target>.enable = true;.
• NixOS vs Home Manager: Targets may differ between platforms. If a target is available in both NixOS and Home Manager, it is recommended to enable it in both.

In Stylix, the total number of testbeds is determined by the product of the number of targets and the number of themes.

Specifically, the calculation is: target × theme.

• target: The number of files located at modules/«target»/testbeds/«target».nix.
• theme: The number of files located at stylix/testbed/themes/«theme».nix.

Caution: Adding new theme modules to stylix/testbed/themes/ will exponentially increase the size of the test suite. Only add themes if necessary.

You can install Stylix into a nix-darwin configuration via Flakes by adding stylix.darwinModules.stylix to your modules.

While Stylix will not theme macOS itself (as macOS lacks the necessary controls), it will automatically set up the Home Manager modules for you if Home Manager is present.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    darwin = {
      url = "github:nix-darwin/nix-darwin";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    stylix = {
      url = "github:nix-community/stylix";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs =
    {
      darwin,
      stylix,
      ...
    }:
    {
      darwinConfigurations."«hostname»" = darwin.lib.darwinSystem {
        system = "aarch64-darwin";
        modules = [
          stylix.darwinModules.stylix
          ./configuration.nix
        ];
      };
    };
}

Every module requires at least one maintainer. If you are not in the Nixpkgs maintainer list, add yourself to /stylix/maintainers.nix.

After adding yourself, you must update the generated maintainers file by running: nix run .#all-maintainers

# Single maintainer
{ lib, ... }:
{
  maintainers = [ lib.maintainers.danth ];
}

# Multiple maintainers
{ lib, ... }:
{
  maintainers = with lib.maintainers; [ danth da157 noahbiewesch ];
}

Stylix automatically generates documentation for options. To improve quality, ensure mkOption calls include a proper type and a detailed description (Markdown is supported). For general module documentation, use the description field in modules/«module»/meta.nix.

To build and view the documentation locally, run: nix run .#doc