Archive
Expected ZIP structure
The archive should contain theme.json at its root and, when needed, style.css, README.md, LICENSE plus the slots/, parts/ and pages/ directories. A single top-level directory is tolerated and removed automatically during installation.
- Maximum archive size: 2 MB.
- Maximum extracted size: 8 MB.
- File count is limited.
- Directory depth is limited.
- No hidden files, no path traversal and no directories outside the allowlist.
Distribution
Installation modes to keep in mind
A theme can be installed from disk, from a ZIP archive or from an HTTPS URL. In all cases, an advanced theme must be treated as PHP code that executes on the server.
Do not ship an advanced theme as if it were only a visual resource. It is an application extension and should be reviewed with the same level of care as a core patch.
Diagnostics
Quick debugging checklist
- The theme does not appear: check
theme.json,id, type and required variables. - The CSS does not change: check the active theme and the
[data-theme="id"]scope. - An override is ignored: check the exact slot or part name and its location.
- A custom page does not load: check that the core really calls the targeted extension point.
- The rendering breaks on mobile: check shell width, sidebar, topbar and oversized tables.
Before shipping
Final checklist
- Stable, short
id. - Valid
theme.jsonconsistent with the directory name. - Required variables present.
style.cssscoped with[data-theme="id"].- Dynamic output escaped.
- No unnecessary direct access to internal classes.
- Desktop and mobile visual check completed.
- Dashboard verification if
pages/dashboard.phpis shipped.