# Themes

> A shop's look as a file you can validate, preview and publish.

Source: https://storeware.ai/docs/themes

## A theme is data, not code

A Storeware theme is colours, page templates and the bands each page is made of. There is no template language, nothing in the file runs, and every value is either a name from the platform's vocabulary or a string that has passed its allow list. So there is nothing in a theme to sandbox: it can only describe.

Two open packages say what a theme may be and how it is drawn:

- [Theme schema](https://storeware.ai/docs/themes/theme-schema): The sections a page is built from, the settings each takes, the tokens a shop may restyle, and the parsers that read them.
- [Theme kit](https://storeware.ai/docs/themes/theme-kit): The stylesheet the bands are drawn with, and the shape of the data a renderer fills before it draws them.
- [Theme reference](https://storeware.ai/docs/themes/reference): Every section, setting and token, read from the schema itself.
- [Embeddable assistant](https://storeware.ai/docs/themes/widget): A shop's assistant on a site Storeware does not host, from one script tag.

## A theme file

```json title="theme.json"
{
  "storeware": "theme",
  "version": 2,
  "name": "Harbour",
  "tokens": {
    "bg": "#fbfaf7",
    "fg": "#17181a",
    "accent": "oklch(0.52 0.11 244)",
    "accentFg": "#ffffff",
    "radius": "0.5rem",
    "fontSans": "Archivo, system-ui, sans-serif"
  },
  "templates": {
    "home": [
      {
        "type": "hero",
        "heading": "Waterproofs for weather that means it",
        "ctaLabel": "Shop the anoraks",
        "ctaHref": "/collections/anoraks",
        "preset": "editorial"
      },
      { "type": "featured_collection", "heading": "The winter rail", "collection": "winter", "limit": 8 },
      {
        "type": "faq",
        "heading": "Before you order",
        "blocks": [
          {
            "type": "question",
            "question": "How should I size it?",
            "answer": "<p>Take your usual size. There is room for a jumper.</p>"
          }
        ]
      }
    ]
  }
}
```

`storeware`, `version` and `name` are the envelope. `tokens` restyles the shop, and `templates` holds one array of bands for each page type the theme sets. The [theme reference](https://storeware.ai/docs/themes/reference) lists every section, setting and token a file may use.

## The loop

> **Early access.** The CLI and the SDK are not on npm yet, so the commands below do not run for everyone. To build an app now, write to https://storeware.ai/contact.

```bash
npx @storeware/cli theme init my-theme
npx @storeware/cli theme validate
npx @storeware/cli theme push
npx @storeware/cli theme preview
npx @storeware/cli theme publish --yes
```

1. `theme init` writes `theme.json` and a README into the folder. The file is the shop as the platform ships it, so your first change is the only change in the diff.
2. `theme validate` reads the file with the platform's own parsers. No network, no shop, no account.
3. `theme push` sends it to your shop's draft. Shoppers see nothing yet.
4. `theme preview` prints a link that serves the draft.
5. `theme publish --yes` makes the draft the shop. The look it replaced is kept.

`theme pull` goes the other way and writes your shop's published look to a file, which is how you keep a copy before an afternoon of changes.

| Flag | Meaning |
| --- | --- |
| `--store <handle>` | Which shop, when the organisation has more than one. |
| `--out <file>` | Where `pull` writes. |
| `--name <name>` | A name for the theme, on `init` and `pull`. |
| `--force` | Let `pull` replace a file that already exists. |
| `--yes` | Confirm a publish, which is the only change a shopper sees. |

`validate` and `push` read `theme.json` in the folder you run them in, or the file you name after the command.