A Spotube theme is a complete **design language** for the app, not just a colour scheme. One theme can change the typeface, the icon set, every control's shape, bevel and hover behaviour, the backdrop behind all screens, and it can offer a few settings (accent, corner style, glow) that you adjust yourself. Every theme has a light and a dark look.

Themes are packages, installed the same way as plugins: a `.zip` containing a `theme.json` plus optional fonts, an icon pack, a logo and a `LICENSE`. Spotube reads the zip in memory and never runs anything from it, so a theme is pure data.

## Install a theme

1. Open **Settings → Appearance** (on phones the Appearance page also has the Light / Dark / System choice).
2. Under **Discover themes**, pick a repository, then a release and its `.zip`; or choose **Install theme** and pick a `.zip` from your device.
3. Spotube shows who made it, its links, licence and contents. Confirm to install.
4. Select the theme's card. Open its details and use **Customize** to change its parameters.

Only install themes from people you trust: fonts and images are decoded by system libraries, which is why Spotube asks you to confirm first.

## Discover themes

**Discover on GitHub** (Settings → Appearance) lists the public GitHub repositories tagged with **both** topics `spotube` and `spotube-theme` (forks are left out), most starred first. Open one to see its releases and every `.zip` they carry, then pick a file: Spotube downloads it (from github.com only) and shows the usual install dialog.

You can also browse [github.com/topics/spotube-theme](https://github.com/topics/spotube-theme) yourself and install a downloaded `.zip` with the **+** button.

## Updates

Themes can declare where their new versions are published (`updates` in `theme.json`): a GitHub repository and the archive name. Spotube then looks at that repository's releases, takes the newest published release whose tag is a semantic version (`1.2.0` or `v1.2.0`) that has the archive, and compares it with the installed version.

- **The selected theme is checked automatically** when Spotube starts and when you switch themes (unless you turned off checking for updates in settings). If a newer version exists you get a dialog with the release notes: **Update** installs it, **Ignore** skips that version.
- The **refresh** button on the Appearance page checks **all** installed themes; rows with a newer version show **Update to X**, which downloads the archive and opens the install dialog.
- An automatic update only replaces the installed theme when the archive has the same id and a newer version, and it is validated like any other import.

### Updating, replacing and downgrading

Installing a theme whose `id` is already installed works like updating a plugin, using the theme's own `version` (semver):

| The package is | Spotube asks |
|---|---|
| A newer version | **Update** to the new version. |
| The same version | **Replace** the installed copy? |
| An older version | **Replace** anyway? (a downgrade is never silent) |
| Not valid semver (either side) | **Replace** anyway? (it can't be compared) |

A fresh install is selected right away; updating or replacing a theme keeps whichever theme you have selected, and your **Customize** choices are kept per theme. Bump `version` in `theme.json` for every release so users get a proper update.

## Make your own

- [Creating a theme](/themes/creating-a-theme): `pnpm create spotube-theme` and the `@team-spotube/theme-tool` CLI, step by step.
- [Theme format](/themes/theme-format): every part of `theme.json`.
- [Schema and versioning](/themes/schema-versioning): the JSON Schema, the semver rules and what keeps old themes working.
- [Example themes](/themes/example-themes): ten finished themes and the techniques each one shows off.

[themes]: https://github.com/team-spotube/themes
