feat: add support for loading custom themes from files (#2218)

* feat: add support for loading custom themes from files --------- Co-authored-by: jeffvli <jeffvictorli@gmail.com>
2026-07-22 02:16:39 +02:00 · 2026-07-19 04:27:09 +02:00
parent 2cab569c23
commit f152e03ae7
14 changed files with 1018 additions and 30 deletions
@@ -0,0 +1,259 @@
+# Custom Themes
+
+Custom themes let you add your own light and dark themes to the **desktop** app without rebuilding Feishin. Drop JSON theme files into the Themes folder; Feishin watches that folder and reloads themes when files change.
+
+Custom themes are **Electron / desktop only**. They are not available in the web or Docker builds.
+
+---
+
+## Getting started
+
+1. Open **Settings → General → Theme**.
+2. Under **Custom Themes**, click **Open Folder** to reveal the Themes directory.
+3. Add a `.json` file (for example `my-theme.json`).
+4. Select the theme from the Theme dropdown (it appears under Dark or Light based on `mode`).
+
+You can also click **Reload** in Settings if a change was not picked up automatically.
+
+### Themes folder location
+
+| Platform | Typical path |
+|----------|----------------|
+| Windows | `%APPDATA%\feishin\Themes` |
+| macOS | `~/Library/Application Support/feishin/Themes` |
+| Linux | `~/.config/feishin/Themes` |
+
+In development builds the folder name is under `feishin-dev` instead of `feishin`.
+
+Theme files must be **`.json` files in the root of the Themes folder** (not nested in subfolders). Linked stylesheets may live next to them or in subfolders, as long as they stay inside Themes.
+
+---
+
+## Theme file format
+
+Each theme is a single JSON object.
+
+```json
+{
+  "mode": "dark",
+  "extends": "defaultDark",
+  "colors": {
+    "primary": "rgb(53, 116, 252)",
+    "background": "rgb(12, 12, 12)",
+    "foreground": "rgb(225, 225, 225)"
+  },
+  "app": {
+    "scrollbar-size": "9px"
+  },
+  "mantineOverride": {
+    "primaryShade": {
+      "dark": 6
+    }
+  },
+  "stylesheets": ["my-theme.css"]
+}
+```
+
+### Identity
+
+| Derived from | Behavior |
+|--------------|----------|
+| **id** | Filename without `.json` (e.g. `rose-pine-custom.json` → `rose-pine-custom`) |
+| **label** | Title-cased id with `-` / `_` replaced by spaces (e.g. `Rose Pine Custom`) |
+
+Use a unique filename. The id is what appears in settings and what you use when another theme `extends` this one.
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `mode` | No (default `dark`) | `"dark"` or `"light"`. Controls which theme group the theme appears in and the app color scheme. |
+| `extends` | No | Built-in theme id or another custom theme’s id (filename without `.json`). Your theme is merged on top of the base. |
+| `colors` | No | Palette overrides. Invalid CSS colors are dropped and shown as a warning in Settings. |
+| `app` | No | App chrome / layout CSS variable overrides. |
+| `mantineOverride` | No | Partial [Mantine theme override](https://mantine.dev/theming/theme-object/). |
+| `stylesheets` | No | Array of CSS file paths **relative to the Themes folder**. Contents are inlined when the theme is active. Paths that escape the Themes folder are ignored. |
+
+Unspecified color and app values fall back to Feishin’s default theme (and then to anything provided by `extends`).
+
+---
+
+## Colors
+
+Supported `colors` keys:
+
+| Key | Typical use |
+|-----|-------------|
+| `background` | Main app background |
+| `background-alternate` | Alternate / nested background |
+| `surface` | Cards, inputs, elevated surfaces |
+| `surface-foreground` | Text on surfaces |
+| `foreground` | Primary text |
+| `foreground-muted` | Secondary / muted text |
+| `primary` | Accent / primary action color (also drives generated primary shades) |
+| `black` | Black token |
+| `white` | White token |
+| `state-error` | Error state |
+| `state-info` | Info state |
+| `state-success` | Success state |
+| `state-warning` | Warning state |
+
+Values must be valid CSS colors recognized by Feishin’s color validator (for example `rgb(...)`, `rgba(...)`, `#rrggbb`, `#rgb`). Named CSS colors like `red` are rejected. Invalid entries are ignored and listed under Custom Themes warnings in Settings.
+
+---
+
+## App variables
+
+Supported `app` keys (CSS values as strings):
+
+| Key | Description |
+|-----|-------------|
+| `content-max-width` | Max width of main content |
+| `root-font-size` | Root font size |
+| `overlay-header` | Header overlay background |
+| `overlay-subheader` | Subheader overlay background |
+| `scrollbar-size` | Scrollbar thickness |
+| `scrollbar-handle-background` | Scrollbar handle |
+| `scrollbar-handle-hover-background` | Handle on hover |
+| `scrollbar-handle-active-background` | Handle when active |
+| `scrollbar-handle-border-radius` | Handle corner radius |
+| `scrollbar-track-background` | Scrollbar track |
+| `scrollbar-track-hover-background` | Track on hover |
+| `scrollbar-track-active-background` | Track when active |
+| `scrollbar-track-border-radius` | Track corner radius |
+
+---
+
+## Extending themes
+
+Use `extends` to start from a built-in or another custom theme and only override what you need.
+
+```json
+{
+  "mode": "dark",
+  "extends": "nord",
+  "colors": {
+    "primary": "#88c0d0"
+  }
+}
+```
+
+Rules:
+
+- Custom theme fields always win over the theme they extend.
+- Custom → custom chains are flattened when loading (depth limit of 10; cycles are ignored).
+- If `extends` is a built-in id, merging with that built-in’s defaults happens in the renderer.
+- If `extends` is omitted, the theme still merges onto Feishin’s shared default palette.
+
+### Built-in theme ids
+
+Use these as `extends` values (same ids as in Settings):
+
+`ayuDark`, `ayuLight`, `catppuccinLatte`, `catppuccinMocha`, `defaultDark`, `defaultLight`, `dracula`, `everforestDark`, `everforestLight`, `githubDark`, `githubLight`, `glassyDark`, `gruvboxDark`, `gruvboxLight`, `highContrastDark`, `highContrastLight`, `materialDark`, `materialLight`, `monokai`, `nightOwl`, `nord`, `oneDark`, `rosePine`, `rosePineDawn`, `rosePineMoon`, `shadesOfPurple`, `solarizedDark`, `solarizedLight`, `tokyoNight`, `vscodeDarkPlus`, `vscodeLightPlus`, `zenburn`
+
+---
+
+## Linked stylesheets
+
+For larger visual overrides (glass effects, layout tweaks, etc.), point `stylesheets` at CSS files inside the Themes folder:
+
+```json
+{
+  "mode": "dark",
+  "extends": "defaultDark",
+  "stylesheets": ["overrides/my-theme.css"]
+}
+```
+
+```text
+Themes/
+  my-theme.json
+  overrides/
+    my-theme.css
+```
+
+Notes:
+
+- Feishin watches **JSON** theme files for automatic reload. After editing only a CSS file, click **Reload** in Settings (or touch/save the `.json` file) so stylesheets are re-read.
+- Empty or unreadable stylesheet paths are skipped with a console warning.
+
+---
+
+## Examples
+
+### Minimal accent-only dark theme
+
+`accent-blue.json`:
+
+```json
+{
+  "mode": "dark",
+  "extends": "defaultDark",
+  "colors": {
+    "primary": "rgb(80, 160, 255)"
+  }
+}
+```
+
+### Full light palette
+
+`paper-light.json`:
+
+```json
+{
+  "mode": "light",
+  "colors": {
+    "background": "rgb(250, 249, 246)",
+    "background-alternate": "rgb(242, 240, 235)",
+    "surface": "rgb(255, 255, 255)",
+    "surface-foreground": "rgb(40, 40, 40)",
+    "foreground": "rgb(30, 30, 30)",
+    "foreground-muted": "rgb(110, 110, 110)",
+    "primary": "rgb(180, 83, 9)",
+    "black": "rgb(0, 0, 0)",
+    "white": "rgb(255, 255, 255)",
+    "state-error": "rgb(185, 28, 28)",
+    "state-info": "rgb(37, 99, 235)",
+    "state-success": "rgb(22, 163, 74)",
+    "state-warning": "rgb(217, 119, 6)"
+  },
+  "app": {
+    "overlay-header": "linear-gradient(rgb(250 249 246 / 50%) 0%, rgb(250 249 246 / 80%))",
+    "scrollbar-handle-background": "rgba(120, 120, 120, 30%)"
+  },
+  "mantineOverride": {
+    "primaryShade": {
+      "light": 5
+    }
+  }
+}
+```
+
+### Theme that extends another custom theme
+
+`nord-soft.json`:
+
+```json
+{
+  "mode": "dark",
+  "extends": "nord",
+  "colors": {
+    "background": "rgb(36, 41, 51)",
+    "surface": "rgb(46, 52, 64)"
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | What to check |
+|---------|----------------|
+| Theme missing from the list | File must be `.json` in the Themes root; use **Reload**. |
+| Theme shows an error in Settings | JSON is invalid or not a top-level object. Fix the file and reload. |
+| Theme loads with a warning | One or more `colors` values were invalid and ignored. |
+| CSS changes not applying | Edit/save the `.json` or click **Reload**; stylesheet watch is tied to JSON changes. |
+| Extending does nothing / looks wrong | Confirm the `extends` id matches a built-in id or another custom filename (without `.json`). Avoid circular chains. |
+
+Broken themes still appear in Settings with their error message so you can fix them without digging through logs.