Choosing between variable themes and advanced themes
The engine supports two theme formats. The first one is limited to a JSON manifest with CSS variables. The second adds a full directory, a style.css file and PHP overrides for the layout or some pages.
| Format | Contents | When to choose it |
|---|---|---|
| variables | A JSON file with theme.json or <id>.json depending on the installation mode. | To change the palette, fonts, radius values and shadows without touching markup. |
| advanced | A directory with theme.json, style.css, slots/, parts/ and pages/. | To reorganize the layout, replace rendered areas or customize the dashboard. |
Start simple, add complexity only when needed
- Start by locking the palette and typography with a
variablestheme. - Move to an
advancedtheme only if the layout really needs to change. - Override a targeted part before copying a full slot.
- Use page overrides only when the core already exposes an extension point for that screen.
dashboard page override is actually wired by the core. Other page names are reserved by the engine but are not all called yet.Where to look in the project
The main shell is rendered by public/layout_top.php and public/layout_bottom.php. The theme engine lives in src/ThemeManager.php, src/ThemeRenderer.php, src/ThemeTemplateTags.php and src/ThemePackage.php.
For concrete examples, start from src/themes_builtin/dark.json, src/themes_builtin/light.json and especially src/themes_builtin/horizon/, which shows a complete advanced theme.
What this documentation helps you ship
The goal is not only to describe the format, but to give you a full working frame: directory structure, valid variables, supported slots, template tags to prefer, ZIP security constraints, debug checks and a delivery checklist.