Creating a theme

Bootstrap, build, check and publish a Spotube theme with pnpm create spotube-theme and @team-spotube/theme-tool.

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

1. Create a project

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:

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. The starter covers the controls most themes touch; anything you leave out keeps Millennium's default look.

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

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

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 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

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

copies one of the ten example themes into src/neon.ts for you to change.

3. Build, check, package

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 (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:

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 describes everything the file can contain.