Panama/docs/superpowers/specs/2026-08-23-appearance-redesign.md

Appearance redesign — full themes, editor, video wallpapers, honest titlebars

Approved 2026-08-23 (consolidated interactive mock). Four workstreams; the theme system is the core. No test is executed until the whole settings redesign is done (see the test backlog spec); tests are written alongside.

1. The theme system

A theme is a complete palette plus an accent pair, bound to one scheme. Selecting a theme restyles the shell, kitty, GTK, the lock screen, Vicinae, Firefox's chrome, tmux, and btop. Ten ship; the editor makes more.

The catalog — one source of truth

config/dot/quickshell/config/themes.json holds the shipped themes. Unlike palette.json (which stays as-is for the curated accent pairs), the catalog is not duplicated into a JS table: a new services/ThemeCatalog.qml singleton reads it with FileView + JSON.parse (the ManualPage pattern), scripts read it with jq, and the Node halves of contracts read the JSON directly with fs. ThemeCatalog embeds a minimal Moon/Day fallback so the shell renders correctly for the instant before the file loads (and forever if it is missing).

A theme record:

{ "id": "mocha", "name": "Catppuccin Mocha", "scheme": "dark",
  "accent": "#cba6f7", "secondary": "#f5c2e7",
  "palette": { "bg": "…", "bgDark": "…", "bgHighlight": "…", "bgPanel": "…",
    "bgPopover": "…", "fg": "…", "fgDim": "…", "fgMuted": "…", "gutter": "…",
    "accentAlt": "…", "cyan": "…", "teal": "…", "green": "…", "yellow": "…",
    "orange": "…", "red": "…", "redDeep": "…", "magenta": "…", "pink": "…" },
  "ansi": { "black": "…", "red": "…", "green": "…", "yellow": "…", "blue": "…",
    "magenta": "…", "cyan": "…", "white": "…", "brightBlack": "…", "…": "…",
    "brightWhite": "…" } }

The nineteen palette keys are exactly Theme.qml's color tokens. ansi (16 keys) exists so terminal themes can be generated rather than hand-kept per theme.

Shipped lineup: Tokyo Moon (default dark — today's exact values), Moon Rose (Moon's palette, rose accent), Catppuccin Mocha, Nord, Gruvbox, Everforest; Tokyo Day (default light — today's values), Catppuccin Latte, Gruvbox Light, Everforest Light.

Records, selection, and scheme flips

ThemeProfileModel.js custom records extend to { id, name, scheme, accent, secondary, shipped, palette?, ansi?, effects? } — both whitelists (copyProfile, normalizeStoredProfile) learn the new optional fields, each palette/ansi value hex-validated, effects validated against the ten effect keys. A stored custom without palette inherits its scheme's default theme palette (moon/day), which also grandfathers every existing saved profile.

Selection becomes per-mode: new internal prefs themeDark (default "moon") and themeLight (default "day"). The Themes tab's light/dark hero writes colorScheme; ThemeProfiles resolves activeId = colorScheme == "light" ? themeLight : themeDark. reconcileScheme's force-reset to moon/day dies — a scheme flip now lands on your chosen theme for that scheme, custom or shipped. Picking a theme card writes its id into the mode's key (and flips colorScheme when the card belongs to the other mode).

accentName desync bug dies with it: every commit path (theme select, curated swatch, hex, wheel, eyedropper, HSV) ends in one function that also recomputes accentName as the nearest curated accent (for GNOME's enum) — libadwaita, kitty borders, and the lock screen stop trailing the truth.

Theme.qml

The 19 color ternaries and 7 alpha ternaries become lookups: palette(token) reads ThemeProfiles.activeProfile.palette?.[token] ?? ThemeCatalog default for the active scheme. Semantic aliases (ok/warn/danger/urgent), geometry, type, and motion tokens are untouched.

Reach — the render pipeline

panama-theme-apps generalizes: it resolves the active theme itself (settings.json → themeProfileId/themeDark/themeLight → catalog or stored customs, all via jq) and renders from the palette instead of copying per-scheme files:

target	today	becomes
kitty	copy tokyonight-{moon,day}.conf + append accent	render current-theme.conf from palette + ansi (template), live-apply via existing socket loop
hyprlock	scheme literals duplicated in 3 scripts	all eight placeholders filled from the palette (the triplication dies)
GTK settings.ini	template (scheme only)	unchanged
GTK gtk.css (3.0/4.0)	static, #82aaff baked in, "light" file secretly dark	marker-delimited @define-color block regenerated from palette; structural CSS untouched; light file actually light
libadwaita accent	gsettings enum	unchanged (nearest-curated mapping)
Vicinae	two hardcoded TOMLs	render panama-dark.toml / panama-light.toml from palette; vicinae.json points at them
Firefox	vendored Edge-Frfox palette, no Panama colors	render chrome/custom.css (the shipped override seam) mapping Edge-Frfox variables to the palette
tmux	copy tokyonight files	render current-theme.conf from palette
btop	sed the theme name	render a panama.theme from palette, point btop at it
nvim	reads colorScheme itself	unchanged this phase — stays tokyonight moon/day; a per-theme colorscheme map is future work

bin/panama-hook theme-set keeps firing (and moves out of the kitty if-condition it is accidentally inside, so it genuinely runs after all generators).

Effects belong to themes

The Effects card moves from the theme tab to the Theme editor. Saving a custom theme snapshots the ten effect values into the record; applying a theme that carries effects commits them; shipped themes carry none and leave yours alone.

The UI

AppearancePage tabs become Themes | Theme editor | Background | Typography | Windows | Shell (tab values themes, editor, plus existing).

Themes tab (the category's landing): the light/dark hero (two preview cards, writes colorScheme), a dark gallery and a light gallery of theme cards (shipped + customs for that scheme; custom cards get Delete), each card a mini palette preview; clicking applies live. A dashed "Build your own theme" card jumps to the editor tab.

Theme editor tab: start-from chips (any theme, or the active one), scheme segment, four color wells — Primary, Secondary, Background, Foreground — each with a hex field, a color wheel (Qt ColorDialog; if unavailable under Quickshell, a small in-shell HSV wheel popover), and the hyprpicker eyedropper. Background edits derive the surface tokens (bgDark/bgPanel/bgHighlight/bgPopover/gutter) by mixing; Foreground derives fgDim/fgMuted; a global Saturation slider re-saturates the derived palette. HSV fine-tune for the accent pair stays behind a disclosure (debounced now — today it commits two preferences per pixel of drag). Then the Effects card, then save-as / delete. Edits apply live immediately (the existing fork-to-custom model); there is no staged revert in this phase.

2. Typography

FontPicker is rebuilt as a closed dropdown: a button showing the current family in its own face, opening a popover with a search field and the filtered list (the current 12-match cap stays). All five rows use it — Interface, Icons, Application, Document, Monospace — with details naming what each controls. The always-open lists and the ActionRow disclosure pattern for fonts both retire. Sizes, hinting, antialiasing, Icons & pointer unchanged.

3. Titlebars — close-only, everywhere

• Schema: titlebarMaximizeButton and titlebarDoubleClick are deleted. GNOME's button-layout push becomes close-only, honoring titlebarButtonSide (close:appmenu / appmenu:close); the action-double-click-titlebar push is dropped (GNOME's default stands). A migration note: removed keys vanish from settings.json on next write; DesktopStyle simply stops reading them.
• New bool panamaTitlebar (group titlebar, default true): "Titlebar on Panama windows". Off = the Settings window renders no titlebar at all — pure Hyprland (Super+Q closes, Super+drag moves, Escape works); the sidebar and tab strip anchor to the window top.
• When on, the Settings titlebar obeys titlebarButtonSide, shows close only (the minimize button was a lie — Hyprland has no minimize), and its close button gains keyboard focus + Accessible metadata (the only unreachable control in the app today).

4. Video wallpapers

Engine: mpvpaper (Terra packages 1.9, which carries the libmpv fence-leak workaround; Fedora/RPM Fusion don't ship it). One process per output, hwdec=vaapi profile=fast no-audio loop-file=inf panscan=1.0 plus a per-output input-ipc-server socket under $XDG_RUNTIME_DIR. VAAPI verified on this machine: ~0.18 core for 1440p30 h264 vs ~0.70 software. Rejected: in-shell QtMultimedia — a continuously animating in-process surface drives repaints across every shell window (Quickshell's own documented failure mode), and a decoder crash would take the whole shell down instead of a wallpaper.

Mechanics, owned by a new services/VideoWallpaper.qml + scripts/panama-video-wallpaper:

• Videos come from videoWallpaperDir (default Videos/Wallpapers), scanned with the same newest-60 discipline (mp4/mkv/webm), rendered in the picker grid with a ▶ badge.
• Selecting a video stops hyprpaper.service for the session (both fight for the background layer; stacking is a race) and starts supervised mpvpaper; returning to a still kills mpvpaper and restarts hyprpaper. The processes are watched and respawned (mpvpaper has an open hotplug-segfault issue), and restarted nightly as leak insurance.
• Pause is Panama's job, not the compositor's. Research finding: Hyprland rebuilds the full-screen blur chain on every wallpaper frame while blur-enabled layers exist, and occluded wallpapers keep compositing except under solitary mode — which any overlay surface (a toast mid-game) breaks. So: pause via mpv JSON IPC (Quickshell.Io.Socket, no socat) on (a) the existing panama-gaming start/end hooks, (b) solitary polling from hyprctl -j monitors on socket2 events, (c) session lock and idle, (d) battery when videoWallpaperPauseOnBattery (default on), and (e) the bar pill — a Pill visible while a video wallpaper is active, click to pause/resume (remote desktop, or just quiet). mpvpaper's -p -a FULL auto-pause rides along as belt-and-braces only.
• Lock screen: panama-lock uses a cached still frame (one-time ffmpeg frame grab on selection) when the wallpaper is a video.
• A panama-doctor check verifies VAAPI actually engaged (the known silent software-decode failure reads as "mpvpaper is heavy").
• Packages: mpvpaper, mpv added to setup/packages/hyprland-packages.
• Schema: videoWallpaperDir (string), videoWallpaperPauseOnBattery (bool, default true); the active video path rides wallpaperPath (the picker treats stills and videos uniformly; Wallpaper.qml routes by extension).
• The 120fps HEVC Canyons file gets flagged in UI copy (interval/fps advice), not special-cased.

5. Blast radius (themes workstream)

Contracts rewritten alongside (not run): theme-profiles-contract (new record fields), accent-controls-contract (editor rebuild), palette-contract (unchanged accents, plus themes.json shape checks), adwaita-accent-contract (nearest-curated mapping), gtk-theme-contract (generated css block), lock-screen-theme-contract (palette-fed placeholders), desktop-style-contract (titlebar keys removed), settings-hardcoded-values-contract, wallpaper-* (video), plus new theme-catalog-contract (themes.json shape: 10 themes, 19 palette keys, 16 ansi keys, valid hexes, unique ids, moon/day byte-matching Theme.qml's former literals). Generators: settings docs/commands unaffected (no new pages); SettingsSearch entries updated (Themes, Theme editor, video wallpaper terms; titlebar entries pruned). docs/settings.md, settings README, manual chapter updates ride along.

Non-goals this phase

nvim per-theme colorschemes; ohmyposh/wofi theming; staged preview-and-revert in the editor; per-token palette overrides beyond the four wells + saturation; theme import/export.