Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

quickshell/nuguland/.system/specs/NL-SPEC-83056D8D-nugu-desktop-theme-switching/index.md

Raw
Rendered preview

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