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

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

• bin/backup.sh (run at home): snapshots live wiring into restore-snapshot/, then rsyncs the repo to the router.
• bin/restore.sh: pull back, rebuild venv/frontend, then auto-run install-theme.sh. Use bin/restore.sh --checksum for a content-only dry-run.
• The repo is git-tracked; backup.sh mirrors .git too, so if a bulk git add is ever interrupted run git gc --prune=now before backing up (a killed git add -A once left 4 GB of loose objects).

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

  kscreenlocker/NexusOS/      # Runtime screen lock (Meta+L in KDE)
    contents/ui/LockScreenUi.qml   # matches SDDM aesthetic; kscreenlocker API

  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:

# 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, kscreenlocker.

First boot into Plasma

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.