diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 96 |
1 files changed, 92 insertions, 4 deletions
@@ -13,16 +13,99 @@ the working config cannot drift from what is committed. Everything outside `~/.config/rofi/udt/` and `~/bin/` was edited in place; `docs/MIGRATION.md` is the record of what changed and where the backups are. +## One palette, many consumers + +Colours are written down once. `palette/<scheme>.conf` holds them under the +scheme's own names and `palette/roles-<scheme>.conf` says what each is for. +`bin/udt-palette` renders that pair into every consumer's own syntax; +`install.sh` runs it first, before anything is linked. + +**The scheme selection lives outside the repo**, in `~/.config/udt/roles.conf`, +seeded from `palette/roles.conf.default` on a first install and never +overwritten after. That is deliberate: which theme a machine runs is local +state, so switching does not dirty the working tree and two machines sharing +this repo can differ. It is the one exception to this repo holding the +canonical copy of everything. + +Nine schemes ship: `macchiato`, `frappe`, `mocha`, `tokyo-night`, `nord`, `dracula`, +`material-ocean`, `material-palenight`, `material-darker`. Switching is one line in +`~/.config/udt/roles.conf` plus `./install.sh`. + +All nine are dark. A light scheme is not a role remap: homepage is pinned +`theme: dark` and its generated card overrides target the dark-mode class, and +`install.sh` would need to flip that setting too. + +Generated files are gitignored, because tracking them would turn every scheme +switch into a diff. Editing one is pointless: the next install overwrites it. +The generated set is `rofi/udt/palette.rasi`, `templates/dunstrc`, +`templates/conky.conf`, `templates/waybar/theme.css`, +`templates/terminal/kitty-theme.conf`, `templates/homepage/custom.css`, +`templates/kvantum/theme.{kvconfig,svg}` and `bin/udt_colors.py`. + +Qt and GTK apps reach the palette through Kvantum. Its theme is a `.kvconfig` +of colours plus a `.svg` of widget artwork with the colours baked into the +paths, so both are templates: the twelve palette colours are placeholders and +the fifteen neutral greys are left alone, because those are shading rather than +theme colour. It installs to `~/.config/Kvantum/udt/` under one fixed name for +every scheme, so switching needs no change to `kvantum.kvconfig` and leaves no +stale theme behind. Derived from `catppuccin-macchiato-lavender`, which this +desktop was already running by hand. + +**Qt apps only read a theme at startup**, so a running one keeps the old +colours until restarted. `install.sh` cannot signal them and does not try. + +Obsidian and Typora are installed by `bin/udt-appthemes`, not by a copy. +Obsidian gets a **snippet**, not a theme, so it layers over whatever theme a +vault uses; enabling it means appending to `enabledCssSnippets` in that vault's +`appearance.json`, never rewriting the list, or the vault loses the snippets it +already had. Every vault under `~/Documents/Obsidian` is found by looking for +`.obsidian` directories, nested ones included. Typora's theme is derived from +its Dracula theme, whose 350 rules all route through `:root` variables, so only +that block is templated. + +Signal, Discord and Spotify cannot be consumers: they ship closed bundles with +no user-CSS hook, and patching a signed app bundle breaks on every update. + +The homepage stylesheet is the one output that leaves this machine. +`install.sh` scp's it to `homepage:hp-stage/`, with a five second timeout and a +warning rather than a failure when the host is down, so installing the local +theme still works off that network. It stages only: `/opt/homepage/config` is +root-owned, and the final copy plus a `systemctl restart homepage` is a manual +step the script prints. homepage's `settings.yaml` must keep `color: gray`, the +theme class the generated CSS targets. The last is +imported by `udt-accent`, which is why its accent table follows the scheme. + +Roles are a flat namespace, so a name collides across sections: conky's outline +is `body_outline` because waybar already has `outline`. A role value is a +palette name with two optional modifiers, `name/75` for 75% alpha and +`name*50` for half brightness. The second exists only because GTK's +`shade(@main-bg, 0.5)` has no palette name to point at: half-brightness crust +is darker than the darkest colour any of these schemes ships. + +**Adding a scheme means adding two files, never editing a consumer.** Every +scheme must define the same role set, and `udt-palette --selftest` enforces +that, then has rofi parse every theme under every scheme. Both checks exist +because both failures shipped: a role set can drift silently, and a palette +that resolves can still emit a theme rofi refuses to parse, which stops every +launcher on the desktop. + ## The accent One colour moves: `@accent`. `bin/udt-accent` reads the current wallpaper, extracts its signature colour, and snaps it to the nearest of ten Catppuccin accents by perceptual hue in CIELAB. `wallp` calls it on every wallpaper change. -It writes four things: `~/.cache/wal/udt-accent.rasi` (rofi), +It writes five things: `~/.cache/wal/udt-accent.rasi` (rofi), `~/.cache/wal/udt-border.lua` (Hyprland), the accent substitution in -`~/.cache/wal/dunstrc`, and `~/.cache/wal/colors.json` (Firefox, via -pywalfox). +`~/.cache/wal/dunstrc`, `~/.cache/wal/colors.json` (Firefox, via +pywalfox), and `~/.cache/wal/udt-palette.qml` (quickshell). + +The QML palette is the one output that is not only the accent: it carries +the whole structural palette too, parsed out of `rofi/udt/palette.rasi` +rather than duplicated in the script. That file stays the single place the +Macchiato values are written down. Quickshell components watch the generated +file and re-read it in place, so a palette edit reaches a running shell +without restarting it; see the `quickshell` repo alongside this one. **Extraction is deliberately isolated from the pywal cache.** It calls `pywal.backends.colorz.get()` directly, which returns a list and writes nothing. @@ -104,12 +187,17 @@ them by exit code: rofi exits non-zero for ordinary reasons such as Escape. - **Themes that reference an image cannot be committed with a real path.** `launcher.rasi` carries an `@WPAPER@` placeholder that `install.sh` rewrites. rofi does not expand `~` inside a `url()`. -- After editing anything under `rofi/udt/`, run `./install.sh`. +- After editing anything under `rofi/udt/` or `palette/`, run `./install.sh`. +- `bin/udt-palette --selftest` resolves every role in every scheme. Run it + after touching a palette, a role map, or the generator. - `bin/udt-accent --selftest` covers the snapping logic. Run it after touching the colour maths. ## Reloading +`./install.sh` reloads everything running, so a scheme switch is one command. +The table is what it does, and what to run if you change a config by hand. + | | How | | --- | --- | | rofi | nothing; the theme is read per launch | |