Themes

Theme package format: theme.json, design tokens, screenshots, build and limits.

A theme changes how a store looks: colours, fonts and spacing, plus the preview card and screenshots shown in the catalogue. It contains data only. The store keeps its own storefront templates and renders them with the theme’s design tokens, so a theme never carries PHP, Blade, HTML, CSS, JavaScript, SVG or fonts — the checks reject such a package even when it is signed.

my-theme/
  theme.json              # the manifest (fields below)
  README.md               # optional: README.md, LICENSE, LICENSE.md, LICENSE.txt, CHANGELOG.md
  screenshots/home.png    # optional: up to 8 PNG, JPEG or WebP images listed in theme.json

theme.json may contain only these fields:

schema_version — 1; package_type — "theme".
package_code — 2–120 characters a–z, 0–9, “.”, “_”, “-”, starting with a letter, e.g. acme.theme.aurora.
version — the theme SemVer; name and publisher — up to 180 characters; description — optional, up to 500 characters.
laracart_compatibility — compatible Tobto.shop versions written as ^MAJOR.MINOR, e.g. ^1.0; must equal the “Compatibility” field of the submission.
default_tokens — exactly three groups: colors, typography, spacing; each has 1–32 keys like primary or accent.
colors — #rrggbb or var(--name), primary is required; typography — font family names (letters, digits, spaces, “,”, “.”, “_”, “-”), body is required; spacing — a number with px, rem or em, md is required.
preview — optional sketch for the catalogue card: header, logo, nav, page, hero as #rrggbb and columns from 1 to 4.
screenshots — optional list of up to 8 paths screenshots/<name>.png|jpg|jpeg|webp; it must match the files in the archive exactly.

Build and sign with the theme packager (PHP 8.2+ with sodium and zlib), using the same key pair as for other packages:

php scripts/package_theme.php build ./my-theme dist ./private-key.pem my-key-id
php scripts/package_theme.php verify dist/<code>-<version>.zip dist/<code>-<version>.manifest.json ./public-key.pem

A working example is the reference theme in laracart-extensions/themes/skeleton.
The packager builds a deterministic ZIP and refuses any file outside the list above instead of skipping it.
Output: <code>-<version>.zip, .checksum and .manifest.json — theme.json plus package_checksum and signature, the publication JSON you attach to the submission.
ZIP up to 16 MB, up to 64 files, each up to 4 MB; theme.json up to 256 KB; screenshots are checked to be real images.

After purchase the store downloads the theme with its licence (for now with php artisan themes:install <code> <version> on the store server), checks the signature and the archive again and adds it to the store’s themes as not active. The owner then previews it, adjusts the tokens and activates it.

Developer documentation