Creating a theme
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' } } } },
}),
});
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.
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
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
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
- Push the project to a public GitHub repository (not a fork).
- Add the topics
spotubeandspotube-theme(About → Topics; both are required). That is how it appears in the app's Discover on GitHub list, sorted by stars. - Create a release tagged with a semantic version (
v1.2.0or1.2.0) and attachdist/<id>.zip. Users pick the release and the file in the app. - Set
updates: truein your theme (withrepositorypointing at the GitHub repo): Spotube then checks that repository's releases for a newer semver tag (with or withoutv) 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. - Bump the theme's
versionfor every release and make it match the tag. Themes without an explicitversionshare theversionin yourpackage.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.