diff options
| -rw-r--r-- | AGENTS.md | 122 | ||||
| -rw-r--r-- | CLAUDE.md | 7 | ||||
| -rwxr-xr-x | bin/udt-accent | 55 |
3 files changed, 184 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bd67064 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,122 @@ +# 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. + +## 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), +`~/.cache/wal/udt-border.lua` (Hyprland), the accent substitution in +`~/.cache/wal/dunstrc`, and `~/.cache/wal/colors.json` (Firefox, via +pywalfox). + +**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/`, run `./install.sh`. +- `bin/udt-accent --selftest` covers the snapping logic. Run it after touching + the colour maths. + +## Reloading + +| | 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 | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3599d0e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md + +This file is intentionally thin. AGENTS.md is the single source of truth for +this project, shared across every agent tool. Do not duplicate content here, +edit AGENTS.md instead. + +@AGENTS.md diff --git a/bin/udt-accent b/bin/udt-accent index e88a512..703f483 100755 --- a/bin/udt-accent +++ b/bin/udt-accent @@ -12,6 +12,7 @@ running `wal -i`, because `wal -i` rewrites the whole ~/.cache/wal directory including the terminal's ANSI colors. See the design spec for why that matters. """ +import json import math import os import subprocess @@ -43,6 +44,19 @@ MIN_CHROMA = 10.0 OUTPUT = Path.home() / ".cache" / "wal" / "udt-accent.rasi" BORDER_OUTPUT = Path.home() / ".cache" / "wal" / "udt-border.lua" DUNSTRC = Path.home() / ".cache" / "wal" / "dunstrc" +COLORS_JSON = Path.home() / ".cache" / "wal" / "colors.json" + +# Catppuccin Macchiato, in pywal's slot order. Firefox is themed from this +# via pywalfox, which reads colors.json and nothing else. +MACCHIATO = { + "background": "#24273a", "foreground": "#cad3f5", "cursor": "#f4dbd6", + "colors": [ + "#494d64", "#ed8796", "#a6da95", "#eed49f", + "#8aadf4", "#f5bde6", "#8bd5ca", "#b8c0e0", + "#5b6078", "#ed8796", "#a6da95", "#eed49f", + "#8aadf4", "#f5bde6", "#8bd5ca", "#a5adcb", + ], +} def _to_lab(hexval): @@ -166,6 +180,46 @@ def write_border(name): raise +def write_colors_json(name, image): + """Rewrite colors.json as Macchiato with the accent in the highlight slots. + + pywalfox reads this file and nothing else, so this is how Firefox tracks the + wallpaper. pywal wrote the file moments earlier with wallpaper-derived ANSI + colours; this replaces them wholesale, which is the point: the terminal + palette stays fixed Macchiato while only the accent moves. + """ + hexval = ACCENTS[name] + colors = list(MACCHIATO["colors"]) + # Slots 4 and 12 are pywalfox's link/highlight colour. + colors[4] = colors[12] = hexval + + doc = { + "wallpaper": str(image), + "alpha": "100", + "special": { + "background": MACCHIATO["background"], + "foreground": MACCHIATO["foreground"], + "cursor": hexval, + }, + "colors": {f"color{i}": c for i, c in enumerate(colors)}, + } + + fd, tmp = tempfile.mkstemp(dir=str(COLORS_JSON.parent), suffix=".tmp") + try: + with os.fdopen(fd, "w") as handle: + json.dump(doc, handle, indent=4) + handle.write("\n") + os.replace(tmp, COLORS_JSON) + except BaseException: + if os.path.exists(tmp): + os.unlink(tmp) + raise + + # Firefox only picks the new colours up when pywalfox pushes them. Never + # fatal: pywalfox may not be installed, and the desktop theme is unaffected. + subprocess.run(["pywalfox", "update"], capture_output=True, check=False) + + def write_dunst(name): """Substitute the accent into the dunst config pywal just rendered. @@ -209,6 +263,7 @@ def main(image): write_accent(name) write_border(name) write_dunst(name) + write_colors_json(name, image) # Hyprland only rereads its config on request, and may not be running. subprocess.run(["hyprctl", "reload"], capture_output=True, check=False) |