Historical V1 protocol (legacy compatibility)

These are historical V1 fields and limits for inspecting and migrating old packages. Use V2 for new works. Changing only the schema number is invalid.

Package structure

manifest.json
LICENSE.txt
README.md
assets/
  preview.png
  background.jpg
  background-dark.jpg
  icons/
    home.png
    home-dark.png
    home-selected.png
    home-selected-dark.png

This illustrates a partial package; a complete theme includes the other icons too. Optional text files must be UTF-8. Images belong under assets/. Safe ASCII path segments use letters, digits, dots, underscores and hyphens, beginning with a letter or digit.

Minimal color theme

This manifest is valid for a deliberately color-only theme. Supply a real assets/preview.png too.

{
  "schemaVersion": 1,
  "id": "quiet-garden",
  "version": 1,
  "name": "Quiet Garden",
  "description": "A quiet garden palette",
  "author": "Your Name",
  "license": "CC-BY-4.0",
  "preview": "assets/preview.png",
  "palette": {
    "primary": "#426B52",
    "secondary": "#A16B4F",
    "tertiary": "#617788"
  }
}

The sample license grants no rights to artwork you do not own. Declare your actual author and license.

Manifest fields

Field	Requirement
schemaVersion	Integer 1
id	At most 48 characters; lowercase letter first, lowercase letters/digits separated by single hyphens; no built-in IDs
version	Positive integer; increase for updates
name / author	Required, at most 60 UTF-16 units each
description	Optional or empty, at most 300 UTF-16 units
license	Required, at most 120 UTF-16 units
preview	Exactly assets/preview.png
palette	Optional; requires all three primary, secondary, tertiary colors in #RRGGBB form
palette.name	Optional companion palette name, up to 60 UTF-16 units; defaults to the manifest name
palette.topBar	Optional colors for shared horizontal selector buttons in library, discovery (including its second row) and search; provide at least one field below
iconScale	Optional number from 0.75 to 1.2; creator-recommended artwork size. Omitted means 1.0 (100%). Buttons, labels and backgrounds keep their size.
icons	Optional; only the 80 supported keys
artwork	Optional; only pageBackground and navigation

No leading/trailing whitespace or control characters in metadata. Some characters, including emoji, use two UTF-16 units. original, tidal, botanical, and celestial are reserved. Supply at least colors, icons or artwork. Unknown fields are rejected.

Use protocol camelCase and stable action semantics, such as topBar, selectedBackground, darkAsset and readAloud. Library, discovery and search share topBar; do not invent page-specific aliases. New features stay optional. Existing works add only requested fields, need not complete later-added slots, and do not raise schemaVersion for optional additions.

Omit optional features as needed. Missing icon slots use the app's original system icons; missing selected uses normal, and missing darkAsset uses that state's asset. Missing page artwork keeps the existing gradient/background; missing navigation artwork adds no decoration. Without palette, applying artwork retains the user's current colors; palette.name defaults to the work's name. Missing topBar or color roles retain existing ColorScheme/material defaults, with explicit control overrides taking priority. iconScale defaults to 1.0 unless a saved user override applies. Identity, version, author, license, preview and at least one of palette/icons/artwork remain required; declaring palette requires all three base colors. Valid omissions differ from broken declarations: missing or corrupt referenced files must fail validation.

Normal and selected horizontal button colors

Add topBar inside palette to style the shared horizontal selectors for library groups, discovery categories and sources, and search filters:

"topBar": {
  "background": "#E6EDF2",
  "foreground": "#234A73",
  "selectedBackground": "#234A73",
  "selectedForeground": "#FFFFFF"
}

background / foreground set the normal button fill and text/icon color; selectedBackground / selectedForeground set the selected state. All four fields are optional, but the object must contain at least one. Colors must use strict #RRGGBB form. Omitted fields retain the app's default calculation; empty objects, unknown fields and explicit null are invalid. These colors apply to the buttons themselves. The app still owns the page app bar, layout and glass/solid preference. Check text and icon contrast in both materials and appearances.

Older clients strictly reject topBar; omit it for compatibility. V1 uses the same overrides in light and dark appearances. Public templates and submissions remain V1.

Icons and artwork

Include palette only when requested; declaring it still requires all three base colors. On import, its companion appears in the color-theme list with the artwork's name by default. For a distinct name, add "name": "Garden Mist" inside palette, keeping all three colors. Choosing the artwork selects its companion; users can then choose another palette independently. Choosing the artwork again restores its companion. Older partial packages without colors keep the current palette. Clients with the older strict palette whitelist do not accept palette.name; custom names require this or a newer app. Same-name packages need no new field.

Merge these fields into your manifest. This fragment demonstrates one icon, not a complete theme:

{
  "icons": {
    "home": {
      "normal": {
        "asset": "assets/icons/home.png",
        "darkAsset": "assets/icons/home-dark.png"
      },
      "selected": {
        "asset": "assets/icons/home-selected.png",
        "darkAsset": "assets/icons/home-selected-dark.png"
      }
    }
  },
  "artwork": {
    "pageBackground": {
      "asset": "assets/background.jpg",
      "darkAsset": "assets/background-dark.jpg"
    },
    "navigation": {
      "asset": "assets/background.jpg",
      "darkAsset": "assets/background-dark.jpg"
    }
  }
}

normal is required for each declared icon; selected and darkAsset are optional. Resolve selected first (or normal if absent), then that state's darkAsset (or its own asset). A missing whole slot uses the app's original icon. A selected state without darkAsset does not use the normal state's dark image.

Image and ZIP limits

Item	Limit or requirement
Compressed / extracted ZIP	10 MiB / 20 MiB
Entries	512, including directories
Manifest	64 KiB
Referenced images	24 million total decoded pixels; the same path counts once
Icons	Square, at most 512×512, with alpha channel
Background	Each dimension at most 2048
Preview	PNG, each dimension at most 1600
Formats	Static PNG, JPEG, WebP; bytes must match the extension

No SVG, GIF, fonts, scripts, remote URLs, encryption, symlinks, duplicate/case-conflicting paths, traversal or unreferenced images. Export SVG sources to transparent PNG or WebP. Keep optional text filenames exactly README.md and LICENSE.txt.

Machine-readable reference

Download the generated V1 schema and slot inventory. The public Skill and reference are generated from the actual server model. Use the single official template. Protocol schemaVersion and theme release version are different values.

Icon size and local drafts

Set "iconScale": 0.9 at the manifest root to recommend 90% size. This is an absolute ratio of the app’s standard artwork size, not a multiplier on the user’s setting. Users can adjust 75%–120% under Appearance, remembered per theme. Restore creator size clears the user override. Color-only packages without icons are unaffected. Older clients reject this new optional field; omit it for compatibility and use the standard size.

Keep the same theme id from local testing through marketplace publication. Increase version for a new official release. The updated app groups saved packages into one My themes card per ID. Different content with the same version can coexist as local drafts and marketplace releases; identical packages are reused. Installing a release preserves different drafts. Matching names with different IDs are not merged. Provenance is verified and recorded by the client, never supplied in the manifest.