add-theme

# Add a theme pack One command themes everything: `bin/theme <name>` renders the pack into `~/.local/state/theme/current/theme/` and nudges every consumer. A pack is `themes/<name>/` and needs only: - `colors.toml` — the contract. Either style: semantic (`mode`, `accent`, `background`, `foreground`, `muted`, `red`, `bright_red`, `dark_background`, ...) or ANSI (`accent`, `background`, `foreground`, `color0`-`color15`). `bin/theme-color -f colors.toml --all` shows the full set after aliasing and derivation; anything missing is mixed from what is there. - `backgrounds/` — images. `theme <name> [N]` picks the Nth (sorted by name), `theme bg next` cycles. Name them `<index>-<description>.<ext>`; the fzf picker previews the filename. - `theme.conf` — `TAGLINE="one line of whimsy"` (printed on switch, shown in the tmux cheat sheet). Optional but every pack has one. - `icons.theme` — optional, a GTK icon theme name (Yaru-* is common); applied on Linux only if that icon set is installed. Every app file (ghostty, kitty, wezterm, tmux, nvim, btop, starship, pi, claude, hyprland borders, hyprlock, wofi, sketchybar, borders, slack) is rendered from `themes/templates/*.tpl`. A pack may ship a file under the same name to hand-tune one app (`hyprland.lua` for a gradient border, `btop.theme`, ...); it wins over the template. Do NOT hand-author the rest. Work directly in the repo (subagent worktrees don't see uncommitted theme files and have flipped the user's live theme by running theme from the wrong tree — do NOT run theme for validation until told, and never from a worktree). ## Sources - **An existing theme repo** (any `themes/<name>/` laid out as above): copy `colors.toml`, `backgrounds/`, `icons.theme`. Skip `neovim.lua`, `vscode.json`, `preview*.png`, `unlock.png`, `shell*.toml`, `keyboard.rgb`, `chromium.theme`. Keep a shipped `btop.theme`; keep a shipped `hyprland.lua` only if it is plain `hl.config` (the `o.window(...)` helper style some repos use does not exist here). An older theme with only `alacritty.toml` and no `colors.toml`: transcribe its `[colors.*]` into ANSI-style `colors.toml`. - **Just a wallpaper**: first run `bin/theme adopt <image>`. It compares the extracted palette with every existing pack and, when the closest score is 60 or lower, copies the image into that pack's `backgrounds/` with the next numeric prefix. A weaker match changes nothing and prints the three closest packs. Then use `bin/theme from-image <name> <image>` to create a new pack; it writes `colors.toml` + `backgrounds/` + an empty `theme.conf`. Both commands use heuristic hue mapping, so eyeball the result. Then write `theme.conf` with a TAGLINE in the house style (see `themes/*/theme.conf`: short, lower-case, a little wry). ## Validate (no theme run) ``` bin/theme-color -f themes/<name>/colors.toml --all # no error, sane mode bin/theme-color -f themes/<name>/colors.toml --name <name> --render /tmp/x themes/templates/*.tpl jq empty /tmp/x/*.json; bash -n /tmp/x/*.sh ghostty +validate-config --config-file=/tmp/x/ghostty.conf ``` A rendered file containing `{{` means a template names a key the resolver does not produce; fix the template, not the pack. ## Hand verification to the user or ask before switching `theme <name> [N]`, then: `tmux show-option -gqv @thm_pink` == accent; `cat ~/.local/state/theme/current/mode`; `jq -r .theme ~/.claude/settings.json` == `custom:<name>`. Linux: `hyprctl getoption general:col.active_border`, `gsettings get org.gnome.desktop.interface color-scheme`. macOS: sketchybar border colour, wallpaper after a few seconds. Pi applies on next launch. ## Commit on the active theme branch and push. ## Removing a theme `git rm -r themes/<name>/`, then `theme <other>`. The rendered `~/.pi/agent/themes/<name>.json` and `~/.claude/themes/<name>.json` can go too.