Theme format
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)
How a theme styles the app
Two modes in one file, both optional:
- Global:
tokens.interactionandtokens.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>), anddefaults(props applied to every component that has them, e.g.{ "shape": 12 }). - Per component:
components.<name>withbase,states,variants,rules. Component names are Millennium's component themes without theThemesuffix: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.
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
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 (whattokensresolved 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 aniftest):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}, andctx.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).
"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
"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:
// 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,.pngand inert.txt/.md/LICENSEare 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.json512 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;contactan email orhttp(s)URL. Neverfile:,javascript:or similar. - No capabilities: pure data. No scripting, no network, no file access. A font or icon
srcis 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.