Theme Structure

主题结构

一个 StackPanel 主题的目录结构如下：

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 内部结构：

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/