歷史協議 V1（舊包兼容）

以下為歷史 V1 字段與限制，僅供讀取舊包和迁移，不是當前創作规范。新作品請使用 V2。舊包不能僅把版本号 1 改成 2。

包的目錄結構

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

這是一份部分主題的目錄示意，完整包還需要其他圖示。說明檔案可選且須使用 UTF-8；圖片只能放在 assets/ 下。安全檔名只使用 ASCII 字母、數字、點、下劃線和連字元，每一段以字母或數字開頭。

最小的配色主題

下面是可透過清單校驗的配色主題示例；還須提供真實的 assets/preview.png 圖片才能打包。它有意不替換圖示或背景。

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

授權示例不自動賦予素材許可；換成你實際擁有的許可與署名。

清單欄位

欄位	要求
`schemaVersion`	固定為整數 `1`
`id`	最長 48 字元，小寫字母開頭，僅小寫字母、數字、單個分隔連字元；不能用內建 ID
`version`	正整數，更新同一主題時遞增
`name` / `author`	必填，各最多 60 個 UTF-16 單位
`description`	可省略或為空，最多 300 個 UTF-16 單位
`license`	必填，最多 120 個 UTF-16 單位
`preview`	固定路徑 `assets/preview.png`
`palette`	可選，提供時必須同時有 `primary`、`secondary`、`tertiary`；顏色為 `#RRGGBB`
`palette.name`	可選，配套配色的名稱，最多 60 個 UTF-16 單位；省略時使用主題 `name`
`palette.topBar`	可選，為書庫、發現（含第二行）及搜尋頁的共用橫排選擇按鈕獨立配色；至少提供下述一項
`iconScale`	可選數值 `0.75`～`1.2`，作者建議的貼圖大小；省略為 `1.0`（100%），不改變按鈕、文字或背景
`icons`	可選，只接受素材清單中的 80 個鍵
`artwork`	可選，只接受 `pageBackground` 與 `navigation`

文字不允許首尾空白、換行或控制字元；emoji 等字元可能佔兩個 UTF-16 單位。內建 ID original、tidal、botanical、celestial 保留使用。主題必須至少提供配色、圖示或背景之一；不接受未知欄位。

命名沿用協議的 camelCase 及穩定動作語義，例如 topBar、selectedBackground、darkAsset、readAloud。書庫、發現及搜尋共用 topBar，不另造頁面專屬別名。新增能力保持可選；既有作品只補本次所需欄位，無須補齊後續新增槽位，也不因加入可選欄位提高 schemaVersion。

可選項按需省略：缺圖示槽使用 App 原系統圖示；缺 selected 使用 normal，缺 darkAsset 使用該狀態的 asset。頁面底圖缺省保留原漸層／底色；導覽裝飾缺省不疊圖。沒有 palette 則套用素材時保留使用者目前配色；palette.name 缺省使用作品名。topBar 整塊或單個角色缺省使用現有 ColorScheme／材質顏色規則，呼叫方明確覆蓋優先。iconScale 缺省為 1.0，已儲存的使用者覆蓋優先。身分、版本、作者、授權、預覽及至少一種配色／圖示／背景內容仍必需；宣告了 palette 時三個基礎色必須齊全。合法省略與錯誤宣告不同：引用不存在或損壞的檔案仍須報錯，不能當成可選項忽略。

橫排按鈕的一般和選中配色

在 palette 內加入 topBar，即可為書庫分組、發現分類與來源、搜尋篩選等共用橫排選擇按鈕設定顏色：

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

background / foreground 是一般狀態的底色及文字／圖示色；selectedBackground / selectedForeground 是選中狀態的底色及文字／圖示色。四項均可省略，但物件至少有一項，顏色嚴格使用 #RRGGBB。未提供欄位保留 App 的預設計算，不接受空物件、未知欄位或 null。這控制按鈕本身；頁面頂欄、版面及玻璃／實底偏好仍由 App 管理。請檢查兩種材質、明暗外觀的文字與圖示對比度。

舊版 App 會嚴格拒絕 topBar；需要相容舊版時省略。V1 的同一組顏色用於明暗外觀；公開範本與投稿仍為 V1。

圖示與背景的寫法

配色可按需提供；宣告 palette 時仍需三個基礎色。配套配色預設使用主題 name，匯入後會保留在配色清單；可在 palette 中加入 "name": "靜岸暮色"，自訂最多 60 個 UTF-16 單位的配色名稱，並保留 primary、secondary、tertiary。選擇貼圖主題時預設選中它的配套配色，之後仍可手動選擇其他配色；再次選擇貼圖時恢復配套配色。沒有配色的舊部分包保留目前顏色。舊版 App 尚不接受 palette.name，自訂名稱需要此次或更新的 App；預設同名不需新增欄位。

把下面兩個欄位合入你的清單；這個片段只展示一個圖示，不是完整主題。

{
  "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 才有效；selected 與 darkAsset 都是可選的。精確回退順序為：先選擇 selected（缺失則 normal），再選擇這個狀態的 darkAsset（缺失則該狀態的 asset）。缺少整個槽位則顯示 App 原有圖示。注意：選中狀態缺深色圖，不會轉去用普通狀態的深色圖。

圖片與 ZIP 限制

專案	上限或要求
ZIP 壓縮大小 / 展開大小	10 MiB / 20 MiB
ZIP 條目	512 個，目錄也計數
`manifest.json`	64 KiB
全部被引用圖片	總計 2400 萬解碼畫素，共用同一路徑只計算一次
圖示	正方形，最大 512×512，必須包含透明通道
背景	每邊最大 2048
預覽	PNG，每邊最大 1600
圖片格式	靜態 PNG、JPEG、WebP，真實格式必須匹配副檔名

不允許 SVG、GIF、字型、指令碼、遠端 URL、加密 ZIP、符號連結、重複或大小寫衝突路徑、路徑穿越和未被引用的圖片。SVG 原稿需要先匯出透明 PNG 或 WebP。說明檔案不要另造未支援的檔名。

機器可讀參考

下載 V1 欄位 Schema 與槽位表。它與公開 Skill 從服務端實際校驗模型生成；完整模板始終是這一份。schemaVersion 是協議，version 是主題的升級序號，兩者不可混用。

圖示大小與本機測試

可在清單根部寫 "iconScale": 0.9 建議 90% 大小。它是相對 App 預設貼圖尺寸的絕對比例，不與使用者設定相乘。使用者可在「外觀設定」調整 75%～120%，按主題分別記憶；「恢復作者建議」清除使用者覆寫值。只有配色、沒有圖示的套件不受縮放影響。舊版 App 嚴格拒絕這個新可選欄位；需相容舊 App 時省略，使用預設大小。

從本機測試到市集上架始終沿用同一主題 id，發佈新正式版本時遞增 version。新版 App 的「我的主題」按 ID 顯示一張卡片，版本頁可保留同版本的不同內容：本機測試稿與市集正式版分別標示。完全相同的套件重用；安裝正式版不會覆蓋不同的測試稿。同名但 ID 不同不會自動合併。安裝來源由客戶端驗證及收據記錄，不能在清單中偽造。