Theme Introduction

主题介绍

StackPanel 主题系统允许自定义平台的视觉风格和页面结构。主题是配置而非代码——通过 CSS Token 声明颜色变量，通过前端包声明页面模板。

主题能做什么

• 定义 CSS Token — 通过 theme.css 声明颜色变量，覆盖默认视觉风格
• 携带前端包 — 提供自定义页面模板、Layout、Finder 等（可选）
• 声明设置 — 通过 settingsSchema 让管理员通过表单配置主题选项
• 携带静态资源 — 图片、字体等（assets/ 目录）

主题不能做什么

• ❌ 不能包含可执行后端代码
• ❌ 不能声明 HTTP 路由
• ❌ 不能包含 .js/.ts 等可执行文件（前端包的 dist/ 除外）
• ❌ CSS 中不能使用 url()、@import、选择器、表达式

主题 vs 插件

维度	主题	插件
后端代码	❌	✅
CSS Token	✅ theme.css	❌
前端包	✅ 可选	✅ 可选
路由	❌	✅
数据库表	❌	✅

三级覆盖

前端渲染遵循 主题 > 插件 > 内置 的三级覆盖优先级。主题的页面模板优先于插件和内置模板。

内置主题

default 主题是内置主题，启动时自动 seed 到 data/themes/default/。它不可删除，且保证至少有一个可用主题。

default 主题包含完整的前端包，示范了 /about、/blog、/blog/:slug 等页面路由和主题 404。

主题激活与预览

• 激活：同一时刻只有一个主题 active=true。激活新主题时自动取消旧主题
• 预览：管理员可以无需激活地预览任意主题，预览状态存储在 settings 表，不影响线上

详见 打包与上传。

接下来

• 主题结构 — 目录布局
• 主题清单 — theme.json 字段
• CSS Token 规范 — theme.css 约束
• 主题设置 — 设置表单
• 主题前端包 — 页面模板
• 打包与上传 — ZIP 打包、签名、安装