主题包是一个标准 ZIP，只需把扩展名改成 .omnitheme。最小包只需要根目录的 manifest.json 和四个亮色种子色，不带图片也可以导入。
我的主题.omnitheme
├── manifest.json 必需
├── preview.png 主题列表预览图
├── background/
│ ├── app.jpg 全局背景
│ ├── atmosphere.png 书架氛围插画
│ ├── read-aloud.jpg 听书页背景
│ ├── audiobook.jpg 有声书页背景
│ └── launch.jpg 开屏页背景
├── tab/ Tab 图标与书架媒体光标
├── player/ 播放组件图标
├── card/accent.png 首页状态卡片装饰
└── comment/ 神评、本章说与数字气泡顶层必填字段是 formatVersion、id、name、version 和 palette.light。id 使用反向域名格式，版本号使用语义化版本；未知字段会被忽略，方便以后扩展。
{
"formatVersion": 1,
"id": "com.example.warm-sun",
"name": "暖日拾光·自制版",
"author": "某某",
"version": "1.0.0",
"description": "暖红奶黄，适合夜读的柔和配色",
"minAppVersion": "1.4.0",
"palette": {
"light": {
"backgroundPrimary": "#FFFCF4",
"surfacePrimary": "#FFFEFA",
"brandAccent": "#BF3F36",
"textPrimary": "#352A25"
},
"dark": {
"backgroundPrimary": "#191614",
"surfacePrimary": "#27211B",
"brandAccent": "#FF8D78",
"textPrimary": "#FFF8E9"
}
}
}palette.light 必填，palette.dark 可选。每个模式只需要四个种子色，其他 token 会按规范推导；颜色只接受 #RRGGBB 或 #RRGGBBAA。
| Token | 用途 | 要求 |
|---|---|---|
backgroundPrimary | 页面底色 | 必填 |
surfacePrimary | 列表、面板表面 | 必填 |
brandAccent | 按钮、图标、选中态的强调色 | 必填 |
textPrimary | 主文字 | 必填 |
backgroundSecondary / surfaceSecondary | 背景和卡片渐变的第二段 | 可选 |
cardBackground / cardHover | 卡片底色与按下态 | 可选 |
brandText / textSecondary | 小字号品牌文字与次要文字，自动校正对比度 | 可选 |
borderSubtle / borderStrong | 细分隔线与强分隔线 | 可选 |
success / warning / error | 状态色 | 可选 |
图片不需要写进 manifest，导入器会按固定路径查找。任何图片都可以增加 -dark 变体；没有暗色图时按对应槽位的回退规则处理。
| 路径 | 用途 | 建议像素 | 格式 |
|---|---|---|---|
background/app | 全局背景 | 1290 × 2796 | PNG / JPG / JPEG / HEIC |
background/atmosphere | 书架氛围插画 | 1024 × 1536 | 透明 PNG |
tab/<name> | 书架、漫画、有声书等 Tab 图标 | 75 × 75 | 透明 PNG |
player/<name> | 播放键、定时、语速、目录等 | 256 × 256 | 透明 PNG |
card/accent | 首页“阅读中 / 正在收听”卡片装饰 | 288 × 144 | 透明 PNG |
comment/god / chapter | 神评与本章说角标 | 按样式选择 | 透明 PNG |
preview.png | 主题列表与导入确认页预览 | 750 × 1334 | 透明 PNG |
Tab 图标建议成套提供；播放器图标支持页面专属覆盖，查找顺序为 player/页面/名称 → player/名称 → SF Symbol。
压缩包不超过 30 MB，解压后不超过 80 MB
文件数量不超过 80；单张图片宽高不超过 4096，总像素不超过 1600 万
路径不能包含绝对路径、反斜杠、.、..、符号链接、加密条目或 ZIP64
manifest.json 必须是合法 JSON，大小不超过 64 KB
四个种子色必须存在且使用 #RRGGBB 或 #RRGGBBAA
致命错误会拒绝导入并指出文件或字段路径；可选图片、Tab 图标不成套、未知文件和颜色自动校正会作为警告展示，允许继续导入。
App 会把原始 manifest、推导并校正后的色板和降采样图片保存到主题目录，不保留原始压缩包，避免备份体积翻倍。同一个 id 只有更高版本会直接覆盖。
Application Support/Themes/<id>/manifest.json · palette.json · images/