managing-themes

@khaneliman/managing-themes

khaneliman

302

14 forks

Updated 1/18/2026

View on GitHub

khanelinix theme system patterns. Use when configuring themes, working with Stylix or Catppuccin, or implementing theme-aware module configuration.

Installation

$skills install @khaneliman/managing-themes

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorykhaneliman/khanelinix

Pathmodules/common/ai-tools/skills/khanelinix/managing-themes/SKILL.md

Branchmain

Scoped Name@khaneliman/managing-themes

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: managing-themes description: "khanelinix theme system patterns. Use when configuring themes, working with Stylix or Catppuccin, or implementing theme-aware module configuration."

Theme System

Theme Hierarchy

Priority (highest to lowest):

Manual theme config - Explicit per-module settings
Catppuccin modules - Catppuccin-specific integration
Stylix - Base16 theming system

Key Principle

Prefer specific theme module customizations over Stylix defaults

Stylix Base

Stylix provides base theming:

stylix = {
  enable = true;
  image = ./wallpaper.png;
  base16Scheme = "catppuccin-mocha";
  polarity = "dark";
};

Catppuccin Overrides

Many apps have dedicated Catppuccin modules:

programs.kitty = {
  enable = true;
  catppuccin.enable = true;  # Uses catppuccin module
};

# Disable stylix for this app
stylix.targets.kitty.enable = false;

Theme-Aware Conditionals

let
  isDark = config.stylix.polarity == "dark";
in
{
  programs.bat.config.theme = lib.mkIf isDark "Catppuccin-mocha";
}

Manual Theme Paths

For apps without theme modules:

xdg.configFile."app/theme.conf".source =
  if config.stylix.polarity == "dark"
  then ./themes/dark.conf
  else ./themes/light.conf;

Theme Configuration Decision Tree

When configuring an application's theme:

Step 1: Check for Catppuccin module

# Search nixpkgs for catppuccin support
nix search nixpkgs catppuccin | grep <app-name>

Step 2A: If Catppuccin module exists → Use it and disable Stylix target

programs.<app> = {
  enable = true;
  catppuccin.enable = true;
  catppuccin.flavor = "mocha";  # or from config.khanelinix.user.theme
};

stylix.targets.<app>.enable = false;  # Prevent conflicts

Step 2B: If no Catppuccin module → Check for built-in theme support

programs.<app> = {
  enable = true;
  theme = "catppuccin-mocha";  # Direct theme name
};

Step 2C: If no theme support → Manual theme files

xdg.configFile."<app>/theme.conf".source =
  if config.stylix.polarity == "dark"
  then ./themes/catppuccin-mocha.conf
  else ./themes/catppuccin-latte.conf;

Step 3: Let Stylix handle it → Last resort fallback

# Do nothing - Stylix will apply base16 theme
# Only if the app supports base16 and no better option exists

Real-World Examples

Example 1: Kitty (has Catppuccin module)

programs.kitty = {
  enable = true;
  catppuccin = {
    enable = true;
    flavor = "mocha";
  };
};

stylix.targets.kitty.enable = false;

Example 2: Waybar (manual theme)

programs.waybar = {
  enable = true;
  style = builtins.readFile (
    if config.stylix.polarity == "dark"
    then ./themes/catppuccin-mocha.css
    else ./themes/catppuccin-latte.css
  );
};

Example 3: Bat (conditional config)

programs.bat = {
  enable = true;
  config.theme = lib.mkIf
    (config.stylix.polarity == "dark")
    "Catppuccin-mocha";
};

Best Practices

Check for Catppuccin module first - Many apps have dedicated support
Disable conflicting Stylix targets when using specific theme modules
Use mkIf for theme conditionals - Clean and readable
Test both polarities when implementing theme-aware config

More by khaneliman

View all

template-creation

302

Create development environment templates and project scaffolding with Nix flakes. Use when creating new project templates, setting up dev shells, configuring language-specific environments, or integrating with CI/CD.

managing-secrets

302

Manages encrypted secrets using sops-nix and age. Use when adding new secrets, rotating keys, debugging secret access, or setting up secret management for new hosts/users.

code-review

302

Conduct thorough, actionable code reviews focusing on critical issues. Use when reviewing pull requests, analyzing code changes, identifying bugs, security vulnerabilities, or suggesting improvements that developers will actually implement.

scaffolding-modules

302

khanelinix directory structure and module placement. Use when creating new modules, deciding where files belong, or understanding the modules/ organization. Covers platform separation (nixos/darwin/home/common) and auto-discovery.