From 8bea372b983327a6241c0456efa0aa70aa455c89 Mon Sep 17 00:00:00 2001 From: Andrew Zambazos Date: Sat, 23 May 2026 17:28:19 +1200 Subject: [PATCH] Expand Desktop README and update root link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the old concise Desktop README with a much-expanded Desktop/README-Desktop.md that consolidates and extends Desktop Mode documentation. The new file adds Design Vision, Windows/macOS/KDE influences, Nebula identity, current development status, milestones (prototype → theming → apps → packaging), recommended workflow (symlinks, apply/reload scripts), suggested layout and visual identity, and useful test commands. Deleted the old Desktop/README.md and updated the top-level README.md to point to Desktop/README-Desktop.md. Purpose: provide a clearer, actionable guide for Desktop Mode development and to separate Desktop Mode docs from Bigscreen Mode. --- Desktop/README-Desktop.md | 547 ++++++++++++++++++++++++++++++-------- Desktop/README.md | 28 -- README.md | 2 +- 3 files changed, 438 insertions(+), 139 deletions(-) delete mode 100644 Desktop/README.md diff --git a/Desktop/README-Desktop.md b/Desktop/README-Desktop.md index aa6492e..1715a38 100644 --- a/Desktop/README-Desktop.md +++ b/Desktop/README-Desktop.md @@ -1,20 +1,18 @@ # NebulaOS Desktop Mode -Desktop Mode is the full Linux desktop experience for NebulaOS. +NebulaOS Desktop Mode is the mouse-and-keyboard desktop layer for NebulaOS. It provides the full Linux desktop experience for users who need file management, development tools, modding workflows, browser access, productivity apps, system settings, and advanced troubleshooting. -It exists because NebulaOS should not only be a console-style interface. -It should also be a capable desktop operating system when the user needs one. +Desktop Mode is built on KDE Plasma as its starting foundation. KDE gives NebulaOS a mature, flexible, themeable, and gaming-friendly Linux desktop while the Nebula-specific shell identity, desktop apps, launcher ideas, and visual language continue to develop. -Bigscreen Mode is for controller-first gaming and media. -Desktop Mode is for everything else. +This README only covers **Desktop Mode**. It does not cover the full NebulaOS project or Bigscreen Mode. Those have their own separate README files. --- ## Purpose -Desktop Mode gives users access to a normal computer environment. +Desktop Mode exists because NebulaOS should not only be a controller-first or console-style interface. It should also be a capable desktop operating system when the user needs one. -It is designed for: +Desktop Mode is designed for: * File management * Web browsing @@ -26,10 +24,115 @@ It is designed for: * Desktop gaming * App management * System maintenance +* Mouse and keyboard workflows -NebulaOS should feel simple in Bigscreen Mode, but never locked down. +NebulaOS should feel simple in Bigscreen Mode, but never locked down. Desktop Mode is what keeps NebulaOS flexible, useful, and powerful. -Desktop Mode is what keeps NebulaOS flexible. +--- + +## Design Vision + +NebulaOS Desktop Mode should feel like a sleek modern OS UI that combines the strongest parts of Windows, macOS, and Linux while still becoming its own distinct interface. + +The goal is not to copy any one operating system. The goal is to borrow the best ideas and reinterpret them through the NebulaOS identity. + +### Windows Influence + +Desktop Mode should take inspiration from Windows for: + +* Familiar taskbar-style productivity +* Clear window management +* App launching habits users already understand +* System tray concepts +* Right-click and power-user workflows +* Desktop gaming familiarity + +### macOS Influence + +Desktop Mode should take inspiration from macOS for: + +* Visual polish +* Calm spacing +* Soft blur and translucency +* Clean typography +* Smooth animation +* Premium-feeling system surfaces +* Control Centre-style quick settings + +### Linux / KDE Influence + +Desktop Mode should take inspiration from Linux and KDE for: + +* Customization +* Openness +* User control +* Themeability +* Widgets +* Scripting +* Session flexibility +* Power-user tooling + +### NebulaOS Identity + +NebulaOS Desktop Mode should add its own identity through: + +* Deep blue and purple tones +* Glass-like dark surfaces +* Soft glow +* Rounded panels +* Space-inspired wallpapers +* Clean icon language +* Gaming-aware shortcuts +* Bigscreen access from the desktop +* Nebula Browser and Nebula Library integration + +--- + +## Current Development Status + +Desktop Mode is currently in the early KDE customization stage. + +### Working / Set Up + +* [x] KDE Plasma selected as the Desktop Mode foundation +* [x] Desktop Mode repo structure created +* [x] Starter KDE theme files copied into the repo +* [x] Theme files are being edited directly from the repo +* [x] Symlink-based development workflow started +* [x] Apply script created or started +* [x] Plasma reload workflow started +* [x] Desktop Mode separated from Bigscreen Mode conceptually +* [x] Current focus is KDE theme and shell identity + +### Being Worked On + +* [ ] NebulaOS Plasma theme +* [ ] NebulaOS color scheme +* [ ] NebulaOS look-and-feel package +* [ ] NebulaOS wallpaper set +* [ ] Floating/glass panel styling +* [ ] Launcher/menu styling +* [ ] Popup/dialog styling +* [ ] Notification styling +* [ ] Task manager active indicators +* [ ] System tray styling +* [ ] Bigscreen Mode desktop shortcut +* [ ] Nebula Browser desktop shortcut +* [ ] Cleaner apply and reload scripts + +### Not the Focus Yet + +The following are planned, but should not be the main focus until the base Desktop Mode theme feels solid: + +* Full custom login system +* Full SDDM theme +* Full Nebula Control Center +* Nebula Store +* Nebula Library desktop app +* Nebula Mod Manager +* Deep KDE source patches +* Full ISO packaging +* First-run setup / OOBE --- @@ -42,8 +145,11 @@ The recommended Desktop Mode foundation is: * SDDM * Wayland where possible * X11 fallback where needed -* Custom Nebula theme -* Custom Nebula session entries +* Custom Nebula Plasma theme +* Custom Nebula color scheme +* Custom Nebula look-and-feel package +* Custom Nebula wallpaper set +* Custom Nebula session entries later KDE Plasma is recommended because it is: @@ -53,26 +159,23 @@ KDE Plasma is recommended because it is: * Mature * Flexible * Suitable for both desktop and handheld layouts +* Easier to prototype with than writing a whole desktop shell from scratch --- -## Design Direction +## Repository & Development -Desktop Mode should feel: +This repository is the source of truth for Desktop Mode. -* Clean -* Smooth -* Modern -* Minimal -* Polished -* Fast -* Familiar -* Slightly futuristic +Local KDE folders under `~/.local/share` are runtime and test targets only. During development, symlinks can point KDE at the files in this repo. For packaging and install testing, the apply script should copy the same repo files into KDE's local package locations. -The design should take inspiration from the clarity and polish of macOS while keeping the flexibility and openness of Linux. +This means: -NebulaOS Desktop Mode should not look like a generic KDE install forever. -The long-term goal is to make it feel like a distinct Nebula desktop experience. +* Edit files in the repo +* Test through symlinks where possible +* Use scripts to apply or reload changes +* Avoid manually editing copied files in KDE's local folders +* Keep all Desktop Mode work version-controlled --- @@ -90,59 +193,10 @@ Desktop Mode should provide: * Desktop game launching * Access to Bigscreen Mode * Advanced troubleshooting tools +* App management +* System maintenance ---- - -## Relationship to Bigscreen Mode - -NebulaOS has two main sessions: - -```text -Nebula Bigscreen -Nebula Desktop -``` - -### Bigscreen Mode - -Used for: - -* Controller navigation -* Game launching -* TV use -* Handheld use -* Couch workflows -* Simple settings -* Console-like experience - -### Desktop Mode - -Used for: - -* Mouse and keyboard use -* Advanced configuration -* Development -* File browsing -* Modding -* Productivity -* Troubleshooting - -Both modes should feel connected, but they should not try to do the same job. - ---- - -## Session Switching - -Long-term, NebulaOS should allow users to switch between modes easily. - -Possible flows: - -```text -Bigscreen Mode → Power Menu → Switch to Desktop Mode -Desktop Mode → App Launcher → Return to Bigscreen Mode -Login Screen → Choose Nebula Bigscreen or Nebula Desktop -``` - -The user should never feel trapped in either mode. +Desktop Mode should feel like a proper computer desktop, not just a fallback mode. --- @@ -151,52 +205,86 @@ The user should never feel trapped in either mode. Desktop Mode customization may include: * Nebula global theme +* Nebula Plasma theme +* Nebula color scheme * Nebula icon theme * Nebula cursor theme * Nebula wallpaper set -* Custom SDDM theme -* Custom splash screen +* Custom SDDM theme later +* Custom splash screen later * Custom panel layout -* Custom application launcher +* Custom application launcher direction * Custom desktop widgets -* Preinstalled Nebula apps +* Preinstalled Nebula apps later * Desktop shortcut for Bigscreen Mode +* Desktop shortcut for Nebula Browser +* Desktop shortcut for Nebula Library later + +Starter KDE Plasma customization currently happens through: + +* Plasma desktop themes for shell surfaces such as panels, widgets, popups, dialogs, and SVG assets +* Look-and-feel packages for grouping the desktop experience under a Nebula identity +* Color schemes for the Nebula Dark palette +* Wallpapers and branding assets +* Plasmoids for prototype Nebula desktop widgets such as the launcher +* Later, KWin scripts and deeper KDE source patches after the prototype layer works + +This layer should stay small and safe for now. Avoid deep KDE source changes until the Plasma theme, color scheme, look-and-feel package, and launcher prototype are easy to test and iterate. --- ## Suggested Desktop Layout -A possible default layout: +A possible default Desktop Mode layout: ```text -Top panel -├── App launcher -├── Active window title +Floating bottom panel +├── Nebula launcher +├── Search +├── Pinned apps +├── Open apps +├── Bigscreen shortcut ├── System tray ├── Network ├── Audio ├── Battery -└── Clock +├── Clock +└── Quick settings Desktop ├── Nebula wallpaper ├── Minimal icons └── Optional widgets -Dock or bottom panel -├── Browser +Launcher +├── Search +├── Pinned apps +├── Recent apps +├── Games ├── Files -├── Terminal ├── Settings -├── Nebula Bigscreen -└── Nebula Library +├── Power +└── Switch to Bigscreen Mode ``` +The default desktop should feel like a mix of a Windows taskbar, macOS Dock polish, and KDE flexibility. + +Suggested panel style: + +* Floating rounded panel +* Dark translucent glass surface +* Subtle border +* Soft shadow +* Centered app icons +* Small glow under active apps +* System tray grouped cleanly on the right +* Nebula launcher button on the left + --- ## Visual Identity -Desktop Mode should share visual DNA with Bigscreen Mode. +Desktop Mode should share visual DNA with the wider NebulaOS project while remaining calmer and more practical than a controller-first interface. Shared elements may include: @@ -210,36 +298,248 @@ Shared elements may include: * Calm animation * Consistent icon language -Desktop Mode should be calmer and more practical than Bigscreen Mode, but still recognizably Nebula. +### Visual Keywords + +```text +Glass +Depth +Glow +Blur +Soft shadows +Rounded panels +Dark translucent surfaces +Blue/purple nebula gradients +Clean typography +Minimal clutter +Gaming polish +Desktop productivity +``` --- -## System Tools +## Plasma vs Native Desktop Apps -Desktop Mode may eventually include Nebula-specific tools such as: +Desktop Mode should not try to force everything into KDE theme files. Some parts should remain KDE/Plasma, while larger Nebula tools should become separate native apps. + +### KDE Plasma should handle: + +* Desktop shell +* Panels +* Widgets +* Notifications +* System tray +* Window management +* Theme integration +* Shortcuts +* Power menu +* Basic desktop settings + +### Native Nebula apps should handle later: + +* Nebula Welcome +* Nebula Control Center +* Nebula Settings +* Nebula Library +* Nebula Mod Manager +* Nebula Store +* Nebula Update Manager +* Nebula account/profile manager +* Nebula diagnostics + +These apps should likely be native Qt apps where deep desktop integration is useful. + +--- + +# Milestones + +## Milestone 0: KDE Prototype Setup + +Status: Mostly complete + +Goal: Get KDE ready for safe Desktop Mode theme development. + +Tasks: + +* [x] Choose KDE Plasma as the Desktop Mode foundation +* [x] Set up the repo structure +* [x] Copy starter KDE theme files into the repo +* [x] Set up symlinks for development +* [x] Begin editing the Plasma theme +* [x] Add or start apply script +* [x] Add or start reload workflow +* [ ] Confirm theme metadata is clean +* [ ] Confirm theme appears correctly in KDE settings +* [ ] Document the development workflow + +Definition of done: + +* KDE can load the NebulaOS theme from the repo or from copied local files +* The theme can be refreshed without reinstalling the OS +* The repo is the source of truth + +--- + +## Milestone 1: NebulaOS Desktop Theme v0.1 + +Status: Current priority + +Goal: Make the desktop visually stop looking like stock KDE. + +Tasks: + +* [ ] Create NebulaOS wallpaper +* [ ] Create NebulaOS color scheme +* [ ] Rename and clean theme metadata +* [ ] Style the main Plasma panel +* [ ] Style launcher/menu surfaces +* [ ] Style popups and dialogs +* [ ] Style tooltips +* [ ] Style notifications +* [ ] Style task manager active indicators +* [ ] Add Nebula launcher icon +* [ ] Add Bigscreen Mode shortcut +* [ ] Add Nebula Browser shortcut +* [ ] Improve apply script +* [ ] Improve reload script +* [ ] Add screenshots to this README later + +Definition of done: + +* Wallpaper applies correctly +* Color scheme applies correctly +* Panel looks like NebulaOS +* Menus and popups match the theme +* Notifications match the theme +* Bigscreen Mode can be launched from Desktop Mode +* The desktop has a clear NebulaOS identity + +--- + +## Milestone 2: NebulaOS Desktop Shell v0.2 + +Status: Planned + +Goal: Improve the default layout and desktop workflow. + +Tasks: + +* [ ] Create default panel layout +* [ ] Add pinned app defaults +* [ ] Add clean system tray layout +* [ ] Add search-focused workflow +* [ ] Add power/user shortcuts +* [ ] Add better desktop widgets if needed +* [ ] Add default shortcuts for browser, files, terminal, settings, and Bigscreen Mode +* [ ] Improve launcher direction + +Definition of done: + +* A fresh Desktop Mode session has a clear default layout +* Users can launch core apps easily +* Users can switch to Bigscreen Mode easily +* The desktop feels intentionally designed instead of manually assembled + +--- + +## Milestone 3: NebulaOS Desktop Apps v0.3 + +Status: Planned + +Goal: Add the first native Nebula desktop tools. + +Recommended first app: + +```text +Nebula Welcome +``` + +Nebula Welcome should allow users to: + +* Learn what Desktop Mode is +* Open KDE/System Settings +* Launch Bigscreen Mode +* Launch Nebula Browser +* Open project/about information +* Access basic setup links + +Future desktop apps may include: * Nebula Control Center +* Nebula Library +* Nebula Mod Manager * Nebula Update Manager -* Nebula Library desktop app -* Nebula Browser * Nebula Store -* Nebula Settings bridge -* Nebula account/profile manager -* Nebula system diagnostics + +Definition of done: + +* At least one native Nebula desktop app exists +* It matches the Desktop Mode visual identity +* It helps connect the desktop experience to the wider NebulaOS ecosystem --- -## Development Goals +## Milestone 4: Login, Session, and System Polish v0.4 -Initial Desktop Mode goals: +Status: Future -* Pick KDE Plasma as the base -* Create a Nebula desktop theme -* Create a Nebula SDDM login theme -* Add Bigscreen and Desktop sessions -* Add a launcher shortcut back into Bigscreen Mode -* Keep normal Linux tools available -* Avoid breaking standard KDE functionality +Goal: Make Desktop Mode feel more native from boot/login onward. + +Tasks: + +* [ ] Create SDDM theme +* [ ] Create splash screen +* [ ] Create lock screen styling +* [ ] Add NebulaOS Desktop session entry +* [ ] Add Bigscreen session entry +* [ ] Add desktop-to-bigscreen switch flow +* [ ] Add bigscreen-to-desktop switch flow +* [ ] Improve power menu integration + +Definition of done: + +* Desktop Mode feels connected from login to desktop +* The user can choose or switch sessions cleanly +* NebulaOS feels less like a theme and more like an operating system experience + +--- + +## Milestone 5: Packaging and Distribution v0.5 + +Status: Future + +Goal: Make Desktop Mode installable and repeatable. + +Tasks: + +* [ ] Clean install script +* [ ] Clean uninstall/reset script +* [ ] Package theme files properly +* [ ] Package wallpapers properly +* [ ] Package desktop shortcuts properly +* [ ] Prepare Arch/EndeavourOS install steps +* [ ] Prepare ISO integration later +* [ ] Add screenshots and setup instructions + +Definition of done: + +* Desktop Mode can be applied consistently on a clean KDE install +* Installation does not rely on manual file copying +* The README clearly explains how to test and apply the desktop theme + +--- + +## Useful Test Commands + +```bash +kbuildsycoca6 +plasmoidviewer -a org.nebula.launcher +./Desktop/scripts/reload-plasma.sh +./Desktop/scripts/apply-nebula-desktop.sh +``` + +`reload-plasma.sh` refreshes Plasma after editing symlinked repo files. + +`apply-nebula-desktop.sh` copies the repo packages into local KDE folders for install and packaging tests. --- @@ -253,6 +553,8 @@ Desktop Mode should avoid: * Becoming too console-like * Depending on Bigscreen Mode to function * Locking users into one workflow +* Deep KDE source changes too early +* Rebuilding things KDE already handles well Desktop Mode should be powerful, normal, and clean. @@ -264,8 +566,33 @@ Desktop Mode is successful when: * Users can use NebulaOS like a normal Linux desktop * KDE feels visually integrated with NebulaOS +* Desktop Mode feels polished instead of temporary * Bigscreen Mode can be launched easily * Advanced settings are accessible * Development and troubleshooting are possible -* The desktop feels polished instead of temporary -* The system still feels like one unified OS +* Gaming and modding workflows are supported +* The desktop has its own identity without breaking Linux flexibility + +--- + +## Current Priority + +The current priority is: + +```text +Milestone 1: NebulaOS Desktop Theme v0.1 +``` + +Focus on: + +* Wallpaper +* Color scheme +* Panel styling +* Menu and popup styling +* Notifications +* Task manager active indicators +* Bigscreen shortcut +* Nebula Browser shortcut +* Clean apply/reload scripts + +Do not focus on the full login system, custom store, mod manager, or ISO packaging yet. The base Desktop Mode identity should come first. diff --git a/Desktop/README.md b/Desktop/README.md deleted file mode 100644 index dabac24..0000000 --- a/Desktop/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# NebulaOS Desktop Mode - -NebulaOS Desktop Mode is the mouse-and-keyboard desktop layer for NebulaOS. It uses KDE Plasma as the starter foundation so the system can provide a normal Linux desktop while the Nebula-specific shell, launcher, and visual identity mature. - -The repository is the source of truth. Local KDE folders under `~/.local/share` are runtime and test targets only. During development, symlinks can point KDE at the files in this repo; for packaging and install testing, use the apply script to copy the same repo files into KDE's local package locations. - -## Current Customisation Layer - -Starter KDE Plasma customisation currently happens through: - -- Plasma desktop themes for shell surfaces such as panels, widgets, popups, dialogs, and SVG assets. -- Look-and-feel packages for grouping the desktop experience under a Nebula identity. -- Color schemes for the Nebula Dark palette. -- Plasmoids for prototype Nebula desktop widgets such as the launcher. -- Later, KWin scripts and deeper KDE source patches after this prototype layer works. - -This layer should stay small and safe for now. Avoid deep KDE source changes until the Plasma theme, color scheme, look-and-feel package, and launcher prototype are easy to test and iterate. - -## Useful Test Commands - -```bash -kbuildsycoca6 -plasmoidviewer -a org.nebula.launcher -./Desktop/scripts/reload-plasma.sh -./Desktop/scripts/apply-nebula-desktop.sh -``` - -`reload-plasma.sh` is for refreshing Plasma after editing symlinked repo files. `apply-nebula-desktop.sh` copies the repo packages into local KDE folders for install and packaging tests. diff --git a/README.md b/README.md index 4453d1e..43ad461 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ Desktop Mode should feel clean, modern, and polished, with a design direction in Read more in: ```text -Desktop/README.md +Desktop/README-Desktop.md ``` ---