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.
---
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.