Theming system

The repo theme source of truth lives in:

• modules/themes//
• modules/system/stylix/default.nix
• modules/user/stylix/default.nix
• lib/stylix-catalog.nix

How it works

1. A host selects a theme with stylix.theme = "<name>"; in hosts/<name>/configuration.nix.
2. The selected theme attrset from modules/themes/<name>/default.nix is imported.
3. The system Stylix module maps that theme to:
   • Base16 colors
   • wallpaper/background image
   • icon theme
   • serif, sans, monospace, and emoji fonts
   • cursor theme and size
4. The user Stylix module applies the same polarity and background on the Home Manager side.

Theme background resolution

Wallpaper selection follows this order:

1. background.file if the file exists inside the theme directory
2. background.url with background.sha256
3. repo root wallpaper.png

Theme structure

Each theme is expected to stay self-contained inside modules/themes/<name>/. The theme may define:

• Base16 palette fields base00 through base0F
• background
• icons
• fonts
• top-level emoji
• cursor
• metadata like scheme, slug, author, description, and polarity

Supported built-in assets

Icons:

• candy-icons
• papirus

Fonts:

• ibm-plex-mono
• ibm-plex-sans
• ibm-plex-serif
• inter
• jetbrains-mono-nerd
• noto-color-emoji
• noto-sans
• noto-serif

Cursor themes:

• bibata-modern-ice
• capitaine-cursors
• capitaine-cursors-white
• rose-pine-cursor
• rose-pine-dawn-cursor

Emoji fonts:

• noto-color-emoji

Current repo themes

• catppuccin-frappe
• catppuccin-mocha
• dracula
• ember
• gruvbox-dark-hard
• gruvbox-dark-medium
• gruvbox-light-hard
• gruvbox-light-medium
• monokai
• orichalcum
• uwunicorn

Theme template

The template for creating a new theme lives at:

• /home/ftmahringer/nixos-config/modules/themes/TEMPLATE/default.nix
• /home/ftmahringer/nixos-config/modules/themes/TEMPLATE/README.md

Template notes:

This template supports the same optional fields as your live themes: background, icons, fonts, emoji, and cursor, plus the required Base16 palette values.

Place your theme-local wallpaper here, for example as wallpaper.png, wallpaper.jpg, wallpaper.svg, or wallpaper.gif, and then point background.file at it from default.nix.

Wallpaper fallback order:

1. background.file if the file exists
2. background.url with background.sha256
3. /home/ftmahringer/nixos-config/wallpaper.png

Template example:

{
  scheme = "Template";
  slug = "ft-theme-template";
  author = "Fynn Mahringer";
  description = "Just a tempalte for adding more themes later";
  polarity = "dark";

  # Background priority:
  # 1. Use `background.file` if it exists.
  # 2. Otherwise use `background.url` with `background.sha256`.
  # 3. Otherwise fall back to `/home/ftmahringer/nixos-config/wallpaper.png`.
  background = {
    file = ./wallpaper.png;

    # Optional remote fallback:
    # url = "https://example.com/wallpaper.png";
    # sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  # Optional icon theme.
  # Supported values currently:
  # - "papirus"
  # - "candy-icons"
  # Unknown values fall back to the config default.
  icons = "papirus";

  # Optional font selection.
  # Supported values currently:
  # - "noto-serif"
  # - "noto-sans"
  # - "inter"
  # - "ibm-plex-serif"
  # - "ibm-plex-sans"
  # - "ibm-plex-mono"
  # - "jetbrains-mono-nerd"
  # - "noto-color-emoji"
  # Unknown values fall back to the config defaults.
  fonts = {
    serif = "noto-serif";
    sansSerif = "noto-sans";
    monospace = "jetbrains-mono-nerd";
    emoji = "noto-color-emoji";

    # Optional size overrides:
    # sizes = {
    #   applications = 12;
    #   desktop = 11;
    #   popups = 11;
    #   terminal = 12;
    # };
  };

  # Optional top-level emoji override.
  # If omitted, `fonts.emoji` is used.
  # Unknown values fall back to the config default.
  # emoji = "noto-color-emoji";

  # Optional cursor theme.
  # Supported values currently:
  # - "bibata-modern-ice"
  # - "capitaine-cursors"
  # - "capitaine-cursors-white"
  # - "rose-pine-cursor"
  # - "rose-pine-dawn-cursor"
  # Unknown values fall back to the config default.
  cursor = {
    family = "bibata-modern-ice";
    size = 24;
  };

  # The remaining fields are the Base16 palette used by Stylix.
  # Keep these as 6-character hex values without `#`.

  base00 = "000000";
  base01 = "111111";
  base02 = "222222";
  base03 = "333333";
  base04 = "444444";
  base05 = "cccccc";
  base06 = "dddddd";
  base07 = "eeeeee";
  base08 = "ff5555";
  base09 = "ffb86c";
  base0A = "f1fa8c";
  base0B = "50fa7b";
  base0C = "8be9fd";
  base0D = "6272a4";
  base0E = "bd93f9";
  base0F = "ff79c6";
}