主題（Theme）開發

HypeLink 主題決定 公開品牌頁 的外觀與版面。每個主題都是一個獨立的 Next.js 專案，以 theme.publish.json 為合約與平台對接。

範本位置


hypelink-theme/
└── theme/
    └── hypelink-theme-template/     ← 官方主題範本（baseline）

所有新主題都以此範本為起點 fork / 複製。

關鍵檔案

檔案	用途
`config/theme.manifest.json`	Manifest 來源（名稱、作者、版本、縮圖、標籤）
`settings.schema.ts`	以 Zod 定義的設定欄位（`layoutMode`、`accentColor`、`backgroundColor`、`cardRadius`、`bottomBar`、`folderTabs` 等）
`types/index.ts`	合約型別：`ThemeContext`、`ThemeCapability`、`UserProfile`、`SocialLink`、`FolderItem`、`SpaceLink`、`ThemeSlots`
`app/theme-entry.tsx`	靜態預覽入口（經 `ThemePreviewLayout`）
`components/*`	主題元件（卡片、社群列、底部浮動列、資料夾分頁）
`scripts/write-theme-publish.mjs`	建置時產出 `theme.publish.json`
`mock/*`	本地開發用的假 `ThemeContext`
`next.config.mjs`	設 `output: 'export'`，輸出 `out/` SSG 靜態產物

平台側對接

合約型別：hypelink/src/lib/hypelink-theme-contract.ts（含 ThemeBottomBarSettingsV1、ThemeFolderTabsSettingsV1）
內建三款：hypelink/public/themes/builtin/{original|dark|notion}/（theme.publish.json + artifact/theme.css）
品牌套用：design_settings.themeId 指向 builtin-original / builtin-dark / builtin-notion 或外部主題的 package_id
公開頁渲染：PublicHypeLinkClient 根據 themeId 載入對應 artifact

建置指令

在 theme/hypelink-theme-template/ 下：


pnpm install
pnpm dev                     # Next.js 本地預覽（port 3000）
pnpm build                   # SSG 靜態輸出至 out/（含 theme.publish.json）
pnpm build:esm               # Vite IIFE bundle → dist/esm/（v2 runtime）
pnpm build:hypelink-public   # 以 basePath 建置，供主專案 public/ 內嵌使用
pnpm write-publish           # 產生 dist/theme.publish.json（建置流程會複製到 out/）

next.config.mjs 預設 output: 'export'，產物目錄為 out/，內含 theme.publish.json。

測試方式

1. 本地預覽


cd hypelink-theme/theme/hypelink-theme-template
pnpm install
pnpm dev

開啟 http://localhost:3000 ，mock/ 目錄的假 ThemeContext 會被注入，可立即看到版面。

2. 格式與合約對齊檢查

修改任何元件或 settings.schema.ts 後，執行 pnpm build 確認可產出 out/theme.publish.json。
確認 靜態預覽版面 與 主平台 PublicHypeLinkClient 在內建原始主題 下的側欄＋主內容視覺對齊（包含連結卡、社群圓示列、殼層與字體）。

3. 打包上傳


cd out
zip -r my-theme.zip .

然後到管理後台 /hypeadmin/theme-items：

點「上傳 Zip」，選擇 my-theme.zip
後端 POST /admin/theme-items/upload-zip 解壓 → 寫入 R2 theme/{name}/
回傳 artifactBaseUrl、previewUrl、themeData
點「預覽主題」新分頁開啟 previewUrl 或 artifactBaseUrl/index.html
「已上架」後會進入公開 GET /platform/theme-catalog，品牌可在 /dashboard/brands/.../design/themes 的「主題庫」區套用。

4. 同步規則（重要）

任何影響 主題格式或合約 的變更（theme.publish.json schema、hypelink-theme-contract、ThemeContext 型別、建置產物欄位、theme_item 讀寫欄位、驗證或後台解析邏輯），都必須在同一輪修改內 同步更新 hypelink/public/hypelink-theme-template（含 config/、scripts/write-theme-publish.mjs、examples/、README.md）。

參考文件

hypelink/theme-guideline.md — 主題開發指南
document/skill-theme-development.md — 技能書（slot 系統、載入編排）