mesh-catalog/modules/adwaita/README.md

adwaita

The desktop's theme as a module (novox/hq ADR 0208, research 026, to-be 42 phase 2, step 6): Adwaita for GTK, Qt, the portal and the cursor, dark by default. It claims no seat, because themes coexist.

• Packages: gnome-themes-extra (Adwaita-dark for GTK 2 and 3), adwaita-icon-theme, adwaita-cursors, qt6ct, xdg-desktop-portal-gtk.
• Environment (ADR 0203), the five words today's ~/.xinitrc exported plus the cursor:
  • GTK_THEME=Adwaita:dark;
  • GTK2_RC_FILES=/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc;
  • QT_QPA_PLATFORMTHEME=qt6ct;
  • QT_STYLE_OVERRIDE=Fusion;
  • QT_SELECT=6;
  • XCURSOR_THEME=Adwaita, XCURSOR_SIZE=24.
• Session code (ADR 0208 §4):
  • in the xinitrc slot normal, the GSettings keys the portal serves (dark, the GTK and icon theme, the cursor, the UI and monospace fonts), set at every session start. This replaces the predecessor's ~/scripts/xdg-appearance;
  • in the xresources slot normal, Xcursor.theme and Xcursor.size.

What it owns

path	class	from
~/.config/gtk-3.0/settings.ini	owned (the found file kept once)	config/gtk-settings.ini
~/.config/gtk-4.0/settings.ini	owned	the same file
~/.config/qt6ct/qt6ct.conf	owned	config/qt6ct.conf
~/.config/xdg-desktop-portal/portals.conf	owned	config/portals.conf
~/.icons/default/index.theme	owned	config/cursor-index.theme: the cursor for programs that read neither XCURSOR_THEME nor the resources

qt6ct.conf is the mesh's now. A change made in qt6ct's own window is replaced at the next push, and the window's saved geometry goes with it. The theme is this module's to say. Settings will make it the operator's (issue 168).

What it improves

• No package from the user repository. Today's Qt style, adwaita-dark (QT_STYLE_OVERRIDE and qt6ct's Adwaita-Dark), comes from the user repository's adwaita-qt5/adwaita-qt6-git, a project that is no longer developed. The module uses Qt's own Fusion style with qt6ct's darker palette, both shipped with Qt and qt6ct. This is the one visible change: Qt programs keep a dark palette, drawn by Fusion instead of Adwaita-Qt.
• One Qt tool. qt5ct is gone (installed on the desktop only, with a configuration on both). QT_SELECT=6 and qt6ct cover the Qt 6 programs. A Qt 5 program gets Fusion through QT_STYLE_OVERRIDE, but not the palette.
• The fonts research 026/04 chose: Inter 11 for GTK, Qt and GSettings' interface font, and JetBrains Mono Nerd Font for Qt's fixed font and GSettings' monospace. Today these are Noto Sans 12, Adwaita Sans 11 and nothing.
• The cursor said everywhere: GTK's settings, GSettings, XCURSOR_*, the X resources and the default theme. Today only the resources and GSettings said it.
• The portal answers secrets. portals.conf routes org.freedesktop.impl.portal.Secret to gnome-keyring. Today adwaita_portal_check shows no backend answering it: gtk does not implement it, and gnome-keyring's backend names only GNOME.

Tools

tool		what
adwaita_appearance	r/a	dark or light as each audience sees it (GSettings, the portal's own answer, the GTK files, Qt's style and palette, the theme words in the user manager). mode switches GSettings for the session, and the answer says what follows live (programs asking the portal) and what stays dark (GTK 3 under GTK_THEME, the declared files)
adwaita_cursor	r/a	the cursor in GSettings, the resources and the environment, and the cursor themes installed; set theme or size for new windows (GSettings, and the resources when a session runs)
adwaita_icons	r	icon themes installed (where, what each inherits, whether it has cursors), and the one GSettings, GTK and Qt use
adwaita_portal_check	r	the backends installed and what each implements, which portals.conf decides (the first that exists, in xdg-desktop-portal's order), the backend answering each interface, what runs on the bus, and the colour scheme the portal answers

Each reaches GSettings, the portal and the user manager on the account's bus. Only the cursor's X resources need the session. From the user manager it reads only the theme's own words.

The appearance is a session's choice. A persistent dark or light, for the files too, is a setting and waits for issue 168. Until then the module's default is dark, and mode lasts until the next login.

What it leaves found

~/.config/qt5ct/, ~/.config/gtk-3.0/bookmarks and everything else in those directories, ~/scripts/xdg-appearance, and the user repository's adwaita-qt* packages.

The one-off migration (ADR 0182)

Once adwaita is assigned:

1. In ~/.xinitrc, the theme exports and ~/scripts/xdg-appearance || true go (see xorg's list).
2. Delete ~/scripts/xdg-appearance.
3. In ~/.Xresources, delete the two Xcursor lines.
4. Delete ~/.config/qt5ct/.
5. Remove the user repository's packages: sudo pacman -Rns adwaita-qt5-git adwaita-qt6-git (laptop), sudo pacman -Rns adwaita-qt5 adwaita-qt6-git adwaita-dark qt5ct (desktop). Check first that nothing else needs them (pacman -Qi).

What changes when it is assigned

	g14	shanks
packages	none (all present)	the same
GTK settings, portals.conf	the found files kept once, then the module's: adds the cursor and Inter, keeps Adwaita dark; portals.conf adds the Secret line	the same
qt6ct.conf	Fusion with the darker palette, Inter and JetBrains Mono, instead of Adwaita-Dark with Noto Sans	the same
~/.icons/default/index.theme	new	new
environment	QT_STYLE_OVERRIDE becomes Fusion; XCURSOR_* added; the rest as ~/.xinitrc exported them	the same
running programs	nothing: settings are read at a program's start, and GSettings is set at the next login	the same
next login	GSettings' fonts become Inter and JetBrains Mono. A secret request through the portal finds gnome-keyring	the same

Blockers

• fonts first, for Inter and JetBrains Mono. Without them, GTK and Qt fall back to the nearest installed face.
• Light is a session's choice only, until settings (issue 168).