Current theme protocol V4

V4 is the current protocol. New works use independently optional app artwork, launch screens, palettes, reader themes and fonts. Legacy V1/V2/V3 packages remain readable. Import saves a copy; application is explicit. Current manifest · Historical V1.

Shared module catalogue

V1, V2, V3 and V4 share the same groups, names and order. A protocol version expands supported modules; it does not define another catalogue. Rows remain visible with provided, author omitted or protocol unsupported status. Only provided modules can be selected.

Group	Module	Key	Minimum protocol
App appearance	App colors	palette	V1
App appearance	Interface icons	icons	V1
App appearance	Page background	pageBackground	V1
App appearance	Navigation decoration	navigation	V1
App appearance	Launch screen	launchScreen	V4
Reading appearance	Reading paper	readerPaper	V2
Reading appearance	Paragraph review decoration	paragraphReview	V2
Reading appearance	Loading animation	openingIndicator	V2
Reading appearance	Information bar styling	informationBars	V2
Reading appearance	Comment cards	commentCard	V3
Fonts	Fonts	fonts	V2

Comment cards style both chapter discussions (本章说) and god comments (神评论). Card background, border, radius, padding and badges belong here. Reading paper and paragraph review button decoration are separate modules; subset downloads never implicitly include each other. This styles existing comments and does not enable comment content. Fonts are one selectable module with ui/body/header/footer roles. skin, palette, reader and fonts are four storage containers, not another public module grouping; one container can carry several independently selectable modules.

The machine protocol publishes the same catalogue under moduleCatalog. catalogVersion: 3 adds the V4 launch-screen module. New packages use schemaVersion: 4; the author's version is a separate monotonic release number.

Current V4 suite manifest

V4 uses integer schemaVersion: 4 and format: "origo.theme-suite". Its components may declare skin, palette, reader and fonts. An omitted component preserves the recipient's choice when applying; an explicit system choice restores that built-in behavior. Portrait skin.artwork.launchScreen and optional launchScreenLandscape each have required asset and optional darkAsset; all files are static PNG/WebP, at most 2 MiB and 2048 pixels on the longest edge. Without landscape artwork the App contains and centers the portrait image. It exits as soon as home is ready, with no forced dwell time. This valid example needs no preview image or extra files:

{
  "schemaVersion": 4,
  "format": "origo.theme-suite",
  "id": "my-shared-theme",
  "version": 1,
  "name": "My shared theme",
  "author": "Your Name",
  "license": "Your actual license",
  "components": {
    "skin": {
      "base": "original"
    },
    "palette": {
      "light": {
        "seed": "#456789"
      },
      "dark": {
        "seed": "#345678"
      }
    },
    "reader": {
      "light": {
        "background": "#FFFDF7",
        "text": "#202020",
        "controlBar": "#FFFDF7"
      }
    },
    "fonts": {
      "resources": [],
      "roles": {
        "ui": {
          "builtin": "system"
        },
        "body": {
          "builtin": "system"
        },
        "header": {
          "builtin": "system"
        },
        "footer": {
          "builtin": "system"
        }
      }
    }
  }
}

Palettes and fonts

Each palette appearance chooses either one seed or all three of primary, secondary and tertiary, never both forms. Either form may include topBar. Pure system fonts use resources: []; a role may target { "builtin": "system" }. Custom font roles reference resource IDs. Each resource declares family, asset, license and licenseAsset; include both the font and license text in the ZIP.

Reader resources and delivery

The V3 reader format supports light/dark paper, background variants, paragraph-review artwork, information bar styling, comment cards and bounded WebP opening animations. Format support does not mean Share current appearance captures every optional setting. See use and sharing for its actual capture scope. Complete share packages must not contain component-delivery distribution metadata.

Information bar styling scope

reader.informationBars may provide style, contentPreset, or both. style.header and style.footer can set a font role, font size (8–24), weight (100–900 in steps of 100), semantic color (text, muted or accent), opacity (0.2–1), and density (compact, regular or relaxed). Per-information-type overrides may set font role, weight, color and opacity. Font roles reference components.fonts.roles; subset downloads include only fonts and licenses actually referenced by the selection.

contentPreset is limited to header and footer, at most two rows per bar, and at most three items in each row's left, center and right groups. Supported types are time, battery, book title, chapter title, chapter pages, remaining pages, chapter count, remaining chapters, chapter progress, book progress, session reading time, today's reading time and total book reading time. Formats are also bounded: time accepts auto/12h/24h, battery accepts auto/icon/percent/both, and progress accepts auto/percent/bar/both. It is not an arbitrary text, script or remote-data surface.

Information bar styling is off by default in the application chooser. It changes only what the user explicitly selects. Undeclared sides remain unchanged, and device placement and margins stay local. It does not control the system status bar, body typography, progress data sources or live-statistics computation.

The downloadable creator tool contains references/protocol.json, generated from the actual models, and references/suites.md for fields and resource constraints. Its checker dispatches to the matching server validator and accepts original skin, a single seed and empty system-font resources without fabricated assets. V4 local limits are 128 MiB compressed and 192 MiB expanded, with additional role budgets. Temporary sharing limits both submitted and normalized ZIPs to 32 MiB. For V2/V3/V4, --complete audits the presence of four storage containers; for V1 it still audits full artwork coverage. Default checks allow valid partial packages.

Download the current generated contract. Authors upload one complete ZIP. Optional media.images uses image IDs and packaged paths; media.cover references an image ID. Subset downloads exclude promotional images while retaining selected resources and licenses. V1/V2/V3 remain readable; new works use V4.

Version labels

schemaVersion: 4 identifies theme package protocol V4. catalogVersion: 3 identifies only the shared catalogue's naming and description revision. versionName: "4.0" is the displayed author version; values such as 1.1, 2.2 and 3.0 are also valid. version remains the monotonic integer delivery identity used for exact downloads and updates. Without versionName, integer version 1 is displayed as 1.0.

Optional V3 reader.commentCard styles light and dark cards for chapter discussions (本章说) and god comments (神评论), including background, border, radius, padding and badges. Body text follows the reader text color. Users select Comment cards independently, and subset downloads project it independently from Reading paper.