# Sneferu: build themes for Hekana stores

> Sneferu is the theme language and SDK for Hekana stores: HTML with hk-* tags and a small template syntax. The CLI checks a theme, previews it with sample data and compiles it into one artifact a store can run safely.

Source: https://hekana.dev/themes

## What a section looks like

This is the hero section every new theme starts with: a dark band with a large
heading, a sentence and a button. A section is one file: the markup first, then
an `<hk-schema>` that lists what the merchant can edit.

```html title="sections/hero.snf"
<hk-section background="theme:secondary" padding-y="96" mobile-padding-y="48">
  <hk-stack gap="16" align="start">
    <hk-heading text="{{ section.settings.title }}" level="h1" size="56" mobile-size="32" color="#FFFFFF" />
    <hk-text text="{{ section.settings.subtitle }}" size="20" color="#E5E7EB" />
    {% for block in section.blocks %}
      <hk-block of="{{ block }}" />
    {% endfor %}
    <hk-button label="{{ t('shop_now') }}" href="/products" />
  </hk-stack>
</hk-section>
<hk-schema>
  {
    "name": "Hero",
    "version": 1,
    "blocks": {
      "allowed": ["chip"],
      "max": 4
    },
    "settings": {
      "title": {
        "type": "text",
        "label": "Title",
        "default": "Hello",
        "maxLength": 80
      },
      "subtitle": {
        "type": "textarea",
        "label": "Subtitle",
        "default": "",
        "maxLength": 200
      }
    }
  }
</hk-schema>
```

![A dark band with a large white heading, a line of text and an orange button](https://hekana.dev/developers/examples/starter-hero@2x.webp "The starter hero in the dev preview, 1080 px wide.")

#### What each line does

1. **Line 1** `<hk-section>` is the band. `background="theme:secondary"` paints
   it with a colour from the theme's `theme.json`. `padding-y="96"` is the space
   above and below the content; on phones it is 48.
2. **Line 2** `<hk-stack>` puts everything inside it in a column, 16 px apart.
3. **Line 3** `<hk-heading>` is the big title. `{{ section.settings.title }}`
   prints the `title` setting: what the merchant typed, or the default.
4. **Line 4** `<hk-text>` prints the `subtitle` setting.
5. **Lines 5-7** draws any small labels the merchant added inside the hero (blocks).
   A new hero has none.
6. **Line 8** `<hk-button>` is a link drawn as a button. `t('shop_now')` takes
   its words from the theme's locale file.
7. **Lines 11-34** `<hk-schema>` names the section and declares its settings:
   `title` and `subtitle`, each with a label and a default.

More complete sections, each with a picture: the [Cookbook](https://hekana.dev/guide/cookbook).

## Quick start

Three commands take you from an empty folder to a theme on a store. You need
Node.js 20 or newer; `npx` downloads the CLI the first time.

### 1. Create a theme

```bash
npx sneferu init my-theme
```

Copies the starter theme into a new folder, `my-theme`, and names the theme
after the folder. `npm create sneferu my-theme` does the same.

### 2. Preview it

```bash
npx sneferu dev ./my-theme
```

![The starter theme in the dev preview: the hero, then the first sample product cards](https://hekana.dev/developers/examples/starter-dev@2x.webp "The top of the page straight after init, 1080 px wide.")

Open `http://127.0.0.1:4100`. The preview fills the theme with sample products
and reloads every time you save a file.

### 3. Push a version

```bash
npx sneferu push ./my-theme --package my-theme
```

Checks the theme, compiles it and uploads it to Hekana as a new version. Sign in
first with `npx sneferu login`; any Hekana account can
[get an API key](https://hekana.dev/guide/get-an-api-key). Add `--dev-store` to publish the
version on your free dev store. See [Push and publish](https://hekana.dev/guide/publishing).