# Theme packages

Two different things can be exported, and confusing them causes real accidents.

| Export | Contains | Installed by |
|---|---|---|
| **Theme profile (JSON)** | Tokens and settings only | Import in the admin panel |
| **Theme directory (PHP/CSS)** | Templates, stylesheets, assets | Filesystem upload |

## Theme profiles

**Appearance → Profiles** manages saved appearance configurations.

| Action | Behaviour |
|---|---|
| Create | Saves the current tokens as a named profile |
| Apply | Snapshots a version first, then activates the profile |
| Duplicate | Copies a profile so you can experiment on the copy |
| Preview | Renders the site with the profile for your admin session only; the public default does not change |
| Export | Downloads the profile as JSON |
| Import | Reads a JSON profile |
| Restore | Rolls back to a stored version |

The active or default profile cannot be deleted. If a fresh install has no profile yet, the current live tokens are adopted as the first profile so the panel always shows a current appearance to work from.

### Import safety

Profile JSON carries **tokens and settings only**. Import never accepts PHP, templates, or executable assets, and the payload is size- and format-constrained. Values are validated exactly as if they had been typed into the panel — including the contrast rule — so an imported palette cannot make the site unreadable.

## Version history

Applying a profile creates a version snapshot **before** the change. Each version records its number, name, tokens and creation time, and can be restored. This is what makes appearance experiments safe: the previous look is always one click away.

## Theme directories

Theme code ships over the filesystem. Copy the directory under `public/themes/` and select the theme in the panel.

There is deliberately no browser upload for theme PHP. See [Security](../03-configuration/SECURITY.md) for the reasoning.

## Moving appearance between sites

1. Export the profile JSON from the source site.
2. Copy the theme directory over the filesystem, if the source used a custom theme.
3. Import the JSON on the target and apply it.

Tokens travel as data; code travels as files. Keep it that way.
