diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d205bcd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,210 @@ +# AGENTS.md + +Guidance for agents working in this repository. + +## What this is + +One visual identity for a Hyprland desktop: Catppuccin Macchiato, Noto Sans for +UI text, Inconsolata Nerd Font Mono for monospace. It covers rofi, dunst, +Hyprland window borders, conky, Qt5/Qt6, GTK3/GTK4, waybar, kitty and neovim. + +The repo holds the canonical copies. `./install.sh` symlinks them into place, so +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 five things: `~/.cache/wal/udt-accent.rasi` (rofi), +`~/.cache/wal/udt-border.lua` (Hyprland), the accent substitution in +`~/.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. +Running `wal -i` instead would rewrite all of `~/.cache/wal`, including the +terminal's ANSI colours, and that is the exact failure this design exists to +avoid. If you change `signature_color()`, verify it still writes nothing. + +`colors.json` is the one pywal file `udt-accent` does rewrite, and it rewrites +it wholesale rather than editing it: a fixed Macchiato palette with the accent +in the cursor and the two highlight slots. That is deliberate. pywalfox reads +`colors.json` and nothing else, so it is the only way Firefox can follow the +accent, and overwriting it costs nothing because nothing else reads it. In +particular kitty reads `~/.config/kitty/current-theme.conf`, not this file, so +the terminal palette stays fixed no matter what the wallpaper looks like. The +write lands after `wallp` has already run `wal --theme`, so it wins; reorder +those two and pywal's wallpaper-derived colours come back. + +Not everything tracks the wallpaper. rofi, dunst, Hyprland borders and Firefox +do; conky, Qt, GTK and waybar sit on fixed lavender, which is also the fallback +when a wallpaper is too grey to snap. Qt and GTK apps only reread a theme on restart, +so a moving accent there would leave running apps disagreeing with new ones. + +## Verifying visual changes + +`rofi -no-config -theme <absolute-path> -dump-theme >/dev/null` catches syntax +errors without a display. It does **not** tell you what renders: it normalises +values, prints `(null)` for every image, and collapses multi-value margins. + +For anything visual, screenshot and measure: + + grim -o DP-1 /tmp/shot.png + +Reasoning about rofi's box model was wrong repeatedly during this project; +measuring pixels was right every time. When a widget looks wrong, measure its +bounding box before theorising about why. + +Rofi needs a display, so these steps run in the user's session. Do not judge +them by exit code: rofi exits non-zero for ordinary reasons such as Escape. + +## Things that are not where they look + +- **rofi is 2.0.0**, not the 1.7.3 its config header claims. `rofi -v` is the + authority. `-width` is gone; width lives in the theme. +- **`userimage` in `powermenu.rasi` only honours its margin.** A `width` with + `expand: false` collapses it to a line, and a percentage margin resolves + against the whole window rather than the padded column. Its 230px margin is + tied to the 680px column in `mainbox`; both move together. +- **A layout that hardcodes `children` silently drops `-mesg`.** That is why + `list.rasi` lists the message widget even though most callers pass nothing. +- **`ClearlyU` is installed and claims large parts of the Private Use Area**, so + it can win fontconfig's fallback and draw a blank where another font has the + glyph. `fc-match ":charset=XXXX" family` says who actually wins. The `U+F0xxx` + Nerd Font ranges avoid the problem. +- **GTK3's theme comes from gsettings on Wayland**, not `settings.ini`. It was + pinned to `Breeze`, silently overriding the file, for who knows how long. +- **GTK4 ignores `gtk-theme-name`.** Its stylesheet is symlinked into + `~/.config/gtk-4.0/theme` and imported by `gtk.css`. +- **Hyprland's Lua parser refuses `hyprctl keyword`** ("keyword can't work with + non-legacy parsers") and has no source directive. The border colours are a Lua + table read with `dofile()`. +- **`wallp` starts `swaybg` in the background**, which inherits the shell's + stdout, so a pipe or command substitution appears to hang after `wallp` has + already finished. Redirect its output when calling it from a script. +- **waybar's own CLAUDE.md documents a stale CSS load order.** The + `modules-*.css` and `states.css` files it names are not imported by anything; + `style.css` pulls in `styles/main.css`. One of the dead files holds a + `font-family` that looks authoritative but does nothing. + +## Editing rules + +- **conky**: change colours in the `conky.config` block only. `conky.text` is + laid out with absolute `${goto}` pixel offsets tuned to label widths, so + editing text means re-tuning every goto on that line. See + `~/.config/conky/CLAUDE.md`. Conky does not hot-reload. +- **Committed files carry no home paths.** A gitleaks hook blocks them, and it + has been right every time. Where a live config mixes theme keys with personal + data (`qt6ct.conf` has an `ignored_applications` list), track only the + theme-relevant keys. +- **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/` 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 | +| dunst | `udt-accent` restarts it | +| Firefox | `udt-accent` runs `pywalfox update` | +| Hyprland | `hyprctl reload` | +| waybar | `killall -SIGUSR2 waybar` | +| kitty | `pkill -USR1 -x kitty` | +| conky | restart it; no hot-reload | +| Qt / GTK apps | restart the app | |