Theme format

Everything a theme.json can contain - metadata, tokens, per-component styling, brushes, expressions, parameters, fonts, icon packs and the package security model.

This is the reference for the contents of a theme package. For a walkthrough, start with Creating a theme. Every property name below is also in the JSON Schema, which gives your editor autocomplete.

Schema version

theme.json has a JSON Schema (JSON Schema, generated from the same property tables the compiler uses, so it lists every property of every component) and a semver schema version (THEME_SCHEMA_VERSION in ThemeDocument.kt). A theme of the same major always loads; a newer minor loads with its newer parts ignored (a warning on the card); another major is refused; patch never matters. Full policy and examples: Schema and versioning.

Package layout

my-theme.zip
├── theme.json        required, at the root
├── logo.png          optional, referenced by "logo" (max 512 x 512)
├── LICENSE           optional, shown on the theme's card
├── fonts/*.ttf|otf   optional
└── icons/*.png       optional

Metadata (top of theme.json)

Field Required Notes
id yes A-Z a-z 0-9 . _ -, up to 48 chars; installing the same id again updates the theme
name, version, author yes version is the theme's own version
description no up to 500 chars
repository, bugs, homepage no http(s) URLs only; "Report an issue" opens bugs
contact no an email address or an http(s) URL
license no SPDX id or a short name; ship the text as LICENSE
logo no path of a .png inside the zip
updates no { "github": "https://github.com/owner/repo", "asset": "my-theme.zip" } (since 1.2.0): where Spotube looks for newer versions. It reads the repository's published releases, takes the newest whose tag is a semver (with or without v) and that has an asset named asset, and offers an update when it is newer than version. The selected theme is checked automatically when the app starts; the Appearance page's refresh button checks all installed themes
schema yes the theme format version this theme is written for, semver ("1.1.0"; declare the lowest version that has every feature you use). See Schema and versioning; the JSON Schema is schema/theme.schema.json (also https://docs.spotube.cc/schemas/theme/1.json)
$schema no editor hint: "https://docs.spotube.cc/schemas/theme/1.json"

How a theme styles the app

Two modes in one file, both optional:

  • Global: tokens.interaction and tokens.surface (see below), tokens.app.background (any brush, e.g. a gradient, painted behind every screen instead of the flat background colour), tokens.color (replaces any of the 15 palette roles: background surface raised inset text muted border highlight accent accentTop accentBottom onAccent success danger scrim), tokens.shape (small medium large), tokens.type (family, scale, styles.<name>), and defaults (props applied to every component that has them, e.g. { "shape": 12 }).
  • Per component: components.<name> with base, states, variants, rules. Component names are Millennium's component themes without the Theme suffix: button iconButton segmentedButton toggleSwitch checkbox triStateCheckbox radioGroup slider progress loading textField autocomplete card listTile avatar tooltip scrollbar separator tabGroup disclosure dialog drawer bottomSheet modalBottomSheet dropdownMenu sidebar bottomNavigationBar topAppBar scaffold snackbar pullToRefresh icon text, plus the app's own components described in "In-house components" below (since 1.3.0).

Cascade, later wins: defaults → base → states.<state> → variants.<v>.base → variants.<v>.states.<state> → matching rules. States: default hovered focused pressed disabled selected error. Components with several slots use variants for them: button/iconButton → primary secondary quiet danger; sidebar → root header content footer group item badge trigger; bottomNavigationBar → main item. A base applies to every slot of a component, so for these always put slot properties under variants (a border set in bottomNavigationBar.base would also box every dock item).

The dock (bottomNavigationBar) is fully themeable: main takes the bar's background, shape, borderColor/Width, shadowElevation, overlayBrush, contentPadding, itemSpacing, minimumHeight and, for a floating inset dock, margin plus insetsInsideSurface: false; item takes per-state background, foreground, shape, labelStyle, borders, scales and effects (states.selected is the active tab).

Property names are Millennium's own (background, shape, borderWidth, shadowElevation, innerGlowColor, trackBackground, thumbBackground, ...). Every property a Millennium component theme declares is available; the exhaustive list with docs is the KDoc of the Millennium*ThemeProperties classes, and the generated mapping is core/ui/theming/engine/GeneratedThemeProps.kt. Properties a component doesn't have are reported as unknown property warnings on the theme's card, so typos don't fail silently. The bundled Modern theme (BuiltInThemes.kt) is a complete worked example.

In-house components (mediaCard, floatingPlayer, ...)

Besides Millennium's components, the app's own components are themed with the same JSON (base, states, variants, rules, vars, same cascade and value types). Each styled part is a slot, addressed as a variants key; states are the usual default hovered focused pressed disabled selected error. A slot you don't mention keeps the stock look, and the theme's global defaults are not applied to these components (they would restyle every card of a theme written before they existed), so name the component to opt in.

Component Slots (variants) Notes
mediaCard (album / playlist / artist / track / liked-songs cards) root: width background highlightBackground shape borderColor borderWidth shadowElevation innerGlowColor scale transitionMillis scaleMillis; artwork: shape actionPadding actionSize actionSpacing; info: padding spacing titleStyle subtitleStyle hovered also covers keyboard focus-within; pressed sets the press scale; error is a blacklisted item. highlightBackground fades in over background while lit.
floatingPlayer (the mini player on compact screens) root: background shape borderColor borderWidth shadowElevation contentPadding horizontalMargin progressHeight progressSpacing controlsSpacing; artwork: size shape background placeholderSize placeholderTint spacing; info: titleStyle subtitleStyle Its total height is fixed by the layout and is not themeable; horizontalMargin insets it from the sides so it lines up with a floating (inset) dock.
largePlayer (desktop bottom player) root: tint blurRadius contentPadding; artwork: size shape background spacing; info: titleStyle artistStyle heartSpacing; transport: timeStyle activeTint inactiveTint volumeWidthFraction tint is laid over the blurred backdrop; activeTint is shuffle/loop when on.
expandedPlayer (full-screen player, compact screens) root: contentPadding topSpacing headerStyle; artwork: widthFraction shape background padding; info: rowPadding titleStyle artistStyle; transport: seekPadding timePadding timeStyle controlsPadding playIconSize activeTint inactiveTint; lyrics: outerPadding contentPadding contentSpacing shadowElevation previewHeight titleStyle iconTint; optionTile: contentPadding iconSize iconTint spacing labelStyle lyrics is the preview card; optionTile a tile of the options sheet.
playerQueue root: contentPadding spacing filterSpacing listPadding titleStyle emptyStyle; row: height handleSize handleTint thumbSize thumbShape thumbBackground thumbIndexStyle titleStyle subtitleStyle durationStyle trailingSpacing participantSize participantBackground participantStyle row.states.selected is the playing track.
mediaListTile (list-mode album / playlist / artist / track) none (states only): background borderColor titleForeground shape borderWidth padding compactPadding minimumHeight compactMinimumHeight artworkSize compactArtworkSize actionSize compactActionSize actionSpacing titleStyle subtitleStyle selected = playing, error = blacklisted.
mediaArtwork none: background shape borderColor borderWidth placeholderSize placeholderTint Thumbnail with placeholder.
emptyState none: padding maxWidth spacing iconBoxSize iconBoxShape iconBoxBackground iconBoxBorderColor iconBoxBorderWidth iconSize iconTint titleStyle descriptionStyle  
trackList card: outerPadding innerPadding separatorInset feedbackPadding feedbackStyle errorColor; row: background selectedBackground titleStyle leadingSpacing indexWidth indexStyle artworkSize artworkShape artworkOverlay overlayIconSize overlayIconTint artistSpacing artistStyle artistSeparatorStyle trailingSpacing albumStyle albumMaxWidth durationStyle durationWidth row selected = current or bulk-selected, error = blacklisted. Per-row ctx.item.* rules work.
trackOptions none: sheetPadding sheetSpacing listPadding itemSpacing itemPadding itemGap iconSize labelStyle disabledAlpha headerPadding headerSpacing headerArtworkSize headerArtworkShape headerTitleStyle headerArtistStyle headerAlbumStyle Track actions sheet.
collectionHeader none: outerPadding padding compactPadding spacing compactSpacing infoSpacing compactInfoSpacing buttonSpacing artworkSize compactArtworkSize artworkShape placeholderStyle titleStyle compactTitleStyle descriptionStyle compactDescriptionStyle ownerStyle ownerAvatarSize ownerSpacing ownerPlaceholderBackground ownerPlaceholderTint actionSeparatorHeight collapsedArtworkSize collapsedArtworkShape collapsedSpacing collapsedTitleStyle collapsedPlaceholderStyle Album / playlist / saved-tracks header and collapsed top-bar title.
featuredCarousel none: height compactHeight itemOffset itemAngle itemShift itemZoom cardShape dimAlpha scrimHeight scrimColor contentPadding textSpacing titleStyle subtitleStyle buttonSize buttonTint buttonBlur buttonGlassTint fadeMillis  
errorDisplay none: padding spacing iconSize iconTint titleStyle descriptionStyle detailsHeaderPadding detailsHeaderStyle detailsActionSize detailsIconSize logStyle logPadding logMaxLines retryHeight retryIconSize  
loginRequired none: padding spacing badgeSize badgeShape badgeBackground iconSize iconTint titleStyle descriptionStyle buttonHeight buttonIconSize  
screen root: topPadding bottomPadding sectionSpacing Scrolling screen content (Home); the shell's bottom overlay inset is added to bottomPadding.
section header: spacing horizontalPadding itemSpacing titleOffset titleStyle subtitleStyle Titled card rows.
appShell root: snackbarOffset  
connectBanner root: padding spacing; row: background shape padding spacing textStyle chevronTint chevronSize; dot: size color ringColor ringWidth "Connected to remote / jam" strip; dot is also used by the sidebar.
settingsRow root: titleStyle subtitleStyle  
lyricsLine root: textStyle padding spacing; immersive: textStyle shape padding spacing selected = current line, disabled = sung line (root), default = upcoming.

Every slot is resolved for all states when the theme is compiled, so a card or player only looks up a ready object while drawing: theming these components adds no per-frame work. Unknown or mistyped properties are reported on the theme's card like for Millennium components.

Surfaces (shadows and glow)

Millennium surfaces (including ones the host app builds itself, like the settings cards) draw drop shadows and inner glow/rims. tokens.surface switches them for every surface at once: { "shadows": false, "glow": false } makes everything flat. Flat themes should set it: besides matching the design, a shadow layer per element is the most expensive part of drawing Millennium, so it is also faster.

Hover and press lighting

Controls that have no lighting property of their own (sidebar, dropdown and bottom-navigation rows, tabs, the dialog buttons) draw Millennium's glossy Aqua hover/press lighting. tokens.interaction changes it for all of them at once: { "lighting": false } removes it (a flat design lets the per-state backgrounds carry hover/selection), or give your own washes: { "hover": <brush>, "press": <brush> }. Where a component has its own interactionOverlay property, that wins for that component.

Millennium draws hover/press lighting itself; a theme replaces it with the component's interactionOverlay / interactionRim / interactionTint properties, and a transparent value switches it off. Put such an overlay only in the states that should show it (a value in base is painted in every state).

Values

Kind JSON
number / dp 12
color "#RGB", "#RRGGBB", "#RRGGBBAA"
brush a color, or a gradient (below)
shape 12, "pill", "rect", [topStart, topEnd, bottomEnd, bottomStart]
padding 12, [horizontal, vertical], [start, top, end, bottom], {horizontal, vertical, start, top, end, bottom}
text style { "fontSize", "lineHeight", "fontWeight", "letterSpacing", "fontStyle", "fontFamily", "color", "textDecoration", "shadow": {"color","offsetX","offsetY","blurRadius"} }, merged onto the default
size [width, height]
motion (buttons) { "stateChangeMillis", "hoverScale", "pressedScale", "scaleDampingRatio", ... }
clear a nullable prop null

Brushes

Millennium paints buttons, tracks, thumbs, fills and panels with Brushes, so a theme can restyle them completely. Stops are a color or [color, position] (position 0..1; missing positions are spread evenly).

  • ["linear", angle, stop, stop, ...]: CSS angle (0 = up, 90 = right, 180 = down), corners get the end colors exactly.
  • ["gradient", c1, c2, ...]: a vertical linear gradient (top to bottom).
  • ["radial", cx, cy, radius, stop, ...]: centre and radius as fractions of the box (radius of the larger side).
  • ["sweep", cx, cy, stop, ...]: a conic gradient.
  • ["gel", top, bottom]: Millennium's convex Aqua gel.

Coordinates are fractions of the painted box, so one theme fits a 40dp icon button and a full-width card.

References, functions, conditions

  • "{tokens.color.accent}": the theme's effective value (what tokens resolved to). "{palette.accent}" is the built-in Millennium value, before your overrides, useful as a base (["lighten", "{palette.surface}", 0.04]). "{vars.x}" is a variable (below). "{ctx.env.dark}", "{ctx.state}" etc. are live context.
  • { "light": x, "dark": y } picks by appearance anywhere a value is allowed. Use it for every hardcoded brush color, otherwise one appearance is unreadable.
  • Functions: ["if", cond, a, b], ["match", v, {"a": 1, "default": 2}], alpha lighten darken mix add sub mul div min max clamp.
  • Conditions (a rule's when, or an if test): all, any, not, state, variant, and { "var": "ctx.x", "eq"|"ne"|"in"|"gt"|"gte"|"lt"|"lte": ... }; several keys in one object are ANDed.
  • Live context: ctx.env.dark, ctx.env.compact, ctx.player.{isPlaying,isPaused,isBuffering,hasTrack,shuffle,loop}, and ctx.item.{current,playing} on track rows.

Parameters (user settings)

parameters are the knobs a theme offers to users: they appear under Customize in the theme's details, apply live, are saved per theme (surviving theme updates) and can be reset to the defaults. A theme uses them as {params.name} anywhere a value is allowed. Keep them to the basics (accent, corner radius, density).

jsonc
"parameters": {
  "accent": { "type": "enum", "label": "Accent color", "default": "blue",
              "options": [ { "value": "blue", "label": "Blue", "color": "#2563eb" },
                           { "value": "rose", "label": "Rose", "color": "#e11d48" } ] },   // "color" draws a swatch
  "radius": { "type": "number", "label": "Corner radius", "default": 8, "min": 0, "max": 16, "step": 1 },
  "compact": { "type": "bool", "label": "Compact rows", "default": false },
  "tint":   { "type": "color", "label": "Tint", "default": "#3B82F6", "presets": ["#3B82F6", "#EF4444"] }
},
"vars": {
  "primary": { "type": "color", "value": ["match", "{params.accent}", { "blue": "#2563eb", "rose": "#e11d48" }] },
  "r": { "type": "number", "value": "{params.radius}" }
}

Types: enum (buttons, or colour swatches when options carry a color), number (slider with min/max/step), bool (switch), color (hex field plus optional presets swatches), string. Every parameter needs a plain default, a label (and optionally a description), and up to 24 are allowed; names are letters, digits and _. Values are validated by type, clamped to the range and checked against the options, so an invalid value falls back to the default. A parameter cannot be derived (use a var for that) and users can never override vars. Compute everything else from parameters with vars (see match, add, sub, max above); the bundled Modern theme (BuiltInThemes.kt) is a complete example.

Variables

vars are the theme author's private token store: { "type": "color|number|bool|string|enum", "default": ..., "min", "max", "options" }, or "value": <expression> for a derived one. Declare colors, radii and the like once, reference them as {vars.name} everywhere, change them in one place. Types are validated; cycles are rejected. A component can declare its own vars, which shadow global ones. Variables are never shown to users: to let users change something, make it a parameter and derive vars from it.

Fonts and icons

jsonc
"assets": {
  "fonts": { "Comfortaa": [ { "src": "fonts/Comfortaa-Regular.otf", "weight": 400 },
                            { "src": "fonts/Comfortaa-Bold.otf",    "weight": 700 } ] },
  "icons": {
    "IconsaxHome": { "glyph": "U+E900", "font": "MyIcons" },     // a glyph of an icon font declared above
    "IconsaxPlay": { "image": "icons/play.png", "tint": true }    // or a PNG, tinted like the stock icon
  }
},
"tokens": { "type": { "family": "Comfortaa" } }

Icon packs

assets.iconPack restyles every app icon at once, including the ones Millennium draws itself (sidebar, dock, icon buttons, checkmarks, chevrons). Keys are icon roles, the Lucide names (house, search, trash-2, chevron-down; the full list is packages/theme-tool/assets/icon-roles.json in the themes repository). Two forms:

jsonc
// 1.0: an icon font and a glyph per role
"assets": {
  "fonts": { "Icons": [ { "src": "fonts/phosphor.ttf", "weight": 400 } ] },
  "iconPack": { "font": "Icons", "icons": { "house": "U+E000", "search": "U+E001", "skip-forward": "U+E002" } }
}

// 1.1: a PNG per role, from any icon library (stroke-based ones too). Tinted like the stock icons unless "tint": false
"assets": {
  "iconPack": { "images": { "house": "icons/house.png", "search": "icons/search.png" }, "tint": true }
}

Roles a pack does not define keep the stock icon, and an entry in assets.icons wins over the pack. images is limited to 128 PNGs of at most 256 KB and 512 px. @team-spotube/theme-tool produces either form from bundled packs, any Iconify set or any folder of SVG files, so authors never write this by hand.

Single icons. assets.icons replaces individual icons by the app's icon (vector) name, with a glyph of an icon font or a PNG: { "IconsaxHome": { "glyph": "U+E900", "font": "MyIcons" }, "IconsaxPlay": { "image": "icons/play.png", "tint": true } }.

Fonts. tokens.type.family applies a font everywhere; tokens.type.styles.<role> or any textStyle.fontFamily overrides it per role. Built-in family names need no assets: default sans-serif serif monospace cursive. Fonts are .ttf/.otf; images are .png only, max 512 x 512 (no SVG).

Security model

A theme is untrusted input and is sandboxed by construction:

  • Never extracted to disk. The zip is read in memory; entry names are never used as paths ("zip slip" has no target). Android needs font files, which go to the cache under a content-hash name we choose.
  • Strict allowlist. Only theme.json (root), .ttf/.otf, .png and inert .txt/.md/LICENSE are accepted; any other entry (executables, scripts, .svg, nested archives, a second .json) rejects the whole archive. Absolute paths, .., backslashes, drive letters, control characters, hidden files, long or deep names and case-insensitive duplicates are rejected; macOS/Windows metadata (__MACOSX/, .DS_Store, Thumbs.db) is skipped.
  • Hard size limits, counted while reading (a zip bomb stops at the cap): archive 16 MB, 128 entries, 32 MB total, theme.json 512 KB, font 8 MB, PNG 256 KB, at most 16 fonts and 128 icon images.
  • Structural validation before any native decoder runs: fonts need a sane table directory (in-range offsets, required tables, valid head/maxp/loca, no SVG table); PNGs need valid chunk framing and CRCs and at most 512 px.
  • Bounded evaluation: JSON nesting and expression depth are capped, and a global step budget stops exponential {ref} graphs (the theme is then ignored with a warning, never a hang).
  • Links are validated: repository, bugs and homepage must be http(s) URLs; contact an email or http(s) URL. Never file:, javascript: or similar.
  • No capabilities: pure data. No scripting, no network, no file access. A font or icon src is only looked up inside the package.
  • Consent and integrity: an import is validated first and only installed after the user confirms a summary (author, links, license, contents, size). Installed packages are re-validated with the same reader on every launch; a corrupt file, or one stored under another theme's id, is skipped.

Residual risk, stated plainly: fonts and PNGs are ultimately decoded by native libraries (Skia/FreeType, the OS). Validation removes malformed-structure cases but cannot make a native parser bug impossible, which is why installing requires consent and the dialog says to only install themes from people you trust.