Theming - Ziad0dev/dots GitHub Wiki

One palette file per theme, a directory of templates, and themectl to render one into the other. Switching themes writes only to ~/.local/state/dots/ — never into the repo, so it never shows up in git status.

themectl list                 # 46 themes
themectl set kanagawa
themectl set auto             # palette from the current wallpaper (matugen)
themectl set auto ~/x.jpg     # …or from a given image
                              # while auto is current, themectl bg … re-derives it
themectl next                 # / prev — alphabetical, wraps
themectl current
themectl reload               # re-render the current theme (after editing a template)
themectl render               # same files, but no app reloads and no wallpaper change

themectl bg                   # print current wallpaper
themectl bg next              # / prev — cycles ~/Pictures/wallpapers
themectl bg set ~/Pictures/wallpapers/x.jpg

Or: SUPER + CTRL + SHIFT + Space (theme picker), SUPER + SHIFT + T (next theme), SUPER + E (wallpaper picker), SUPER + CTRL + E (next wallpaper).

themectl is in every profile (home/themectl.nix), so the minimal one's prompt, fzf, tmux, Neovim and btop are themed too.

A fresh home gets dots.theme (oxocarbon) on its first activation, so nothing starts unstyled. With dots.liveConfig = false the rendered files and links point into the generation's store path, so every switch also runs themectl render.

1. Sources config/themes/<name>/colors.sh (or theme.sh), computes five derived colours, and renders every config/themes/_templates/*.in into ~/.local/state/dots/theme/.
2. Records the name in ~/.local/state/dots/theme/current.
3. Points ~/.local/state/dots/shell/current/ at the palette, wallpaper directory, preview and background — what Quickshell and the lock screen read.
4. Writes /var/lib/dots-theme/sddm.json for the login greeter (if the directory is writable).
5. Links or copies the rendered Kvantum, GTK and Vencord files into place, and concatenates config/zen/sites/*.css into zen-sites.css.
6. Reloads: Ghostty (SIGUSR2), Quickshell (theme reload over IPC), GTK (theme name bounce), btop (SIGUSR2), tmux, dunst (sway only), Hyprland, swayosd. Zen reads its CSS only at startup.
7. If the theme ships a wallpaper.*, sets it with a random awww transition.

config/themes/<name>/colors.sh — sourced by bash, so plain key="#rrggbb" lines. All 47 keys are expected:

Optional: border — the Hyprland active border becomes color0 → border → color0 (fading out at both ends) instead of the default color0 → color1, and the Quickshell frame rim and lock-screen band use it blended 55 % toward background instead of color1.

The Quickshell bar and lock screen take their muted text from color8 but lift it toward foreground until it reaches a 4.5:1 contrast against background (Palette.js) — terminal "bright black" is often far darker (oled: 1.85:1).

themectl adds five derived colours — dim, muted (foreground blended 35 % / 60 % toward background), surface (background 8 % toward foreground), accent_dim and accent_container (accent blended 25 % / 72 % toward background). Several palettes have base03 == base04 == base05; templates that need a readable grey ramp should use these instead.

Other files in a theme directory:

Templates use ${key} for #rrggbb, ${key_hex} for the bare hex (Hyprland's rgb() wants that) and ${key_rgb} for r g b decimals. Substitution is envsubst with an explicit variable list, so anything that isn't a palette key — $TIME, $HOME, shell variables in the target format — passes through untouched.

Not template-driven but still themed:

cp -r ~/dots/config/themes/kanagawa ~/dots/config/themes/mytheme
$EDITOR ~/dots/config/themes/mytheme/colors.sh
# drop in wallpaper.jpg / preview.png if you have them
themectl set mytheme

No rebuild — themectl reads the working tree directly. git add it when you're happy.

Every key must be present. themectl set checks before rendering and refuses with theme '<name>' is missing palette keys: …, leaving the previous theme in place — copying an existing palette and editing values is the safe way to start.

A rebuild is needed if you make the new theme dots.sddm.theme or dots.theme, since those are baked.

1. Write config/themes/_templates/<name>.in using ${key} / ${key_hex}.
2. themectl reload — every *.in is rendered automatically, no registration.
3. Point the app at ~/.local/state/dots/theme/<name>: a mkOutOfStoreSymlink in a home module, an include line in the app's own config under config/, or a *_compat step in scripts/themectl.sh if it needs copying (that last one needs a rebuild — themectl is a packaged script).
4. If the app needs a nudge to pick up changes, add it to reload_apps in scripts/themectl.sh.

If a template references a name that isn't a palette key, it passes through unsubstituted and themectl warns unsubstituted tokens remain in … with the first few offenders. The check matches any ${name} left in the output, so a target format that legitimately uses ${…} will warn too.

• Pool: ~/Pictures/wallpapers (top level only; jpg/jpeg/png/webp).
• dots-set-wallpaper <file> runs awww img with a random transition and records the file at ~/.local/state/dots/theme/wallpaper.
• dots-current-wallpaper reads that link (falling back to awww query).
• Setting a theme with its own wallpaper.* overrides the current wallpaper; setting one without leaves it alone.

_{Source: docs/theming.md}