Theme Structure

主题结构

StackPanel 主题是一个目录，上传时整体打包为 ZIP。theme.json 与 theme.css 是必须项，assets/ 与 frontend/ 可选。

目录布局

my-theme/
├── theme.json             # 主题清单（必须）
├── theme.css              # CSS Token 声明（必须）
├── assets/                # 静态资源（可选）
│   ├── logo.png
│   └── font.woff2
└── frontend/              # 前端包（可选）
    ├── manifest.json      # 前端清单
    └── dist/
        └── index.js       # 编译后的模板

文件职责

theme.json

主题元数据清单，声明 ID、名称、版本等。字段定义见主题清单。

theme.css

CSS 自定义属性（变量）声明文件。只能包含 :root 和 .dark 块，且块内只能声明 --* 自定义属性。约束见 CSS Token 规范。

assets/

静态资源目录。图片、字体等文件放在此处，由内核通过 GET /themes/:id/assets/* 提供；清单的 assets.logo、assets.favicon 声明包内相对路径。单文件最大 1 MB。

frontend/

可选的前端包目录。主题需要提供自定义页面模板、Layout 或 Finder 时在此声明。写法见主题前端包和前端包介绍。

ZIP 包结构

上传的 ZIP 内部结构如下，theme.json 与 theme.css 必须位于 ZIP 根目录：

my-theme-1.0.0.zip
├── theme.json             # 必须
├── theme.css              # 必须
├── assets/                # 可选
│   └── logo.png
├── frontend/              # 可选
│   ├── manifest.json
│   └── dist/
│       └── index.js
└── signature.json         # 可选

主题 ZIP 不允许包含 .js、.ts、.mjs、.cjs、.jsx、.tsx 可执行文件，frontend/dist/*.js 除外。

数据目录

安装后，主题文件存储在 data/themes/<id>/，数据库 themes 表记录安装状态和激活状态。

data/themes/
├── default/               # 内置默认主题
│   ├── theme.json
│   ├── theme.css
│   └── frontend/
└── my-theme/              # 用户安装的主题
    ├── theme.json
    ├── theme.css
    └── frontend/