bitzdots

1# Theming
2 
3How the automatic color theming pipeline works in bitzdots.
4 
5## Overview
6 
7```
8Wallpaper image
9    ↓ matugen (fastresize backend, saliencedark16 palette, salience colorspace)
1016-color palette (background, foreground, 8 accent colors, 8 terminal colors)
11    ↓ 25 Jinja2 templates
12Config files for every component
13    ↓ reload-theme.sh
14All running apps pick up new colors
15```
16 
17## The Pipeline in Detail
18 
19### 1. Color Extraction
20 
21**matugen** analyzes your wallpaper image using the `fastresize` backend and `salience` colorspace to extract a `saliencedark16` palette. It starts with the most salient and contrasting color:
22 
23| Index | Usage |
24|-------|-------|
25| `background` / `color0` | Base backgrounds |
26| `foreground` / `color15` | Primary text |
27| `color1`-`color9` | Accent colors (active borders, highlights) |
28| `color8`-`color15` | Terminal ANSI colors |
29 
30Contrast checking is enabled. matugen ensures text remains readable.
31 
32### 2. Template Rendering
33 
3426 Jinja2 templates in `matugen/templates/` use matugen color variables:
35 
36```jinja2
37{{background}}       → #1a1218
38{{foreground}}       → #f2dde4
39{{color1}}           → #f4a0b8
40{{color0}}           → #1a1218
41{{color8}}           → #3d2838
42```
43 
44Templates render into component config files:
45 
46```toml
47# config.toml snippet
48[waybar-css]
49template = "waybar.css.j2"
50target = "~/.config/waybar/style.css"
51 
52[kitty-colors]
53template = "kitty-colors.conf.j2"
54target = "~/.config/kitty/colors.conf"
55```
56 
57### 3. Cache Daemon
58 
59The `matugen-cache-daemon.service` runs at low priority (Nice=19) and:
60 
611. **Watches** `~/Pictures/Wallpapers/` and `~/Pictures/Wallpapers/live/` via `inotifywait`
622. **Debounces** file changes (waits for stability)
633. **Pre-generates** color palettes for every wallpaper in the background
644. **Skips** problematic images with a 24-hour cooldown to avoid repeating failures
655. **Uses file locking** to prevent concurrent runs
66 
67When you select a wallpaper from the picker, the theme applies without waiting for matugen to run.
68 
69### 4. Theme Reload
70 
71When a wallpaper is changed, `reload-theme.sh`:
72 
731. Runs matugen to generate new configs from templates
742. Reloads swaync CSS (notifies swaync to re-read style.css)
753. Reloads Quick Shelf if it is running
764. Updates Hyprland border colors from `colors.lua`
775. Restarts waybar so all module colors refresh
78 
79Quick Shelf (`qs` / `quickShelf`, hosted at https://github.com/bitzzdev/quickShelf)
80reads the generated palette from `~/.config/quick/shelf/colors.css`. Its TUI accepts
81the same hex, `rgb(...)`, and `rgba(...)` values used by the rest of the generated theme.
82When bitzdots is active, no second Quick Shelf palette or theme configuration is required.
83Users can switch between Bento and List layouts with `dev shelf view`, adjust the 1:1 aspect
84ratio with `dev shelf ratio`, or customize `~/.config/quick/shelf/config.json`.
85 
86See the [Quick Shelf ricing guide](https://github.com/bitzzdev/quickShelf/blob/main/docs/ricing.md)
87for layout, bento geometry, section ordering, and dotfiles linking examples.
88 
89## Backup/Restore Safety
90 
91Before every theme generation, the system:
92 
931. **Backs up** all current generated config files to a timestamped directory
942. **Runs matugen** to generate new configs
953. **On failure**: restores the previous backup, logs the error
964. **On success**: keeps the backup for manual rollback
97 
98This means a bad wallpaper or failed matugen image never --config ~/.config/matugen/config.toml breaks your theme.
99 
100## Template Reference
101 
102All 26 templates in `matugen/templates/`:
103 
104| Template | Target | Purpose |
105|---|---|---|
106| `waybar.css.j2` | `waybar/style.css` | Bar CSS |
107| `waybar-config.jsonc.j2` | `waybar/config.jsonc` | Bar module layout |
108| `swaync.css.j2` | `swaync/style.css` | Notification CSS |
109| `wlogout.css.j2` | `wlogout/style.css` | Logout screen CSS |
110| `hypr-colors.lua.j2` | `hypr/colors.lua` | Border colors |
111| `kitty-colors.conf.j2` | `kitty/colors.conf` | Terminal colors |
112| `cava-colors.j2` | `cava/themes/generated` | Audio visualizer |
113| `rofi-colors.rasi.j2` | `rofi/theme-generated.rasi` | Launcher theme |
114| `quick-shelf.css` | `quick/shelf/colors.css` | Quick Shelf terminal palette |
115| `matugen-env.j2` | `matugen/env` | Color env vars |
116| `browser-colors.css.j2` | `matugen/browser-colors.css` | Browser CSS |
117| `hyprlock.conf.j2` | `hypr/hyprlock.conf` | Lock screen |
118| `kdeglobals.j2` | `kdeglobals` | KDE colors |
119| `qt6ct.conf.j2` | `qt6ct/qt6ct.conf` | Qt6 theme |
120| `bitzdots.colors.j2` | `color-schemes/bitzdots.colors` | KDE scheme |
121| `launcher.rasi.j2` | `rofi/themes/launcher.rasi` | Launcher theme |
122| `clipboard.rasi.j2` | `rofi/themes/clipboard.rasi` | Clipboard theme |
123| `power.rasi.j2` | `rofi/themes/power.rasi` | Power menu theme |
124| `wallpaper-grid.rasi.j2` | `rofi/themes/wallpaper-grid.rasi` | Wallpaper picker |
125| `lock.svg.j2` | `rofi/icons/lock.svg` | Lock icon |
126| `logout.svg.j2` | `rofi/icons/logout.svg` | Logout icon |
127| `reboot.svg.j2` | `rofi/icons/reboot.svg` | Reboot icon |
128| `shutdown.svg.j2` | `rofi/icons/shutdown.svg` | Shutdown icon |
129| `sleep.svg.j2` | `rofi/icons/sleep.svg` | Sleep icon |
130| `cancel.svg.j2` | `rofi/icons/cancel.svg` | Cancel icon |
131| `static.svg.j2` | `rofi/icons/static.svg` | Static wallpaper icon |
132| `live.svg.j2` | `rofi/icons/live.svg` | Live wallpaper icon |
133 
134## Adding a New Themed Component
135 
136See [Customization](customization.md) for the step-by-step guide.
137 
138## Manual Theme Regeneration
139 
140```bash
141# Regenerate from current wallpaper
142matugen image ~/.cache/current_wallpaper.png --config ~/.config/matugen/config.toml
143 
144# Regenerate from a specific image
145matugen image ~/Pictures/Wallpapers/image.jpg --config ~/.config/matugen/config.toml
146 
147# Apply the new theme
148~/.config/matugen/reload-theme.sh
149```
150