Theme add-ons: import and create themes

Theme add-ons extend Mastery HQ’s built-in wallpaper themes with your own — solid gradients, custom CSS backgrounds, or full video wallpapers. Add-ons live outside the installer in the app’s themes/ folder, so they survive updates and never bloat the download.

Installing a theme

1. Open the Workspace Style palette (top chrome).
2. Click + Import theme (.zip / .json) — a .zip bundles a manifest plus its video; a .json is just the manifest.
3. The theme appears in the palette immediately, marked as an add-on.

Prefer doing it by hand? The palette’s folder button opens the add-ons folder directly (“Open the folder where theme add-ons (and their videos) live”) — drop files in and reload.

Writing your own manifest

A theme is one JSON file:

{
  "id": "my-theme",
  "label": "My Theme",
  "accent": "#ff8a2a",
  "overlay": 0.42,
  "preview": ["#0d2422", "#2a1d14"],
  "video": "myclip.mp4"
}

• id — unique slug; add-ons can’t override a built-in theme’s id.
• accent — the UI accent color the theme applies.
• overlay — 0–1 darkening laid over the wallpaper so panes stay readable.
• preview — two gradient stops for the theme chip in the palette.
• video — optional: a bare filename sitting next to the manifest, an absolute path, or an http(s) URL. Omit it for a pure gradient theme.
• css — optional custom CSS background (for example a gradient) when you want full control instead of a video.

Good to know

• Built-ins are hardcoded; add-ons merge in at load. If an add-on reuses a built-in id, the built-in wins.
• Your add-on library is per-machine — it isn’t part of the app or synced anywhere.