This is the reference for the contents of a theme package. For a walkthrough, start with [Creating a theme](/themes/creating-a-theme). Every property name below is also in the [JSON Schema](/schemas/theme/1.json), which gives your editor autocomplete.

## Schema version
`theme.json` has a JSON Schema ([JSON Schema](/schemas/theme/1.json), 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](/themes/schema-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](https://docs.spotube.cc/themes/schema-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 `background`s 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 `Brush`es, 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.
