From 82dfcae2225e4313f400e87e97b1e5f42a0e7b3f Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Wed, 16 Sep 2026 09:23:17 +0200 Subject: docs(gtk): record GTK as a generated consumer AGENTS.md listed GTK3/GTK4 among the covered consumers, but nothing generated or installed a theme for it: the claim had been aspirational since the repo started. It now describes what the code does, and says plainly that the old state was a gap rather than a drift. templates/qt-gtk/ documented both Qt and GTK as installed from upstream. Qt still derives from catppuccin/Kvantum and GTK from catppuccin/gtk, but both are generated here now, so the table and the gsettings line say 'udt'. Its tracked gtk3-settings.ini carried the old theme name too, which made the record disagree with the live config it mirrors. Co-Authored-By: Claude Opus 5 --- templates/gtk/README.md | 66 ++++++++++++++++++++++++++++++++++++++ templates/qt-gtk/README.md | 16 +++++---- templates/qt-gtk/gtk3-settings.ini | 2 +- 3 files changed, 76 insertions(+), 8 deletions(-) create mode 100644 templates/gtk/README.md (limited to 'templates') diff --git a/templates/gtk/README.md b/templates/gtk/README.md new file mode 100644 index 0000000..adfc092 --- /dev/null +++ b/templates/gtk/README.md @@ -0,0 +1,66 @@ +# GTK3 and GTK4 + +Generated from the palette, installed as `~/.themes/udt`. One fixed name for +every scheme, like Kvantum: the name is referenced by gsettings and by the +GTK4 symlink, so a per-scheme name would mean rewriting both on every switch +and leaving stale themes behind. + +Derived from `catppuccin/gtk` v1.0.3, which is **archived upstream**. Forking +it is deliberate: it is the theme this desktop already ran, and it will not +track future GTK4/libadwaita changes. Replacing it means replacing these +templates, not editing a consumer. + +## What is substituted + +Colours appear in two forms and both are replaced: the hex (`#b7bdf8`) and the +bare decimal triple GTK writes inside `rgba()` (`183, 189, 248`). Substitution +is whole-file, not confined to the `@define-color` block at the tail, because +the 8400 lines above it hardcode palette colours too. That was measured, not +assumed: 338 occurrences in GTK3 and 328 in GTK4 sit outside the block. + +`#eff1f5` is upstream's foreground, which is Latte `text`, a near-white it +pairs with a Macchiato background. It maps to the `fg` role so GTK text matches +rofi, kitty and waybar rather than being brighter than all of them. + +The generator replaces `@ROLE_RGB@` before `@ROLE@`, because `@FG@` is a prefix +of `@FG_RGB@` and the other order would eat the start of the triple placeholder +and leave a literal `_RGB@` in the CSS. + +## What is left alone + +Neutral greys and upstream's derived tints: `#3e4152`, `#2e3143`, the +`rgba(0, 0, 0, ...)` shadows, `#ffffff`, and the `*_500`/`*_700`/`*_900` +Material swatch constants, which ship with every build and are not theme +colour. Same rule as the Kvantum SVG: shading is not palette. + +Two derived values are mapped anyway, because they are semantic rather than +shading: `17, 17, 27` (Latte crust, used as text on the accent) becomes +`bg_deep`, and `182, 106, 119` (a darkened red on the close button) becomes +`critical`. + +## Assets + +67 SVGs, carrying only three palette colours: `bg`, `bg_alt` and the accent, +the last in 36 of them. The upstream `gtk-3.0/assets` and `gtk-4.0/assets` +directories are byte-identical, so one templated set is rendered and copied +into both. + +They are discovered from disk by the generator rather than listed, because +they arrive as a set from upstream and a hand-written list would silently miss +one added by a future refresh. + +## Gotchas + +- **GTK3 takes its theme name from gsettings on Wayland**, not `settings.ini`. + The file is written too, but gsettings wins; it was once pinned to `Breeze`, + silently overriding the file for who knows how long. +- **GTK4 ignores `gtk-theme-name` entirely.** Its stylesheet is imported by + `~/.config/gtk-4.0/gtk.css` through the `theme` symlink. +- **`gtk-dark.css` must exist** alongside `gtk.css`. Apps request one or the + other depending on the prefer-dark setting; upstream ships them identical. +- **GTK apps only reread a theme at startup**, like Qt. A running app keeps the + old colours, which is why the accent here is the fixed fallback rather than + the wallpaper-tracking one. +- **A placeholder with no matching role renders literally** and GTK drops the + declaration with no error. `udt-palette --selftest` asserts every placeholder + in these templates maps to a role, because 8500 lines is too much to eyeball. diff --git a/templates/qt-gtk/README.md b/templates/qt-gtk/README.md index c7c951b..7d3910a 100644 --- a/templates/qt-gtk/README.md +++ b/templates/qt-gtk/README.md @@ -9,16 +9,18 @@ accent lands on the same colour. ## Upstream themes -Neither is generated by this repo; both are installed from upstream. +Both are generated by this repo now, each derived from an upstream theme +rather than installed from one. -| | Theme | Source | +| | Theme | Derived from | | --- | --- | --- | -| Qt5 + Qt6 | `catppuccin-macchiato-lavender` | `catppuccin/Kvantum` | -| GTK3 + GTK4 | `catppuccin-macchiato-lavender-standard+default` | `catppuccin/gtk` v1.0.3 | +| Qt5 + Qt6 | `udt` | `catppuccin/Kvantum` | +| GTK3 + GTK4 | `udt` | `catppuccin/gtk` v1.0.3 | `catppuccin/gtk` is **archived upstream**. v1.0.3 works and is what the -ecosystem uses, but it will not track future GTK4/libadwaita changes. Removing -it is just deleting the directory from `~/.themes`. +ecosystem uses, but it will not track future GTK4/libadwaita changes. Since +the theme is now a set of templates in this repo, replacing it means replacing +those; see `templates/gtk/README.md`. ## Wiring @@ -35,6 +37,6 @@ it is just deleting the directory from `~/.themes`. ## Reproducing - gsettings set org.gnome.desktop.interface gtk-theme 'catppuccin-macchiato-lavender-standard+default' + gsettings set org.gnome.desktop.interface gtk-theme 'udt' gsettings set org.gnome.desktop.interface icon-theme 'Material-Black-Plum-Suru' gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark' diff --git a/templates/qt-gtk/gtk3-settings.ini b/templates/qt-gtk/gtk3-settings.ini index a35a2ea..d434da8 100644 --- a/templates/qt-gtk/gtk3-settings.ini +++ b/templates/qt-gtk/gtk3-settings.ini @@ -10,7 +10,7 @@ gtk-icon-theme-name=Material-Black-Plum-Suru gtk-menu-images=1 gtk-modules=colorreload-gtk-module:window-decorations-gtk-module gtk-primary-button-warps-slider=false -gtk-theme-name=catppuccin-macchiato-lavender-standard+default +gtk-theme-name=udt gtk-toolbar-style=GTK_TOOLBAR_BOTH_HORIZ gtk-xft-dpi=98304 gtk-toolbar-icon-size=GTK_ICON_SIZE_LARGE_TOOLBAR -- cgit v1.2.3