Files

T

jon 6bbdd428db Add assets/themes/README.md — theme architecture + hard-won gotchas

Documents layout, wiring, apply/reload, backup/restore, and the
debugging traps hit this session (Adwaita fallback, machine-generated
settings.ini, GTK4 separate config, @border collision, gtk-menu-images
scope, Whisker #id-not-.class, .gitignore inline comments).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-18 16:55:09 -05:00

3.7 KiB

Raw Blame History

NexusOS desktop theme

XFCE/GTK desktop theme (distinct from the web UI in interface/web/). Lime-green + purple, dark, with tightened menus.

Layout

Path	What
`NexusOS/`	GTK2/3 + xfwm4 theme. GTK3 CSS in `NexusOS/gtk-3.0/` is hand-maintained (no build step).
`NexusOS/gtk-3.0/colors.css`	All color tokens. Edit colors here, not in the widget files.
`NexusOS-icons/`	Icon theme (inherits `Papirus-Dark`).
`../../management/Mint-Y-Nexus/`	XFCE app-icon set.
`_palette.py` + `*-src/build.py`	Regenerate gtk2 / icons / xfwm4 — NOT gtk-3.0.
`install-theme.sh`	Idempotent restore of all the wiring (see below).
`gtk3-user-overrides.css`	Symlinked to `~/.config/gtk-3.0/gtk.css`.

How it's wired (the part backups miss)

The files above are just source. What makes the desktop use them lives outside this folder and is recreated by install-theme.sh:

Symlinks: ~/.themes/NexusOS, ~/.icons/NexusOS, ~/.icons/Mint-Y-Nexus, ~/.config/gtk-3.0/gtk.css.
xfconf: xsettings (/Net/ThemeName, /Net/IconThemeName, /Gtk/CursorThemeName, /Gtk/FontName) and xfwm4 /general/theme.
~/.config/gtk-3.0/settings.ini and ~/.config/gtk-4.0/settings.ini.

Canonical values: theme NexusOS, icons NexusOS, cursor DMZ-White, font Ubuntu 10. Keep these in sync with NexusOS/index.theme and install-theme.sh.

Apply / reload after editing

xfconf-query -c xsettings -p /Net/ThemeName -s Adwaita
xfconf-query -c xsettings -p /Net/ThemeName -s NexusOS
xfdesktop --reload & xfce4-panel -r

Some apps cache the theme at startup and need a full restart.

Backup / restore

bin/backup.sh (run at home): snapshots live wiring into restore-snapshot/, then lftp-mirrors the repo to the router.
bin/restore.sh / bin/restore-full.sh: pull back, rebuild venv/frontend, then auto-run install-theme.sh.
The repo is git-tracked; backup.sh mirrors .git too, so if a bulk git add is ever interrupted run git gc --prune=now before backing up (a killed git add -A once left 4 GB of loose objects).

Gotchas (each cost real debugging time)

Theme silently falls back to Adwaita if gtk-theme-name in settings.ini and xfconf xsettings/Net/ThemeName disagree, or point at a non-existent theme. Edits then have zero visible effect.
settings.ini is machine-generated by xfsettingsd from xsettings.xml — don't symlink it into the repo. GTK4 has its own ~/.config/gtk-4.0/settings.ini that xsettings does not override; it must be reconciled separately (easy to forget).
@border == @overlay_bg (#2e3236) in colors.css, so a separator drawn in @border on an overlay surface is invisible. Use @border_strong / @menu_border. Root collision is unfixed; patched per-spot.
gtk-menu-images toggles icons in classic GtkMenus only. It does not affect the Whisker menu (separate widget tree).
Whisker menu: the popup's identifier is set via gtk_widget_set_name(), so CSS must target #whiskermenu-window (an #id), not .whiskermenu-window (a class) — a class selector matches nothing. The base window.background rule also outranks a bare class; #id wins on both counts. Whisker version: 2.9.x. Its app/category lists are treeview/iconview; restart xfce4-panel to reload its CSS.
Menu surfaces use @menu_bg (#2a1d33) / @menu_border (#4d3461) — dark purple. Tooltips/menubars/cards stay on the gray surface palette deliberately.
.gitignore does not support trailing/inline comments. A Dir/ # note line matches nothing — comments must be on their own line. (This once let a git add start ingesting the 28 GB venv.)

3.7 KiB Raw Blame History