Nebula-OS/Desktop/README-Desktop.md

NebulaOS Desktop Mode

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.

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.

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

Desktop Mode is designed for:

• File management
• Web browsing
• Productivity
• Development
• Modding
• Troubleshooting
• Advanced settings
• Desktop gaming
• App management
• System maintenance
• Mouse and keyboard workflows

NebulaOS should feel simple in Bigscreen Mode, but never locked down. Desktop Mode is what keeps NebulaOS flexible, useful, and powerful.

---

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

• KDE Plasma selected as the Desktop Mode foundation
• Desktop Mode repo structure created
• Starter KDE theme files copied into the repo
• Theme files are being edited directly from the repo
• Symlink-based development workflow started
• Apply script created or started
• Plasma reload workflow started
• Desktop Mode separated from Bigscreen Mode conceptually
• 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

Parallel track: OS login (controller-friendly)

Desktop Mode work now includes a controller-friendly OS login so Bigscreen Mode does not need its own account creation, PIN lock, or sign-in flows.

Planned at the system layer (SDDM + sessions):

• Nebula SDDM theme navigable with a gamepad
• Account picker and sign-in
• Session choice: Nebula Bigscreen vs Nebula Desktop
• First-run / account setup when needed (desktop or login side, not inside Bigscreen)

This can proceed alongside Plasma theme work; it does not need to wait until every panel pixel is final.

Not the Focus Yet

The following are planned, but should not block the base Desktop theme or login track:

• Full Nebula Control Center
• Nebula Store
• Nebula Library desktop app
• Nebula Mod Manager
• Deep KDE source patches
• Full ISO packaging
• First-run setup / OOBE

---

Recommended Foundation

The recommended Desktop Mode foundation is:

• Linux
• KDE Plasma
• SDDM
• Wayland where possible
• X11 fallback where needed
• 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:

• Highly customizable
• Friendly to Linux gaming workflows
• Themeable
• Mature
• Flexible
• Suitable for both desktop and handheld layouts
• Easier to prototype with than writing a whole desktop shell from scratch

---

Repository & Development

This repository is the source of truth for Desktop Mode.

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.

This means:

• 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

---

Desktop Mode Responsibilities

Desktop Mode should provide:

• File manager access
• Browser access
• Terminal access
• App launcher
• System settings
• Development tools
• Game modding tools
• Desktop game launching
• Access to Bigscreen Mode
• Advanced troubleshooting tools
• App management
• System maintenance

Desktop Mode should feel like a proper computer desktop, not just a fallback mode.

---

KDE Customization Goals

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 later
• Custom splash screen later
• Custom panel layout
• Custom application launcher direction
• Custom desktop widgets
• 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 Desktop Mode layout:

Floating bottom panel
├── Nebula launcher
├── Search
├── Pinned apps
├── Open apps
├── Bigscreen shortcut
├── System tray
├── Network
├── Audio
├── Battery
├── Clock
└── Quick settings

Desktop
├── Nebula wallpaper
├── Minimal icons
└── Optional widgets

Launcher
├── Search
├── Pinned apps
├── Recent apps
├── Games
├── Files
├── Settings
├── 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 the wider NebulaOS project while remaining calmer and more practical than a controller-first interface.

Shared elements may include:

• Nebula gradients
• Deep blue and purple tones
• Soft glass panels
• Rounded corners
• Subtle glow
• Clean typography
• Space-inspired wallpapers
• Calm animation
• Consistent icon language

Visual Keywords

Glass
Depth
Glow
Blur
Soft shadows
Rounded panels
Dark translucent surfaces
Blue/purple nebula gradients
Clean typography
Minimal clutter
Gaming polish
Desktop productivity

---

Plasma vs Native Desktop Apps

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:

• Choose KDE Plasma as the Desktop Mode foundation
• Set up the repo structure
• Copy starter KDE theme files into the repo
• Set up symlinks for development
• Begin editing the Plasma theme
• Add or start apply script
• 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:

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 Store

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

---

Milestone 4: Login, Session, and System Polish v0.4

Status: Planned (parallel with theme milestones)

Goal: Provide a controller-friendly OS login so users pick account and session before Bigscreen or Desktop starts. Bigscreen Mode should not implement account creation or login.

Tasks:

• Create controller-friendly SDDM theme
• Account picker and sign-in usable with gamepad and keyboard
• Session entries: Nebula Bigscreen and Nebula Desktop
• First-run / account setup flow (OS or desktop side, not in Bigscreen shell)
• Create splash screen
• Optional lock/suspend styling consistent with SDDM (session layer, not Bigscreen PIN)
• Add desktop-to-bigscreen switch flow
• Add bigscreen-to-desktop switch flow
• Log out / switch user returns to SDDM
• Improve power menu integration in Bigscreen (return to login only)

Definition of done:

• Users can sign in and choose Bigscreen or Desktop from the couch with a controller
• Bigscreen Qt shell starts already authenticated—no in-shell login or account wizard
• Desktop Mode feels connected from login to desktop
• 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

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.

---

What Desktop Mode Should Avoid

Desktop Mode should avoid:

• Removing normal Linux functionality
• Hiding important system tools
• Making KDE harder to use
• 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.

---

Success Criteria

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
• Gaming and modding workflows are supported
• The desktop has its own identity without breaking Linux flexibility

---

Current Priority

The current priority is:

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.