--- id: NL-SPEC-83056D8D type: spec title: Nugu desktop theme switching --- # Nugu desktop theme switching ## Contract - Nugu is the sole palette source for generated desktop themes. - Valid modes are `dark` and `light`. - Missing or invalid persisted state resolves to `dark`. - Config is the daily appearance interface; existing CLI operations remain compatibility and test boundaries for selecting dark/light, toggling, read-only status, and preparation without explicit consumer reload. - Status reads effective mode without writes or reloads. - A successful mode change persists selected intent and reconciles the desktop preference and enabled consumer artifacts; mutations serialize, preflight installed inputs, and stage changed files before committing authority. - Cross-application publication is not atomic; post-selection failures report selected mode and failed steps without rolling back intent or falsely reporting synchronization. - Startup preparation reconciles preference and artifacts from authority without overwriting it; same-mode selection also retries explicit consumer reloads. - Nuguland and all other mode-aware consumers observe the same effective mode. - Config exposes observed desired mode, pending work, failed reconciliation steps, and retry of the selected mode; interrupted publication never claims rollback. - Config delegates appearance selection to the installed-artifact runtime without generating themes or creating another mode authority. ## Runtime state - Nuguland owns selection and preparation; the existing `$XDG_STATE_HOME/nugu/mode` file remains the sole persistent desired-mode authority, preserving valid existing state during migration. - Nugu is build/install source only; install both mode variants before runtime selection. - Runtime selection consumes installed artifacts and never imports Nugu generator modules, reads palette source, or regenerates themes. - GSettings is an output publisher for the XDG Settings portal compatibility target, never a mode authority; generic GNOME/KDE desktop compatibility is not promised. - WezTerm follows native appearance using installed palettes; indexed TUIs inherit terminal colors, while explicit-RGB exceptions remain named consumer integrations rather than a universal adapter. - Runtime artifacts contain palette-derived colors and styling only. - Layout, behavior, bindings, modules, and timeouts remain consumer-owned. - Runtime switching never edits tracked files or symlink targets inside the dotfiles repository. ## Safety - Switching between modes and back leaves repository status unchanged. - Live updates preserve unrelated application and session state. - Consumer restart is allowed only when no reliable live-update path exists. - Retired consumers do not constrain runtime artifacts. ## Acceptance - Missing and invalid state select `dark`. - Selection, toggle, preparation, and status have the specified effects. - Dark and light artifacts are deterministic and palette-derived. - Desktop preference consistently reflects the selected mode. - A complete light-to-dark round trip creates no dotfiles diff. - Enabled visual consumers are readable and consistent in both modes. - Final visual acceptance is human-confirmed. - Runtime selection/preparation succeeds with Nugu source unavailable and only installed artifacts present. - Tests cover preference-publication and authority-write failures, missing artifacts, repeated/concurrent selection, startup recovery, and unchanged repository status in isolated environments without a real desktop portal.