NexusOS/assets/themes/README.md

# NexusOS desktop theme

XFCE/GTK desktop theme (distinct from the web UI in `interface/web/`).
Lime-green + purple, dark, with tightened menus.

## Layout

| Path | What |
|---|---|
| `NexusOS/` | GTK2/3 + xfwm4 theme. **GTK3 CSS in `NexusOS/gtk-3.0/` is hand-maintained** (no build step). |
| `NexusOS/gtk-3.0/colors.css` | All color tokens. Edit colors here, not in the widget files. |
| `NexusOS-icons/` | Icon theme (inherits `Papirus-Dark`). |
| `_palette.py` + `*-src/build.py` | Regenerate gtk2 / icons / xfwm4 — **NOT gtk-3.0**. |
| `NexusOS-icons-src/build_actions.py` | Regenerate the `actions` icons (logoff dialog / Whisker session buttons). |
| `install-theme.sh` | Idempotent restore of all the *wiring* (see below). |
| `gtk3-user-overrides.css` | Symlinked to `~/.config/gtk-3.0/gtk.css`. |

## How it's wired (the part backups miss)

The files above are just *source*. What makes the desktop use them lives
outside this folder and is recreated by `install-theme.sh`:

- Symlinks: `~/.themes/NexusOS`, `~/.icons/NexusOS`,
  `~/.config/gtk-3.0/gtk.css`.
- xfconf: `xsettings` (`/Net/ThemeName`, `/Net/IconThemeName`,
  `/Gtk/CursorThemeName`, `/Gtk/FontName`) and `xfwm4 /general/theme`.
- `~/.config/gtk-3.0/settings.ini` **and** `~/.config/gtk-4.0/settings.ini`.

Canonical values: theme `NexusOS`, icons `NexusOS`, cursor `DMZ-White`,
font `Ubuntu 10`. Keep these in sync with `NexusOS/index.theme` and
`install-theme.sh`.

## Apply / reload after editing

```bash
xfconf-query -c xsettings -p /Net/ThemeName -s Adwaita
xfconf-query -c xsettings -p /Net/ThemeName -s NexusOS
xfdesktop --reload & xfce4-panel -r
```

Some apps cache the theme at startup and need a full restart.

## Backup / restore

- `ncp backup -f` (`python bin/sync.py backup --full`): `bin/backup-linux.sh`
  snapshots live wiring into `restore-snapshot/`, then the tree is committed
  and pushed to Gitea.
- `ncp restore` (`python bin/sync.py restore`): pull, rebuild venv/frontend,
  then `bin/restore-linux.sh desktop` auto-runs `install-theme.sh`. Add
  `--check` for a dry run.
- Both stages are Linux-only and skipped on Windows; `bin/sync.py` is the
  entry point on both machines.

## Gotchas (each cost real debugging time)

1. **Theme silently falls back to Adwaita** if `gtk-theme-name` in
   `settings.ini` and xfconf `xsettings/Net/ThemeName` disagree, or
   point at a non-existent theme. Edits then have zero visible effect.
2. **`settings.ini` is machine-generated** by xfsettingsd from
   `xsettings.xml` — don't symlink it into the repo. **GTK4 has its own
   `~/.config/gtk-4.0/settings.ini`** that xsettings does *not* override;
   it must be reconciled separately (easy to forget).
3. **`@border` == `@overlay_bg` (`#2e3236`)** in `colors.css`, so a
   separator drawn in `@border` on an overlay surface is invisible. Use
   `@border_strong` / `@menu_border`. Root collision is unfixed; patched
   per-spot.
4. **`gtk-menu-images`** toggles icons in classic GtkMenus only. It does
   **not** affect the Whisker menu (separate widget tree).
5. **Whisker menu**: the popup's identifier is set via
   `gtk_widget_set_name()`, so CSS must target **`#whiskermenu-window`
   (an #id), not `.whiskermenu-window` (a class)** — a class selector
   matches nothing. The base `window.background` rule also outranks a
   bare class; `#id` wins on both counts. Whisker version: 2.9.x.
   Its app/category lists are `treeview`/`iconview`; restart
   `xfce4-panel` to reload its CSS.
6. **Menu surfaces** use `@menu_bg` (`#2a1d33`) / `@menu_border`
   (`#4d3461`) — dark purple. Tooltips/menubars/cards stay on the gray
   surface palette deliberately.
7. **`.gitignore` does not support trailing/inline comments.** A
   `Dir/ # note` line matches nothing — comments must be on their own
   line. (This once let a `git add` start ingesting the 28 GB venv.)

---

## KDE Plasma migration (`KDE/`)

All KDE Plasma theme assets live under `KDE/`. These are built to mirror the NexusOS
visual design — same palette, same flat aesthetic — in KDE-native formats. The GTK 3
theme and icon theme carry over unchanged.

```
KDE/
  install-plasma.sh           # idempotent installer (run once after switching)
  generate_plasma_colors.py   # regenerate NexusOS.colors from _palette.py

  plasma/NexusOS/             # Plasma shell theme (panel, widgets, tooltips)
    NexusOS.colors            # KDE color scheme — source of truth for Qt/KDE colors
    colors                    # Plasma shell palette overrides
    widgets/*.svg             # 9-slice SVGs: panel-background, tooltip, button, etc.
    opaque/widgets/           # compositor-off variants

  kvantum/NexusOS/            # Qt5/Qt6 app styling
    NexusOS.kvconfig          # widget geometry + element references
    NexusOS.svg               # flat SVG widget drawings

  aurorae/NexusOS/            # KWin window decoration
    NexusOSrc                 # titlebar height, button layout, colors
    decoration.svg            # window frame (9-slice)
    close/maximize/minimize/restore/alldesktops/keepabove/keepbelow/shade.svg

  sddm/NexusOS-QML/           # Login screen (already deployed; palette now aligned)
    Main.qml                  # QML login UI — NexusOS purple/green palette
    assets/background.svg  assets/logo.png

  look-and-feel/com.nexusos.desktop/   # Global Theme: selects every component
    contents/defaults                  # what System Settings applies in one click
    contents/splash/Splash.qml         # startup splash, matches Plymouth/SDDM

  wallpaper/NexusOS/          # desktop + lock wallpaper (brushed metal)

  konsole/
    NexusOS.colorscheme            # general terminal colors
    NexusOS-Promethean.colorscheme # deep purple — matches promethean-kitty.conf
    Promethean.profile             # Konsole profile: rcfile, cursor, color scheme
```

### What survives the switch unchanged

| Asset | Status |
|---|---|
| `NexusOS/gtk-3.0/` (all CSS) | GTK apps on Plasma use it as-is |
| `NexusOS-icons/` | Freedesktop spec — works on any DE |
| `_palette.py` / `colors.css` | Source of truth; KDE palette generated from it |
| Plymouth boot splash | System-level; unaffected by DE switch |

### Installing before the switch (XFCE)

**Testable now:**
```bash
# Kvantum (Qt5 app styling — works on XFCE)
sudo apt install qt5-style-kvantum qt5-style-kvantum-themes
ln -sfn "$PWD/assets/themes/KDE/kvantum/NexusOS" ~/.config/Kvantum/NexusOS
kvantummanager --set NexusOS     # then open any Qt5 app

# Konsole colors (works on XFCE if konsole installed)
cp assets/themes/KDE/konsole/*.colorscheme assets/themes/KDE/konsole/Promethean.profile \
   ~/.local/share/konsole/

# SDDM palette (already live; installer will redeploy if needed)
```

**Needs KDE session:** Aurorae decoration, Plasma shell theme, Global Theme.

The lock screen is Breeze's, with the NexusOS wallpaper set on it. Plasma 5.27
draws the lock screen from a look-and-feel package's `contents/lockscreen`, and
replacing that QML risks a lock screen you cannot get back through, so only the
background is ours.

### First boot into Plasma

```bash
assets/themes/KDE/install-plasma.sh
```

Then in System Settings → Appearance verify:
- Global Theme: (manual if needed — set individual components below)
- Colors: NexusOS
- Application Style: Kvantum-dark
- Plasma Style: NexusOS
- Window Decorations: NexusOS
- Icons: NexusOS

Test lock screen: **Meta+L**

### Promethean Terminal on KDE

`bin/promethean/promethean-terminal.desktop` now uses `konsole --profile Promethean`.
The Promethean Konsole profile configures the rcfile, deep-purple color scheme,
and `#b040c0` cursor. The kitty fallback line is commented out in the `.desktop`.

### Palette alignment note

The SDDM `NexusOS-QML` theme previously used a navy/cyan palette (`#0f1626` / `#00d4ff`).
It has been updated to the NexusOS palette (`#1e1526` / `#8cc63f`) for consistency.
The live SDDM at `/usr/share/sddm/themes/NexusOS-QML/` still has the old colors;
`install-plasma.sh` will replace it.