Theme Studio, Sound Studio and a Permission Inspector for Frappe & ERPNext. Install the version-16 branch on v16, the version-15 branch on v15.
# Nexus Theme
**Make your workspace yours.** Colours, sounds, a themed sign-in screen and a clear view of who can do what, all inside your ERPNext / Frappe Desk. Pick one of 17 ready-made themes or build your own, choose the sounds the Desk plays, give the login page your own look, and let administrators see and change permissions in plain language.
   
**Two branches, one app.** You are looking at the build for Frappe / ERPNext **16**
— branch [`main`](https://github.com/abbas0444/nexus_theme/tree/main), also published
as [`version-16`](https://github.com/abbas0444/nexus_theme/tree/version-16).
Running Frappe / ERPNext **15**? Use
[`version-15`](https://github.com/abbas0444/nexus_theme/tree/version-15).
---
## A Look at It
Every screenshot below is the app running on a real ERPNext 16 site.
| Theme Studio | Permission Inspector |
|---|---|
|  |  |
| Pick a theme and watch a miniature Desk repaint as you go. | See what a role or a person may do, record type by record type. |
| Sign-in screen | Sound Studio |
|---|---|
|  |  |
| Optional two-column login page, painted in your theme. | Choose the sound the Desk plays for each event. |
---
## Table of Contents
1. [What Nexus Theme Gives You](#1-what-nexus-theme-gives-you)
2. [Install It](#2-install-it)
3. [Where to Find Everything on the Desk](#3-where-to-find-everything-on-the-desk)
4. [Theme Studio: Pick and Build Themes](#4-theme-studio-pick-and-build-themes)
5. [Sound Studio: Choose Your Sounds](#5-sound-studio-choose-your-sounds)
6. [Permission Inspector: Who Can Do What](#6-permission-inspector-who-can-do-what)
7. [Administrator Guide: Theme Settings](#7-administrator-guide-theme-settings)
8. [The Record Types Behind It All](#8-the-record-types-behind-it-all)
9. [Who Can Use What (Roles)](#9-who-can-use-what-roles)
10. [Everyday Recipes](#10-everyday-recipes)
11. [How It Works Under the Hood](#11-how-it-works-under-the-hood)
12. [For Developers](#12-for-developers)
13. [Things to Know](#13-things-to-know)
14. [Troubleshooting and FAQ](#14-troubleshooting-and-faq)
15. [Requirements and License](#15-requirements-and-license)
---
## 1. What Nexus Theme Gives You
Nexus Theme is one Frappe app with three tools inside it. Install it once and every feature is ready; nothing needs to be switched on.
| Tool | Who it is for | What it does |
|---|---|---|
| **Theme Studio** | Everyone who uses the Desk | Pick a theme, adjust colours and fonts with a live preview, generate a whole theme from one brand colour, pair a light and a dark theme, share themes with the team, export and import themes as files. |
| **Sound Studio** | Everyone who uses the Desk | Choose the sound the Desk plays on login, save, submit, cancel, delete, errors, email, alerts and notifications. Use a bundled preset or upload your own, set the volume, or mute everything. |
| **Permission Inspector** | System Managers | Pick a person or a role and see, record type by record type, what they may View, Edit, Create, Delete, Submit and Cancel, which role gives them that, and change it safely from the same screen. |
| **Theme Settings** | System Managers | Site-wide controls: a default theme for everyone, an allowed list, whether people may build or share themes, the company logo and favicon, and a master switch for sounds. |
| **Login Page** | System Managers switch it on; everyone sees it | A two-column sign-in screen painted in the site's theme colours, with your logo, your headline and bullet points on a coloured panel. Off by default; Frappe's own login page stays until you turn it on. |
| **Three record types** | Nobody has to open them | *Theme Definition*, *User Theme Preference* and *User Sound Preference* are where the studios store everything. They are listed in the workspace so you can look, fix or pre-build a company theme — see [section 8](#8-the-record-types-behind-it-all). |
Everything is per user. Your theme and sounds are yours; nobody else sees them unless you share a theme on purpose.
---
## 2. Install It
**On Frappe Cloud:** open your site, choose *Apps → Install App*, and pick **Nexus Theme** from the Marketplace. Nothing else to do.
### Which version do I need?
Run `bench version` first and read the **frappe** line.
| Your bench | Branch to install | Install with |
|---|---|---|
| Frappe / ERPNext **16** | `version-16` (same code as `main`) | `bench get-app --branch version-16 https://github.com/abbas0444/nexus_theme.git` |
| Frappe / ERPNext **15** | `version-15` | `bench get-app --branch version-15 https://github.com/abbas0444/nexus_theme.git` |
Both branches hold the same features; they differ only where the two frameworks
differ. `main` is the same code as `version-16`, so leaving `--branch` out gets you
the 16 build. Installing the wrong one damages nothing, but the app will not work
properly — switch branches and run `bench --site yoursite.com migrate` again.
**On your own bench:** run these commands. Replace `yoursite.com` with your site name.
```bash
cd /path/to/your/bench
bench get-app --branch version-16 https://github.com/abbas0444/nexus_theme.git
bench --site yoursite.com install-app nexus_theme
bench --site yoursite.com migrate
bench restart # or restart `bench start` in development
```
Installation does all of this for you:
- Creates the **Theme User** role and gives it to every Desk user, so Theme Studio and Sound Studio work at once. New Desk users get the role automatically when they are created or promoted.
- Loads the **17 bundled themes**.
- Creates the **Theme Settings** record with every option switched off, so the app changes nothing about your site until you decide.
- Adds **Theme Studio** and **Sound Settings** to the avatar menu, the **Nexus Theme** tile to the apps screen, and the **Nexus Theme** workspace with all its shortcuts.
- Registers the **Permission Inspector** page for System Managers.
Updating later is the usual `bench update` or `git pull` followed by `bench --site yoursite.com migrate`. Your custom themes and sound choices survive updates.
Uninstalling (`bench --site yoursite.com uninstall-app nexus_theme`) removes the role, the menu items, the tile and the app's own tables. It never touches Frappe's own permission records.
---
## 3. Where to Find Everything on the Desk
| Place | What you will see |
|---|---|
| **Avatar menu** (top-right) | Theme Studio, Sound Settings |
| **Apps screen** (the grid icon or `/apps`) | A **Nexus Theme** tile that opens the workspace |
| **Nexus Theme workspace** (`/app/nexus-theme`) | Shortcuts to Theme Studio, Sound Studio, Themes, Theme Settings and Permission Inspector, plus cards for every record type the app owns |
| **Search bar** (Ctrl+K / Cmd+K) | Type `Theme Studio`, `Sound Studio`, `Permission Inspector` or `Theme Settings` |
| **Frappe's own Switch Theme dialog** (avatar menu, Toggle Theme) | Every Nexus theme is listed there too, next to Frappe Light and Timeless Night |
| Direct links | `/app/theme-studio`, `/app/sound-studio`, `/app/nexus-permission-inspector`, `/app/theme-settings` |
| **Login page** (`/login`) | Frappe's own sign-in screen, or the Nexus login page once an administrator switches it on in Theme Settings |
*The workspace at `/app/nexus-theme`: shortcuts on top, record types underneath. The three pages sit in the sidebar on the left.*
The apps screen carries a **Nexus Theme** tile, and the avatar menu in the corner opens either studio from wherever you are:
---
## 4. Theme Studio: Pick and Build Themes
### 4.1 The five-minute flow
1. Click your **avatar** (top-right) and choose **Theme Studio**.
2. Click any theme card. The **Live Preview** inside the dialog, a small mock-up of the Desk, shows how it looks.
3. Happy? Click **Apply** and the whole Desk changes at once. Not sure? Click another card. Nothing is stored until you press Apply.
4. Want to tweak it? Click **Customize** and adjust colours; the preview follows every change.
Press **View Login** at any point to see the sign-in screen in the same theme.
5. Want to keep your tweaks? Click **Save as Custom…**, give it a name and, if you like, tick **Share with other users**.
Your choice is remembered on every device you log in from.
*Theme Studio. The Live Preview at the top is a miniature Desk — navbar, sidebar, table, buttons — so you can judge a theme before applying it. The buttons along the bottom are always in reach.*
Click a different card and only the preview changes. The Desk behind it stays as it was until you press **Apply**:
**View Login** opens the sign-in screen in whichever theme is selected, without signing out:
### 4.2 The three theme lists
| List | What is in it |
|---|---|
| **Default Themes** | The 17 themes that ship with the app |
| **My Custom Themes** | Themes you saved. Only you see them, and you can delete them here. |
| **Public Themes** | Themes your colleagues chose to share with everyone |
The 17 bundled themes are:
- **Dark:** Midnight Indigo, Graphite Dark, Nord Frost, Dracula, Tokyo Night, GitHub Dark, Material Ocean, Cyberpunk Neon
- **Light:** GitHub Light, Solarized Light, Ocean Breeze, Forest Green, Rose Quartz, Mint Fresh, Solar Warmth, Sepia Reader, High Contrast
### 4.3 The editor: Basic and Advanced
Click **Customize** on any theme. The editor shows a **Live Preview** card and a set of controls. Every change is applied to the Desk behind the dialog as you make it.
**Basic** shows the controls most people need:
| Control | What it changes |
|---|---|
| Background | The main backdrop of the Desk |
| Text Color | Text on that backdrop |
| Accent | Links, highlights, the active item |
| Font Family | Inter, system fonts, monospace and more |
| Font Size | The base size everything scales from |
| Corner Radius | How rounded cards, buttons and inputs are |
| Hover Lift | Cards rise slightly when you hover over them |
*The Basic tab. The green bar at the bottom is the readability check — it recalculates on every change, so you always know whether the theme is legible before you save it.*
**Advanced** adds the rest of the 11 colours and the finer settings:
| Control | What it changes |
|---|---|
| Surface / Cards | Cards, sidebars and panels |
| Input Background | Search boxes and form fields |
| Muted Text | Secondary labels and hints |
| Accent Hover | The accent colour when you hover |
| Button Color, Button Text, Button Hover | The primary buttons |
| Border | Lines between sections |
| Font Weight | Lighter or bolder text overall |
| Animation Speed | How fast hover and fade effects run |
### 4.4 Palettes: fill all 11 colours at once
Open the **Palettes** tab and click a set. Every colour in the editor is filled together, and each set is checked for readability before it ships:
Indigo Mist · Forest Paper · Rose Quartz · Graphite Amber · Midnight Violet · Carbon Teal · Obsidian Rose · Nordic Frost
![The Palettes tab