Skip to main content

ADR 0013: Theme as the thirteenth public kind

Status: accepted (2026-10-09)

Context​

A workstation's look is a named thing: desktops ship a colors.toml palette (mode, accent, background and terminal colors) with wallpapers, applied by naming the theme. GnomeProfile sets the appearance one workstation at a time, but there is no reusable, named palette. GNOME exposes color-scheme, accent-color, gtk-theme, icon-theme, cursor-theme and fonts in org.gnome.desktop.interface, the wallpaper in org.gnome.desktop.background, and the Shell accent from GNOME 47.

Decision​

Add desktop.deskos.org/v1alpha1 Theme:

FieldValue
modedark or light, lowered to color-scheme
accentany #RRGGBB, mapped to the closest GNOME accent by hue
iconTheme, cursorThemetheme names, lowered as-is
fontsthe same font shape as GnomeProfile.appearance.fonts
wallpaperlight/dark assets, like GnomeProfile.appearance.wallpaper

A Theme shares the GNOME setting domain of GnomeProfile, so layering, locking and conflicts work unchanged: a Theme and a GnomeProfile setting appearance.accentColor at one layer conflict. A Theme sets at least one field, enforced by schema and typed decoder; a free accent maps to the closest of nine by hue, with a slate fallback for near-achromatic colors.

Slice 2: the palette and the applier (implemented)​

palette makes a Theme generate the look's overrides: background and foreground produce a GTK4/libadwaita override limited to the window and view surfaces, and the six normal ANSI colors (red…cyan, plus optional black/white) produce a Ptyxis palette (dconf drop in distro.d/60-deskos-ptyxis) and a Ghostty theme, as a GeneratedFile IR leaf.

The compiler installs the files into /etc/skel/… and /etc/dconf/db/distro.d/…; the dconf defaults reach every user who has not pinned the key, the /etc/skel files only accounts created after the image.

deskos-theme is the runtime counterpart: apply --palette <dir> validates every color as #RRGGBB and writes the same files (--user to $HOME, --system under a root), failing with a clear message if a setting could not be applied. reset-gnome-defaults returns the GNOME keys DeskOS manages to the image default; icons, cursors and fonts are not applied.

Optional adapters​

  • GNOME Shell (--shell-css): replaces Adwaita base hexes in the distro's stylesheet and writes two packs (deskos-a/deskos-b) so the Shell reloads by switching. A hex replacement does not preserve meaning and can fail silently when upstream CSS changes.
  • GTK3 (gtk-3.0/gtk.css): generated by default, in the image and in apply, but experimental. @define-color from a user provider does not reliably reach the active theme's resolved rules, and an adw-gtk3 dependency must be declared and enabled.

Consequences​

  • The public API has fifteen kinds today (thirteen when this decision was taken); a test enforces the count, and the remaining work is the manual, visual check of GTK4 and Ptyxis in a session.
  • Visual parity with another desktop is not promised: GNOME has deliberate limits, and apps read the accent by API, not CSS. A colors.toml palette is the reference shape.
  • shell.welcomeTour: false writes welcome-dialog-last-shown-version, a value gnome-shell owns.