---
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`.
- Public operations select either mode, toggle, report current status, or prepare runtime artifacts without reload.
- Status reads effective mode without writes or reloads.
- A mode change updates the desktop color-scheme preference and every enabled consumer supporting that mode.
- Nuguland and all other mode-aware consumers observe the same effective mode.

## Runtime state

- Runtime state belongs under the Nugu directory in XDG state home.
- 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.