You make themes with **`@team-spotube/theme-tool`**: a CLI, typed helpers, the [JSON Schema](/themes/schema-versioning), bundled fonts and icon packs, and ten example themes to start from. You do not need to clone any repository.

## 1. Create a project

```bash
pnpm create spotube-theme my-themes
cd my-themes
pnpm install
```

It asks a few questions (theme id and name, author, licence, repository URL, which template to start from) and writes:

```
my-themes/
├── package.json      @team-spotube/theme-tool as a devDependency, plus build/check/zip/dist scripts
├── tsconfig.json
├── src/sunset.ts     your first theme, one TypeScript file; the file name is the theme id
├── fonts/            your own fonts, one folder per family (optional)
└── README.md
```

Everything can also be given as flags, for scripts: `pnpm create spotube-theme my-themes --id sunset --name "Sunset" --author "You" --repository https://github.com/you/my-themes -y`.

## 2. Edit the theme

`src/<id>.ts` default-exports a theme. It is plain data plus a few helpers, fully typed, so your editor completes and checks it:

```ts
import { A, choice, defineTheme, flatComponents, merge, solid } from '@team-spotube/theme-tool';

export default defineTheme({
  name: 'Sunset',
  description: 'Warm and rounded.',
  author: 'You',
  license: 'MIT',
  repository: 'https://github.com/you/my-themes',
  logo: 'logos/sunset.svg',                       // your own artwork: .svg or .png (max 512 px)
  iconPack: { iconify: '@iconify-json/tabler' },  // restyles every icon in the app; any library works
  fonts: { Inter: { from: '@fontsource/inter', files: [['files/inter-latin-400-normal.woff2', 400], ['files/inter-latin-700-normal.woff2', 700]] } },

  parameters: {                                   // what users can change under "Customize"
    accent: choice('Accent', 'orange', [['orange', 'Orange', '#ff7a18'], ['violet', 'Violet', '#7a1eff']]),
  },
  vars: {                                         // your private tokens
    key: { type: 'color', value: ['match', '{params.accent}', { orange: '#ff7a18', violet: '#7a1eff' }] },
    page: { type: 'color', value: A('#ffffff', '#101014') },   // A(light, dark)
  },
  tokens: {
    color: { background: '{vars.page}', accent: '{vars.key}' },
    type: { family: 'Inter' },
    app: { background: solid('{vars.page}') },    // the backdrop behind every screen
  },
  components: merge(flatComponents(), {
    button: { variants: { primary: { base: { background: solid('{vars.key}'), foreground: '#ffffff', shape: 'pill' } } } },
  }),
});
```

| Helper | What it does |
|---|---|
| `defineTheme(theme)` | Type-checks the theme. |
| `A(light, dark)` | A value that differs between appearances. |
| `choice(label, default, options)` | A parameter with colour swatches. |
| `solid(color)` | A flat brush. |
| `flatComponents()` | Switches off all of Millennium's built-in gloss (shadows, rims, glows, scaling), so a theme only has the effects it asks for. |
| `merge(a, b)` | Deep merge. |

What every property means is in the [theme format](/themes/theme-format). The starter covers the controls most themes touch; anything you leave out keeps Millennium's default look.

### Your logo

`logo` is the path of **your** artwork: a `.png` (up to 512 x 512) or an `.svg` (rendered to a 512 px PNG; convert text to paths first). The tool never generates a logo. The project starts with a clearly marked placeholder that the build warns about until you replace it.

### Any font

```ts
fonts: {
  Inter: { from: '@fontsource/inter', files: [['files/inter-latin-400-normal.woff2', 400], ['files/inter-latin-700-normal.woff2', 700]] },
  Mine:  { dir: 'my-font', files: [['MyFont-Regular.ttf', 400]] },   // ./fonts/my-font/
}
```

`from` takes any npm font package (`pnpm add -D @fontsource/inter`, `@expo-google-fonts/...`) or a `./path`; `dir` is a folder in your project's `fonts/` or one of the 12 bundled families (`pnpm exec spotube-theme list`). Files can be `.ttf`, `.otf`, `.woff` or `.woff2`: Spotube loads TrueType/OpenType, so the web formats are converted for you. The font's licence is copied into the theme's `LICENSE`. Use a font per text role with `tokens.type.styles`.

### Any icon library

```ts
iconPack: { iconify: '@iconify-json/hugeicons' },                       // pnpm add -D @iconify-json/hugeicons
iconPack: { iconify: '@iconify-json/ph', suffix: '-bold' },             // a style variant
iconPack: { svgDir: 'node_modules/feather-icons/dist/icons', license: 'MIT' },
iconPack: 'phosphor-fill',                                              // or one of the bundled packs
```

Spotube restyles every icon, including the ones inside controls, through about 90 *roles* (Lucide names such as `house`, `skip-forward`, `trash-2`). The tool finds each library's icon for a role (by name and synonyms), renders it to a PNG, and Spotube tints it like its own icons. [Iconify](https://icon-sets.iconify.design) sets cover 200+ libraries: Hugeicons, Tabler, Material Symbols, Heroicons, Remix, Carbon, Lucide, Phosphor, Bootstrap, Font Awesome, Fluent and more, including stroke-based ones. The build lists roles it could not find (they keep the stock icon); map them with `names: { 'skip-forward': 'player-skip-forward' }`. Options: `suffix`, `prefix`, `names`, `size`, `tint`, `license`. Generic packs need theme format 1.1, which the tool declares automatically; bundled packs work with 1.0.

### Start from an example instead

```bash
pnpm exec spotube-theme add neon --template neon-noir --name "My Neon" --author "You"
```

copies one of the ten [example themes](/themes/example-themes) into `src/neon.ts` for you to change.

## 3. Build, check, package

```bash
pnpm dist          # = build + check + zip
```

| Command | Result |
|---|---|
| `spotube-theme build` | `src/<id>.ts` → `themes/<id>/` (`theme.json`, `logo.png`, the exact fonts and icon font used, and a `LICENSE` carrying every font's licence) |
| `spotube-theme check` | validates against the [JSON Schema](/themes/schema-versioning) (a misspelt property is an error), checks metadata, parameters, file types and the size limits Spotube enforces on install |
| `spotube-theme zip` | `dist/<id>.zip`, reproducible, plus `dist/index.json` |

Install `dist/<id>.zip` from **Settings → Look & feel → Themes → Install theme** to try it.

To see exactly how the real engine renders it, run Spotube's own test from a Spotube checkout:

```bash
THEMES_DIR=/path/to/my-themes/themes ./gradlew :composeApp:jvmTest --tests '*ThemeFolderValidationTest*'
```

It requires **zero warnings**, compiles every parameter choice in light and dark, and writes PNG renders to `composeApp/build/theme-gallery/external`. Open them and check text is readable on every fill, in both appearances.

## 4. Publish

1. Push the project to a public GitHub repository (not a fork).
2. Add the topics **`spotube`** and **`spotube-theme`** (**About → Topics**; both are required). That is how it appears in the app's *Discover on GitHub* list, sorted by stars.
3. Create a release tagged with a semantic version (`v1.2.0` or `1.2.0`) and attach `dist/<id>.zip`. Users pick the release and the file in the app.
4. Set `updates: true` in your theme (with `repository` pointing at the GitHub repo): Spotube then checks that repository's releases for a newer semver tag (with or without `v`) that carries `<id>.zip`. It checks the **selected theme automatically** at app start (users see a dialog with your release notes, so write them) and every installed theme when the user taps refresh on the Appearance page. `updates: { github: 'https://github.com/you/repo', asset: 'my-theme.zip' }` uses another repository or archive name.
5. Bump the theme's `version` for every release and make it match the tag. Themes without an explicit `version` share the `version` in your `package.json`, so one tag matches every theme in a multi-theme repository.

## Without the tool

The tool is a convenience. A theme is just a folder with a `theme.json` (plus optional fonts and PNGs): write it by hand, add `"$schema"` for editor help, and zip the folder contents (files at the root of the zip). The [theme format](/themes/theme-format) describes everything the file can contain.
