# Storelib Developer Hub: Storelib Builder Framework, complete reference

> Source: https://storelib.com/developers. Map of pages: https://storelib.com/llms.txt.

---
<!-- https://storelib.com/developers -->

# Storelib Developer Hub

Storelib sites are built from sections, and every section is written in one language: the **Storelib Builder Framework**. This hub is its complete reference, and a guide to the website builder that runs it.

The same language is read by everyone who builds here. A creator in the code editor, the builder's own AI, and whatever you bring with you, whether that is Claude Code, Codex, ChatGPT or Cursor, all write the same files through the same compiler and get the same errors back. There is no second format for machines and no private dialect for the platform's own sections: the thirty sections in the library are written in exactly what these pages describe.

Where part of the framework is specified but not live yet, the page says so plainly. Nothing here describes a feature you cannot use today without saying that it is not live.

## A section, whole

This is a complete, working section. Save it as `sections/notice.storelib` and it compiles, appears in Add Section, and draws its own settings panel.

```html
<template>
<section class="notice" data-scheme="{{ settings.color_scheme }}">
  <p class="notice__text">{{ settings.message }}</p>
  {% if settings.link_url != "" %}
    <a class="notice__link" href="{{ settings.link_url | url }}">{{ settings.link_text }}</a>
  {% endif %}
</section>
</template>

<style>
.notice { container-type: inline-size; display: flex; flex-wrap: wrap; gap: 8px 16px;
  justify-content: center; padding: 14px 24px; background: var(--scheme-background); }
.notice__text { margin: 0; color: var(--scheme-text); font-size: 14px; }
.notice__link { color: var(--scheme-link); font-size: 14px; font-weight: 600; }
</style>

<schema>
{
  "type": "notice",
  "name": "Notice bar",
  "category": "Promotion",
  "settings": [
    { "type": "text", "id": "message", "label": "Message", "default": "Free shipping on orders over $50" },
    { "type": "text", "id": "link_text", "label": "Link text", "default": "Shop now" },
    { "type": "url", "id": "link_url", "label": "Link", "default": "" },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "dark" }
  ],
  "presets": [{ "name": "Notice bar" }]
}
</schema>
```

Four blocks: markup, scoped CSS, an optional script, and a schema that declares every setting the markup reads. That is the whole format.

## Start here

1. **[How the builder works](https://storelib.com/developers/builder)**. Themes, pages, sections and blocks, what is stored where, and what happens between saving a file and a visitor seeing it.
2. **[Sections](https://storelib.com/developers/sections)**. The `.storelib` file and the template language: output, conditions, loops, filters, and what the compiler refuses.
3. **[Blocks](https://storelib.com/developers/blocks)**. Repeatable content inside a section, and the rules for declaring, rendering and limiting it.
4. **[Schema](https://storelib.com/developers/schema)**. Every setting type, every key a schema can carry, and the order a value is resolved in.
5. **[Styling](https://storelib.com/developers/styling)**. How CSS is scoped, container queries, colour schemes and the theme's type scale.
6. **[JavaScript and forms](https://storelib.com/developers/javascript)**. What a section may do without script, how forms and embeds work, and the scripting API.
7. **[Examples](https://storelib.com/developers/examples)**. Complete sections, each compiled by the test suite on every change.

## Building with an AI agent

Point the agent at [storelib.com/llms.txt](https://storelib.com/llms.txt). It is a map of this hub in the plain format agents read, and [llms-full.txt](https://storelib.com/llms-full.txt) is every page in one file. The [AI guide](https://storelib.com/developers/ai) is written for the agent itself: the rules it must follow, the checks its output has to pass, and the exact reference the builder's own AI is given.

## The framework in numbers

| Limit | Most allowed |
| --- | --- |
| One section file | 512 KB |
| A section's CSS | 128 KB |
| A section's script | 64 KB |
| Settings in one section | 120 |
| Blocks in one section | 50 |
| Sections on one page | 60 |
| One asset | 15 MB |
| Files in a theme package | 2000 |
| A theme package | 50 MB |

Changes to the framework are recorded in the [changelog](https://storelib.com/developers/changelog).

---

<!-- https://storelib.com/developers/builder -->

# How the builder works

A Storelib website is a **theme**: a set of source files that say how things look and behave, and a set of pages that say what is on them. The website builder is an editor over those two things, and the storefront is a renderer over them. This page is the map; the rest of the hub is the detail.

## Source and content

Everything in a theme is one of two kinds, and the split is the whole design.

| Kind | What it is | Where it lives | Who changes it |
| --- | --- | --- | --- |
| **Source** | Section files: markup, CSS, schema, optional script. One file per section type. | `sections/<type>.storelib` | A developer, the code editor, an AI agent |
| **Content** | Pages: which sections they hold, in what order, with what settings and blocks. Never markup. | `templates/<page>.json` | The creator, in the builder |

Change a section file and every page using that section changes how it looks; nobody's content moves. Change a page and one page's content changes; no section changes how it works. There is no file that does both, which is why a section can be rewritten without losing a single word a creator typed.

## A theme on disk

The same layout is used in the database, in the code editor's file tree and inside an exported theme, so it only has to be learned once.

```text
my-theme/
├── theme.json              name, version, engine requirement
├── config/
│   └── settings.json       theme-wide settings: colour schemes, fonts, radius
├── layout/
│   └── theme.storelib      the page shell, and the one place CSS is not scoped
├── templates/
│   ├── index.json          the home page: its sections, in order
│   ├── product.json
│   └── page.about.json     a page of its own, at /about
├── sections/
│   ├── hero.storelib       one file per section type
│   └── features.storelib
└── assets/
    └── 3f2a…c9.png         files, named by the SHA-256 of their bytes
```

Rules the importer and the code editor enforce:

- A section file is `sections/<type>.storelib` and its schema's `type` is the same word. A file whose schema disagrees with its name is refused, because two names for one thing is how a rename loses data.
- A section type is lowercase letters, digits, `-` and `_`.
- Paths are relative to the theme root. A path may not begin with `/` or contain `..`.
- An asset is referenced as `asset://<sha256>`, never by URL. See [Schema](https://storelib.com/developers/schema#assets).

## The hierarchy

```text
Theme
 ├─ Theme settings       colour schemes, fonts, text styles, spacing, radius
 └─ Pages
     └─ Sections          an instance of a section type, with its own settings
         └─ Blocks        repeatable children: a question, a slide, a logo
```

A **section instance**, as the builder stores it:

```json
{
  "id": "sec_9k2m",
  "type": "faq_accordion",
  "name": "FAQ",
  "settings": { "heading": "Questions" },
  "blocks": [
    { "id": "blk_8f2a", "type": "question", "settings": { "question": "Do you ship abroad?" } },
    { "id": "blk_c31d", "type": "question", "settings": { "question": "Returns?" } }
  ],
  "hidden": false
}
```

- Ids are minted once and never change. Reordering moves an instance; duplicating mints a new id.
- `settings` holds only what the creator changed. Everything else comes from the schema's defaults, so a later change to a default reaches everyone who never overrode it.
- A setting the schema no longer declares is kept, not deleted. Updating a section never destroys content.

## Draft and published

Every page and every theme setting has a draft and a published copy. The builder writes drafts as you work; **Publish** copies the drafts over the published columns in one step. Visitors only ever see published values, and the builder only ever shows drafts, so nothing you try in the editor reaches a visitor until you choose.

## What happens when you save a section file

1. **Parse.** The file is split into its four blocks, each with the line it starts on.
2. **Validate the schema.** Every setting type, id, default and option is checked against the control registry.
3. **Compile the template.** The markup becomes a tree. Every name the template reads is checked against the schema beside it, so `{{ settings.headng }}` is an error with a line number, not a blank space on the page.
4. **Scope the CSS.** Every selector is rewritten to apply to this section's instances only.
5. **Check the script.** Forbidden names and undeclared capabilities are refused.

If any step fails, the file is not saved, and each error is shown with its file and line. A section that reached the page has already compiled. See [Sections](https://storelib.com/developers/sections#errors) for the error format.

## What happens when a visitor opens a page

The storefront reads the published page, resolves each section's settings (saved value, then schema default, then the control's own fallback), renders the compiled template to HTML on the server, and sends that HTML with each section's scoped CSS. A visitor's browser receives finished markup and never downloads the template engine.

A hidden section is not rendered. A section whose file does not compile is left out of the published page rather than breaking it, and shown in the builder as a card naming the file and the line.

## Two kinds of section

The library is written in the framework, and so is anything you or an AI write. A few long-standing sections, such as the header and footer, are still drawn by the platform's own React components. Both kinds are placed, reordered, hidden and edited in exactly the same way, and both read the same colour schemes and text styles, so a creator cannot tell them apart. Everything you write is the first kind.

## What keeps a site safe

A theme can be exported to a single `.storelib-theme` file and imported into another account, and themes are becoming something creators share. So the framework treats every section as code somebody else might have written.

- **Markup is escaped.** `{{ }}` always HTML-escapes. The only way to emit markup is the `raw` filter, and only on a `richtext` setting, whose value is cleaned against an allow list on save, on import and again on every read.
- **CSS cannot leave its section.** Scoping is done by the compiler, not by convention.
- **No inline script.** `<script>` in a template, `on*=` attributes and `javascript:` URLs are refused at compile time.
- **Frames are allow-listed.** An `<iframe>` needs the `embed` capability and takes its address from the `embed` filter, which only answers for known video and audio players.
- **Scripts cannot reach the page.** `window`, `document`, `fetch` and the rest are refused by name. See [JavaScript](https://storelib.com/developers/javascript).

## Moving a theme

**Export** writes the theme's files, pages, settings and assets into one `.storelib-theme` file, with a manifest listing the SHA-256 of every file. **Import** reads it as a whole or not at all: every path is checked, every hash is recomputed, every section is compiled, and every page is checked against the sections it uses. A package that fails any check is refused with the list of reasons, and nothing is written. Anything creator-written is cleaned on the way in.

Limits for a package:

| Limit | Most allowed |
| --- | --- |
| One section file | 512 KB |
| A section's CSS | 128 KB |
| A section's script | 64 KB |
| Settings in one section | 120 |
| Blocks in one section | 50 |
| Sections on one page | 60 |
| One asset | 15 MB |
| Files in a theme package | 2000 |
| A theme package | 50 MB |

---

<!-- https://storelib.com/developers/website-builder -->

# Using the website builder

Every part of the Storelib website builder: what each button, panel and setting is, what it changes, and where it lives. The settings on this page are drawn from the same lists the builder reads, with their defaults, so what you see here is what you see in the editor.

The builder opens from **Websites** in your dashboard. Pick a website and press **Edit website**.

## The screen

| Part | Where | What it is for |
| --- | --- | --- |
| Top bar | Across the top | Leaving, switching page, desktop or phone preview, the inspector, Ask AI, and Publish. |
| Sidebar | Left, on a computer. A sheet at the bottom, on a phone | The sections of the page, the pages of the site, and General Settings. |
| Canvas | The middle | The page, drawn by the same renderer your visitors get. Click a section to edit it. |
| Ask AI | Between the sidebar and the canvas, when open | Describe a change, or a new section, and it is made. |

A window narrower than 768px is treated as a phone: the preview is the phone preview and the sidebar becomes a sheet with three tabs, **Sections**, **Pages** and **Settings**.

## The top bar

From left to right on a computer:

| Control | What it does |
| --- | --- |
| Exit | Back to your websites. If a save is still going or a code file is unsaved, it asks first: **Stay here** or **Leave anyway**. |
| Sections, Pages, General Settings | Switch what the sidebar shows. |
| Website name and green dot | The dot means the website is published. |
| **…** menu | View code, Theme settings, Website settings, Connect Claude Code or Codex, Undo, Redo, View live site, Back to Dashboard. On a phone this is also how you reach Code, Website settings and the connections. |
| Preview, Code, Website Settings | Three ways of looking at the project. Code opens the code editor over the canvas. |
| Desktop or phone | One button that switches the canvas between the full width and a 390px phone. |
| Page switcher | Which page you are editing. See [Pages](#pages). |
| Open the live page | The page you are on, on the live site, in a new tab. |
| Undo and Redo | 30 steps. Typing in a box counts as one step. Changing page starts a fresh history. |
| Inspector | On: click a section in the canvas to select it. Off: the canvas is a plain preview you can click through. |
| Plug | **Connect Claude Code, Codex or ChatGPT.** Opens Website Settings › Advanced, where they connect. |
| Ask AI | Opens and closes the AI panel. |
| Publish, or Save | See [Saving and publishing](#saving-and-publishing). |

Shortcuts: **⌘Z** or **Ctrl+Z** undoes, **⌘⇧Z**, **⌘Y** or **Ctrl+Y** redoes. In the code editor, **⌘S** or **Ctrl+S** saves.

## The sidebar

### Sections

The page's sections, top to bottom.

- **The header and footer** sit in their own boxes at the top and bottom. They are the same on every page: change them on one and every page changes. They can be hidden with the eye, but not moved, copied or deleted.
- **Every other section** has a grip to drag it up or down (press and hold on a phone, or use the arrow keys), and a **…** menu with **Duplicate**, **Hide** or **Show**, and **Delete**. Right-clicking the row opens the same menu.
- A hidden section is drawn faded in the list and is left out of the page. Delete takes effect at once; Undo brings it back.
- A thin line between two rows shows a **+** under the pointer: press it to add a section at exactly that point.
- **Add section**, at the end of the list on a computer and the start on a phone, adds a section above the footer.

### Adding a section

**Add section** opens the library: a search box, the categories down the side, and a card for each section drawn small with its real content. Sections you or Ask AI coded are under **Created by you**. Pick one and it is placed, selected and scrolled to.

The library's categories are Hero, Products, Features, Content, Social Proof, CTA, Media, About, FAQ and Marketing.

### Blocks

Some sections hold repeated items: questions in an FAQ, columns in a footer, slides in a gallery. These are blocks, listed under the section's settings. Each block can be moved up or down, duplicated, deleted, and opened to edit its own settings. **Add** adds another until the section's limit, and clicking a block in the canvas opens it in the list.

### Pages

**Pages** lists the website's pages: Home, About, Contact, Shop and Search, the pages you made, and a product page for each product. The switcher in the top bar does the same with a search box, and **Create page** asks for a title and makes a page at an address taken from it. A new page starts with the header and footer and nothing between.

Every website comes with a Refund Policy, a Privacy Policy and Terms of Service page. Edit them like any other page before you publish.

## A section's settings

Click a section, in the canvas or the list, and its settings open in the sidebar.

- **Colour scheme** comes first: pick one of the website's schemes and every colour in the section follows it. **Advanced colors** overrides single colours (background, text, heading, accent, border, and the two buttons) for this section only. **Reset to scheme** undoes that.
- **Text** picks the heading and body styles from General Settings, or **Custom** to set font, weight, size per screen, line height, letter spacing and case for this section.
- **The section's own settings** follow, in the order its file declares them, each with its help text.
- **Blocks**, if it has any.
- **Hide**, **Duplicate** and **Delete** are pinned along the bottom.

With the inspector on, a selected section also shows a small toolbar at its top right: Ask AI, Move up, Move down, Duplicate, Hide and Delete.

### Every control a section can have

A section declares its settings in its schema, and each type is drawn as one control. This is every type, drawn as the builder draws it. To write one, see [Schema](https://storelib.com/developers/schema).

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Heading (`text`) | text | Welcome | A single line of text. A one-line box. A text setting whose id or label says gradient is drawn as the gradient editor instead. |
| Body (`textarea`) | textarea |  | Several lines of plain text. A box that grows as you type. |
| Content (`richtext`) | richtext |  | Formatted text. Stored as sanitised HTML; output with the `raw` filter. A small editor with Paragraph, Heading 2 to 4, Bold, Italic, Link, bulleted and numbered lists. Pasting brings in plain text. |
| Columns (`number`) | number 1 to 6 | 3 | A number typed in. A number box that keeps to its min, max and step. With `responsive`, a Desktop, Tablet, Phone switch sits above it. |
| Show badge (`toggle`) | toggle | true | On or off. A switch. |
| Require agreement (`checkbox`) | toggle |  | On or off, drawn as a checkbox. Prefer `toggle` for a single switch. The same switch as toggle. Prefer toggle in new sections. |
| Layout (`select`) | select: Centre, Split | Centre | One of a list, drawn as a dropdown. A dropdown. |
| Button style (`radio`) | radio: Filled, Outline | Filled | One of a short list, every option visible. Buttons side by side when there are three options or fewer, a dropdown when there are more. |
| Padding (`range`) | range 0 to 160px | 64 | A number on a slider. A slider with the number and unit beside it. Can be responsive. |
| Background (`color`) | color | #ffffff | A hex colour. A swatch and its hex. It opens in place with a colour field, a hue slider, the hex and the colours already on the page. Hidden in a section panel, where colours come from the scheme. |
| Colour scheme (`color_scheme`) | color_scheme | white | One of the theme's named colour schemes, by key: the built-in white, light, dark, black and highlight (Light, Soft, Dark, Brand and Accent in the editor) or one the creator added. The editor offers every scheme the theme has; see docs/theme/16-design-tokens.md. The scheme picker at the top of the section panel, each scheme painted in its own colours, with Edit beside each one. |
| Heading font (`font_picker`) | font | Inter | A font family from the theme's font list. A dropdown whose options are drawn in their own font. |
| Align (`alignment`) | alignment | center | Left, centre or right. Three buttons: left, centre, right. Can be responsive. |
| Image (`image_picker`) | image |  | One image from the media library. Stored as an asset reference, rendered as a URL. A dashed box: Add Image, click to upload or drag in. Filled, it shows the picture with Replace and Remove. JPEG, PNG, GIF, WebP, SVG or AVIF under 5 MB. |
| Images (`image_gallery`) | image_gallery  to 12 |  | Several images, in order. A stack of image pickers, with an empty one at the end to add another. |
| Background video (`video_picker`) | video |  | A video file from the media library, or a hosted video URL. The video, with an X to clear it, and a box to paste a hosted video link. |
| Downloadable file (`file_picker`) | file |  | Any file from the media library. A box for a file's address. |
| Icon (`icon_picker`) | icon | zap | One icon from Storelib's icon library, by name. A searchable grid of icons. |
| Button link (`url`) | url | /shop | Where something links to: a page of the site, a product, or any address. The link picker: a search over your pages and products, or any address typed in (`/about`, `https://…`, `mailto:`). |
| Page (`page_picker`) | picker |  | One of the site's pages, by key. A dropdown of the site's pages. |
| Product (`product_picker`) | picker |  | One of the creator's products, by id. A dropdown of your products. |
| Community (`community_picker`) | picker |  | One of the creator's communities, by id. A box for a community id. |
| Content (`header`) | header |  | A heading in the sidebar. Holds no value. A small heading that divides a long panel. Holds no value. |
| Paragraph (`paragraph`) | paragraph |  | A line of help text in the sidebar. Holds no value. A line of help text in the panel. Holds no value. |
| Divider (`divider`) | divider |  | A rule between groups of settings. Holds no value. A line across the panel. Holds no value. |

### The header's own panel

The header has a panel of its own, in three parts.

- **Store Logo**: the logo, its height, a nudge left or right, and a separate logo and height for phones.
- **Navigation Links**: up to eight links, each with a label, where it goes, and whether it opens in a new tab. Drag to reorder. Each link can hold one level of sub-links.
- **Header Settings**: the layout on a computer (logo left, nav inline, nav centred, or logo centred) and on a phone; the colour scheme; how menu links react to the pointer; width and spacing; sticky and transparent behaviour; a bottom border and shadow; which icons show (search, account, wishlist, cart); and an optional button with its own text and link.

## General Settings

The settings that belong to the whole website. Open them with the gear in the top bar, or **Settings** on a phone.

### Colors

Every section picks one **colour scheme**. Change a scheme here and every section using it changes with it. A website starts with five:

| Colour | Light (`white`) | Soft (`light`) | Dark (`dark`) | Brand (`black`) | Accent (`highlight`) |
| --- | --- | --- | --- | --- | --- |
| Surface: Background | #ffffff | #f8fafc | #1f2937 | #000000 | #fde2e4 |
| Surface: Secondary background | #f8fafc | #ffffff | #111827 | #111111 | #fff1f2 |
| Surface: Border | #e2e8f0 | #e2e8f0 | #374151 | #1f2937 | #fbcfd1 |
| Text: Heading | #0f172a | #0f172a | #ffffff | #ffffff | #1f2937 |
| Text: Text | #5c5b63 | #475569 | #cbd5e1 | #cbd5e1 | #475569 |
| Text: Muted text | #76757d | #697483 | #94a3b8 | #9ca3af | #626976 |
| Text: Link | #0f172a | #0f172a | #f8fafc | #ffffff | #1f2937 |
| Text: Accent | #1f2937 | #1f2937 | #e5e7eb | #e5e7eb | #0f172a |
| Primary button: Primary button | #000000 | #0f172a | #ffffff | #ffffff | #1f2937 |
| Primary button: Primary button text | #ffffff | #ffffff | #0f172a | #000000 | #fde2e4 |
| Primary button: Primary button border | #000000 | #0f172a | #ffffff | #ffffff | #1f2937 |
| Secondary button: Secondary button | #ffffff | #ffffff | transparent | transparent | transparent |
| Secondary button: Secondary button text | #0f172a | #0f172a | #ffffff | #ffffff | #1f2937 |
| Secondary button: Secondary button border | #0f172a | #0f172a | #ffffff | #ffffff | #1f2937 |
| Inputs: Input | #ffffff | #ffffff | #111827 | #111111 | #ffffff |
| Inputs: Input text | #0f172a | #0f172a | #f8fafc | #ffffff | #1f2937 |
| Inputs: Input border | #e2e8f0 | #e2e8f0 | #374151 | #1f2937 | #fbcfd1 |

Pick a scheme to edit it: its name, whether new sections start on it, and its seventeen colours in five groups (surface, text, primary button, secondary button, inputs). If a pair of colours is hard to read, it says so and by how much. A scheme can also lay a gradient over its background. **Add scheme** makes another; a scheme you made can be deleted, and the sections on it move to another.

**Page colors**, under Colors, are the colours of the page itself, behind and between sections:

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Primary (`primary_color`) | color | #6366f1 | The page's main colour, outside any section. |
| Primary hover (`primary_hover_color`) | color | #4f46e5 | The main colour under the pointer. |
| Secondary (`secondary_color`) | color | #8b5cf6 | A second colour for the page's own parts. |
| Accent (`accent_color`) | color | #f59e0b | Small highlights outside sections. |
| Page background (`background_color`) | color | #ffffff | The page behind every section. |
| Surface / card (`surface_color`) | color | #f8fafc | Cards and panels outside sections. |
| Surface alt (`surface_alt_color`) | color | #f1f5f9 | A second, slightly different surface. |
| Heading text (`text_color`) | color | #0f172a | Headings outside sections. |
| Body text (`text_secondary_color`) | color | #64748b | Body text outside sections. |
| Muted text (`text_muted_color`) | color | #94a3b8 | Captions and quiet text outside sections. |
| Border (`border_color`) | color | #e2e8f0 | Lines and borders outside sections. |
| Link color (`link_color`) | color | #6366f1 | Links outside any section. |
| Link hover (`link_hover_color`) | color | #4f46e5 | Those links under the pointer. |
| Success (`success_color`) | color | #10b981 | Confirmations, such as a sign-up that went through. |
| Error (`error_color`) | color | #ef4444 | Errors, such as a form that needs fixing. |

### Branding

The store's name, logo and its height, an optional smaller logo for phones, the favicon and a tagline. The logo is kept in step with the header's Store Logo: change it in either place.

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Store name (`brand_name`) | text |  | The store's name, used by the header when there is no logo and in the page title. |
| Logo image (`logo_url`) | image |  | The logo in the header. Kept in step with the header's own Store Logo. |
| Logo height (`logo_width`) | range 24 to 120px | 40 | How tall the logo is drawn. The Branding panel shows it as Logo height. |
| Favicon (`favicon_url`) | image |  | The small icon in the browser tab. A square image, 64 by 64 or larger. |
| Tagline (`tagline`) | text |  | A line under the store's name, where a section or the footer shows it. |

### Typography

Three fonts, and nine text styles every section uses unless it sets its own.

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Heading font (`font_heading`) | font: Inter, Plus Jakarta Sans, Space Grotesk, DM Sans, Poppins, Montserrat, Raleway, Oswald, Bebas Neue, Playfair Display, Cormorant Garamond, Lora, Merriweather, Libre Baskerville, EB Garamond | Inter | The font every heading style uses unless a style says otherwise. |
| Body font (`font_body`) | font: Inter, DM Sans, Plus Jakarta Sans, Space Grotesk, Poppins, Nunito, Source Sans 3, Lato, Open Sans | Inter | The font for body text and buttons. |
| Accent font (`font_accent`) | font: Same as heading font, Inter, DM Sans, Plus Jakarta Sans, Space Grotesk, Poppins, Nunito, Source Sans 3, Lato, Open Sans | Same as heading font | A third font a text style can pick. Empty means the heading font. |

The text styles, with their defaults. Each can be changed: font, weight, a size for desktop, tablet and phone, line height, letter spacing and case. A dot marks a style you changed, and **Reset style** puts it back.

| Style | Key | Font | Weight | Size, px (desktop / tablet / phone) | Line height | Letter spacing, px |
| --- | --- | --- | --- | --- | --- | --- |
| Heading 1 | `h1` | heading | 700 | 56 / 44 / 36 | 1.1 | -1 |
| Heading 2 | `h2` | heading | 700 | 36 / 32 / 30 | 1.15 | -0.5 |
| Heading 3 | `h3` | heading | 600 | 24 / 22 / 20 | 1.25 | 0 |
| Heading 4 | `h4` | heading | 600 | 18 / 17 / 16 | 1.35 | 0 |
| Body large | `body_large` | body | 400 | 18 / 17 / 17 | 1.6 | 0 |
| Body | `body` | body | 400 | 16 | 1.6 | 0 |
| Body small | `body_small` | body | 400 | 14 | 1.5 | 0 |
| Button | `button` | body | 600 | 14 | 1.2 | 0 |
| Caption | `caption` | body | 500 | 12 | 1.4 | 0.3 |

### Buttons

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Default style (`button_style`) | radio: Filled, Outline, Ghost | Filled | What a button looks like before a section changes it: filled, outlined or text only. |
| Button shape (`button_shape`) | radio: Square, Rounded, Pill | Rounded | Square corners, rounded, or fully round ends. |
| Border radius (px) (`button_border_radius`) | range 0 to 32px | 8 | Exactly how round a rounded button is. |
| Default size (`button_size`) | select: Small, Medium, Large, Extra large | Medium | The default padding and text size of a button. |
| Font weight (`button_font_weight`) | select: Normal (400), Medium (500), Semibold (600), Bold (700) | Semibold (600) | How heavy button text is. |
| Button shadow (`button_shadow`) | toggle | false | A soft shadow under every button. |
| Hover animation (`button_transition`) | select: None, Fade, Lift, Scale | Fade | What a button does under the pointer. |

### Layout

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Max page width (`page_width`) | range 900 to 1800px | 1240 | The widest the content of a section gets on a large screen. |
| Side padding (`content_padding_x`) | range 8 to 80px | 32 | The space between content and the screen's edges. |
| Section gap (`section_gap`) | range 0 to 80px | 0 | Space added between every two sections. |
| Spacing scale (`spacing_scale`) | range 0.5 to 2 | 1 | Multiplies every section's own spacing: below 1 tighter, above 1 roomier. |
| Card border radius (`border_radius`) | range 0 to 24px | 8 | How round the corners of cards are. |
| Card shadow (`card_shadow`) | select: None, Small, Medium, Large | Small | How much shadow a card casts. |
| Image border radius (`image_border_radius`) | range 0 to 24px | 8 | How round the corners of images are. |

### Animations

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Enable scroll animations (`animations_enabled`) | toggle | true | Sections ease in as they scroll into view. Visitors who ask their device for less motion never see it. |
| Animation style (`animation_style`) | select: Fade up, Fade in, Slide left, Slide right, Zoom in | Fade up | How a section arrives: rising, fading, sliding or growing. |
| Duration (ms) (`animation_duration`) | range 200 to 1200ms | 600 | How long the arrival takes. |
| Stagger delay (ms) (`animation_stagger`) | range 0 to 200ms | 80 | The delay between items arriving in a row, such as cards. |

### Announcement bar

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Show announcement bar (`announcement_bar_enabled`) | toggle | false | A thin bar across the top of every page. |
| Message (`announcement_bar_text`) | text |  | What the bar says. |
| Link text (`announcement_bar_link_text`) | text |  | The words of the link at the end of the bar. |
| Link URL (`announcement_bar_link_url`) | url |  | Where that link goes. |
| Background (`announcement_bar_bg`) | color | #6366f1 | The bar's colour. |
| Text color (`announcement_bar_color`) | color | #ffffff | The colour of the bar's text. |
| Scrolling marquee (`announcement_bar_scrolling`) | toggle | false | The message moves across the bar instead of standing still. |
| Allow dismiss (`announcement_bar_dismissible`) | toggle | true | Visitors can close the bar with an X. |

### Social links

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Twitter / X URL (`social_twitter`) | url |  | Your X profile, for the social icons. |
| Instagram URL (`social_instagram`) | url |  | Your Instagram profile. |
| YouTube URL (`social_youtube`) | url |  | Your YouTube channel. |
| TikTok URL (`social_tiktok`) | url |  | Your TikTok profile. |
| LinkedIn URL (`social_linkedin`) | url |  | Your LinkedIn page. |
| Discord URL (`social_discord`) | url |  | Your Discord server invite. |
| Facebook URL (`social_facebook`) | url |  | Your Facebook page. |
| Pinterest URL (`social_pinterest`) | url |  | Your Pinterest profile. |
| Twitch URL (`social_twitch`) | url |  | Your Twitch channel. |
| GitHub URL (`social_github`) | url |  | Your GitHub profile. |
| Show icons in header (`social_show_in_header`) | toggle | false | Shows an icon for each filled-in profile in the header. |
| Show icons in footer (`social_show_in_footer`) | toggle | true | Shows them in the footer. |

### Shipping

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Free shipping threshold ($) (`free_shipping_threshold`) | number 0 to  | 0 | The order total above which shipping is free. 0 turns it off. |
| Show free shipping progress bar (`free_shipping_bar`) | toggle | false | Shows the cart how far it is from free shipping. |

### SEO

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Default page title (`seo_title`) | text |  | The title search results and browser tabs show when a page has none of its own. |
| Meta description (`seo_description`) | textarea |  | The sentence search results show under the title. |
| Social share image (OG) (`seo_og_image`) | image |  | The picture a link to your site shows when it is shared. |
| Twitter card type (`seo_twitter_card`) | select: Summary, Summary with large image | Summary with large image | A small or a large picture when a link is shared on X. |
| Allow search indexing (`seo_robots`) | toggle | true | Off asks search engines not to list the site. |

### Cookie and privacy

| Setting | Control | Default | What it does |
| --- | --- | --- | --- |
| Use my own words and colours (`cookie_banner_enabled`) | toggle | false | Every site asks visitors before storing anything optional, and a visitor can change their answer from Cookie preferences in the footer. On, the banner uses the words and colours below instead of Storelib's. |
| Banner text (`cookie_banner_text`) | textarea |  | What the banner says, in place of Storelib's sentence. |
| Accept button text (`cookie_accept_text`) | text |  | The words on the accept button. |
| Decline button text (`cookie_decline_text`) | text |  | The words on the decline button. |
| Banner background (`cookie_bg`) | color | #0f172a | The banner's colour. |
| Text color (`cookie_text_color`) | color | #ffffff | The banner's text colour. |

## The canvas

The canvas is your page, drawn the way a visitor sees it.

**With the inspector on**, a section shows a faint ring under the pointer and a solid one when selected. Clicking selects a section, or a block inside it. Clicking into a form field lets you type in it rather than selecting the section. Hovering the gap between two sections shows **Add a section here**.

**With the inspector off**, the canvas is a plain preview: links inside the website open that page in the builder.

Either way, the builder never leaves itself:

- A link to a page of the website opens that page in the builder. A link to a page that does not exist yet offers **Create this page**.
- Links to other websites, email links and phone links do nothing.
- Forms do not submit, and nothing can be bought. A sign-up box in the canvas does not subscribe anyone.

A section that fails to draw says so in its place, with the error and **Try again**. The rest of the page is unaffected.

## Ask AI

Ask AI has two modes.

- **Change this page**: describe a change and it is made with the same sections, blocks and settings the panels use. It is one step of Undo, and nothing is saved until the builder saves. Select a section first and it can be limited to that one.
- **Code a section**: describe a section the library does not have. It is written as a section file, compiled, and only kept if it compiles; a file that does not compile is sent back to be fixed, up to three times. While it is being written, the panel says what it is doing (Starting, Thinking, Writing the section, Checking it, Fixing a detail), the spot it will fill shows code being typed, and the finished section takes its place. If it still cannot get it right, it says so in plain words with **Try again**, never with the compiler's report.

Both modes answer rather than guess. A greeting, a question, or a request too unclear to act on gets a short reply saying what it understood and what to ask for, and nothing on the page changes.

You can attach up to four pictures (PNG, JPEG, WebP or GIF) of something you want built. Pressing Enter while it is working queues the next request.

## The code editor

**Code**, in the top bar, opens every file of the website's theme: the section files, the templates, the settings, the styles and the scripts. The list marks files you changed in blue and unsaved ones in amber.

- **Save** (or ⌘S) compiles a section file first. If it does not compile, nothing is saved, and each error is listed with its line; press one to jump to it, or **Solve with AI**.
- A save is a draft: the live website changes when you publish.
- **History** lists every save of a file; open any of them to bring it back.
- **Revert** puts a theme file back to how the theme shipped it. Your own files can be renamed, duplicated and deleted; the editor warns first if a page uses the section.
- Unsaved edits are kept in the browser, and offered back when you return.

The language section files are written in is the [Storelib Builder Framework](https://storelib.com/developers/sections).

## Website settings

**Website Settings**, in the top bar, is a page of its own, with nine subjects down the left. On a phone they are a list, and each opens with its own Back. The tabs above the live website's cover on the Website page (Pages, Domain, SEO, Publishing, Settings) open the matching one.

Every website has its own settings. Anything marked below as part of the draft is saved with the website's other changes, can be undone, and reaches visitors when you publish.

| Page | What is there |
| --- | --- |
| General | The website's name, which only you see. Its address, set by your username. Whether it is live. Its favicon and its language (both part of the draft); the language sets the page's `lang` and the share card's locale. |
| Domains | The Storelib address, and a custom domain if one is connected, with its status: waiting for DNS, securing, or connected. The `www.` address is the main one and the bare domain redirects to it. HTTPS is set up for both. **Connect a domain** opens Settings › Domains. |
| SEO & Social | A preview of the search result. Site title, meta description, social image, share card size, and whether search engines may list the website (all part of the draft). |
| Pages & Navigation | Every page with **Edit**, which opens it in the builder, and **Add page**. **Edit menu** selects the header, where the menu is. |
| Commerce | How many published products the website can show, and **Manage products**. Checkout is Storelib's, paid by card or Google Pay through Stripe, in US dollars. **Payments settings** is where payouts go. Free shipping from an amount, and the free shipping bar (part of the draft). |
| Policies | The refund, privacy and terms pages, each with **Edit**. The cookie banner, its message and its two buttons (part of the draft). |
| Publishing | Live or draft, the published address, when it was last published, **Publish**, and **Take offline**, which asks first and deletes nothing. |
| Backups & Versions | A backup is kept every time you publish and every time Ask AI finishes. **Back up now** makes one; **Restore** puts one back (after saving the current draft as a backup first). The newest 30 are kept. **Duplicate** makes a draft copy, if the library has room. |
| Advanced | **Connect Claude Code, Codex or ChatGPT**: pick the tool and follow its steps. Claude Code and Codex connect directly with a token or through GitHub; ChatGPT connects through GitHub. **Edit code**, and the developer docs. See [Building with AI agents](https://storelib.com/developers/ai). |

A creator keeps up to three websites: one live and two drafts. Add theme, Duplicate and Import all refuse a fourth, on the server.

## Saving and publishing

- Every change is saved as a **draft** a moment after you make it. There is no save button to remember while editing.
- The live website does not change until you **Publish**. On a website that is live, the button in the top bar says Publish, with a bright dot when the draft is ahead of the live site.
- The Publish panel shows the website's address, when it was last published, and **Preview**, which makes a private link that shows the draft to anyone you send it to.
- Publishing makes every page's draft, the theme settings and the saved code files live at once, and keeps a backup.
- A website that has never been published has a **Save** button instead, since there is nothing live to update yet.

---

<!-- https://storelib.com/developers/sections -->

# Sections

A section is one file, `sections/<type>.storelib`, that describes a section type completely: how it looks, how it is styled, what a creator can change about it, and what it does. It has four blocks, in any order, at most one of each.

| Block | Required | What it holds |
| --- | --- | --- |
| `<template>` | yes | The markup, in the template language below. |
| `<style>` | no | CSS for this section's instances only. `<style scoped>` means the same thing. See [Styling](https://storelib.com/developers/styling). |
| `<script>` | no | Behaviour. Checked when saved, then **run in a sandbox** against a copy of the section. See [JavaScript](https://storelib.com/developers/javascript). |
| `<schema>` | yes | JSON: the section's identity, settings, blocks and presets. See [Schema](https://storelib.com/developers/schema). |

## Rules the parser enforces

- A block's opening and closing tags count only when they start a line. `</style>` inside a string in the template is text, not the end of the style block.
- A second `<template>`, or a second of any block, is refused, naming the line of the first.
- A block that is never closed is refused at the line it opened.
- A file without `<template>` or `<schema>` is refused.
- There is no unscoped `<style>` in a section. Global CSS belongs in `layout/theme.storelib`.

## The template language

The template is HTML plus output, conditions, loops and comments. It is **not** Vue, React, JSX or Liquid, although it looks like Liquid: `v-if`, `@click`, `:class` and JSX braces are refused by the compiler. It is compiled to a tree and walked, with no `eval` anywhere, which is what keeps rendering deterministic and lets the storefront run under a strict Content Security Policy.

```html
<h2>{{ settings.heading }}</h2>

{% if settings.show_subheading and settings.subheading != "" %}
  <p>{{ settings.subheading }}</p>
{% elsif settings.show_subheading %}
  <p>No subheading yet</p>
{% endif %}

<ul>
{% for block in blocks %}
  <li data-block-id="{{ block.id }}" class="{% if forloop.first %}is-first{% endif %}">
    {{ forloop.index }}. {{ block.settings.title | upcase }}
  </li>
{% else %}
  <li>Add an item</li>
{% endfor %}
</ul>

{# A comment. It is read and thrown away, and never reaches the page. #}
```

### Output

`{{ expression }}` prints a value, always HTML-escaped. The only way to print markup is the `raw` filter, and only on a `richtext` setting, whose value was cleaned against an allow list before it was stored.

### Expressions

- **Literals:** `"text"`, `'text'`, `12`, `1.5`, `true`, `false`, `null`.
- **Paths:** `settings.heading`, `block.settings.url`, `theme.colors.primary`, `items[0]`, `items["key"]`. Indexes must be literal; there are no computed lookups.
- **Comparisons:** `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`.
- **Logic:** `and`, `or`, `not`, and parentheses.
- **Filters:** `value | name: arg1, arg2`, chained left to right.

A path reads plain data only. `__proto__`, `constructor` and `prototype` cannot be reached, a function is never called, and a missing value is `null` rather than an error. Arrays have `.size`, `.first` and `.last`.

### Every name must be declared

`{{ settings.foo }}` compiles only when the schema declares a setting with the id `foo`, and `{{ block.settings.bar }}` only when that block type declares `bar`. A typo is a compile error with a line number. A setting the schema declares and the template never reads is a warning: it would be a control in the panel that does nothing.

### What a template can read

| Name | What it is |
| --- | --- |
| `settings.*` | This instance's settings, resolved: defaults applied, assets turned into URLs, responsive values as `{ desktop, tablet, mobile }`. |
| `blocks` | This instance's blocks in order, each `{ id, type, settings }`. Hidden blocks are left out. |
| `section.id`, `section.type` | This instance. Use `section.id` to build element ids, so the section can appear twice on a page. |
| `scheme.*` | The colour scheme this instance chose, resolved, with the section's own overrides applied. See [Styling](https://storelib.com/developers/styling#colour-schemes). |
| `theme.colors.*`, `theme.typography.*`, `theme.radius.*`, `theme.spacing.*`, `theme.settings.*` | The theme's tokens. |
| `page.template` | Which page this is on: `index`, `product`, `page.about` and so on. |
| `page.in_editor` | `true` inside the builder. Put prompts for the creator behind it so a visitor never sees them. |
| `products` | The creator's published products, newest first, each `{ id, type, settings }` with `settings.title`, `price` (already formatted), `compare_price`, `image`, `url` and `tag`. The same shape as a block, so one card works for both. |
| `forloop.index`, `index0`, `first`, `last`, `length` | Inside a `for`. |

### Filters

| Filter | Example | What it does |
| --- | --- | --- |
| `default` | `{{ settings.label \| default: "Shop" }}` | The argument when the value is empty, `null` or `false`. |
| `upcase` | `{{ settings.tag \| upcase }}` | Upper case. |
| `downcase` | `{{ settings.tag \| downcase }}` | Lower case. |
| `capitalize` | `{{ settings.name \| capitalize }}` | The first letter in upper case. |
| `strip` | `{{ settings.name \| strip }}` | Removes spaces from both ends. |
| `size` | `{{ blocks \| size }}` | How many items a list has, or characters a string has. |
| `first` | `{{ blocks \| first }}` | The first item of a list, or the first character of a string. |
| `last` | `{{ blocks \| last }}` | The last item of a list, or the last character of a string. |
| `join` | `{{ settings.tags \| join: " · " }}` | A list joined into one string, with `, ` unless given another separator. |
| `truncate` | `{{ settings.text \| truncate: 80 }}` | Cut to that many characters, 50 unless given, ending with `…` or the second argument. |
| `append` | `{{ settings.price \| append: " each" }}` | Adds the argument to the end. |
| `prepend` | `{{ settings.code \| prepend: "#" }}` | Adds the argument to the start. |
| `replace` | `{{ settings.text \| replace: "old", "new" }}` | Replaces every occurrence of the first argument with the second. |
| `plus` | `{{ forloop.index \| plus: 1 }}` | Adds a number. |
| `minus` | `{{ settings.count \| minus: 1 }}` | Subtracts a number. |
| `times` | `{{ settings.columns \| times: 2 }}` | Multiplies by a number. |
| `divided_by` | `{{ settings.width \| divided_by: 2 }}` | Divides by a number. Dividing by zero gives 0. |
| `round` | `{{ settings.ratio \| round: 2 }}` | Rounds to that many decimal places, 0 unless given. |
| `json` | `data-config="{{ settings \| json }}"` | The value as JSON, escaped for an attribute. |
| `escape` | `{{ settings.text \| escape }}` | HTML-escaped. Output already is, so this is rarely needed. |
| `raw` | `{{ settings.body \| raw }}` | Printed without escaping. Only on a `richtext` setting, which was cleaned before it was stored. |
| `url` | `href="{{ settings.link \| url }}"` | Keeps a link starting `/`, `http://`, `https://`, `mailto:`, `tel:` or `#`, keeps an empty value empty, and turns anything else into `#`. Use it on every link built from a setting. |
| `embed` | `src="{{ settings.video \| embed }}"` | A player address from a pasted YouTube, Vimeo, Spotify or SoundCloud link, or an empty string. Needs the `embed` capability. |
| `asset` | `{{ block.settings.clip \| asset }}` | An `asset://` reference as the URL this account serves it from. A plain URL passes through. |
| `alpha` | `{{ settings.color \| alpha: 0.4 }}` | A hex colour at that opacity, as `rgba()`. |

Two rules worth remembering: put `| url` on every `href` built from a setting, and use `raw` only on a `richtext` setting.

### What the compiler refuses

- A <script> tag inside <template>. A section's script goes in its own <script> block, beside <template>, where it runs in a sandbox.
- An on*= attribute. Add the listener in the section's <script> block instead, or use HTML that needs none: <details>, a radio input with :checked, or popovertarget.
- A javascript: URL.
- An <object> or <embed>.
- An `<iframe>`, unless the schema declares the `embed` capability and its `src` comes from the `embed` filter.
- An unclosed `{{` or `{%`, an `{% if %}` without `{% endif %}`, an unknown tag, an unknown filter, or a malformed expression.
- A name the schema does not declare, such as `{{ settings.headng }}`.

Vue syntax is refused by name, with what to write instead, because it is the first thing anyone arriving from a framework reaches for:

| Vue | Write instead |
| --- | --- |
| `v-if` | {% if … %} … {% endif %}. |
| `v-else-if` | {% elsif … %}. |
| `v-else` | {% else %}. |
| `v-for` | {% for item in list %} … {% endfor %}. |
| `v-show` | {% if … %} … {% endif %}. |
| `v-bind:` | An attribute written out: href="{{ settings.link }}". |
| `v-model` | A setting in the schema; a section does not hold state. |
| `v-html` | {{ settings.body \| raw }}, for a richtext setting. |
| `v-text` | {{ settings.text }}. |
| `v-on:` | HTML where it does it alone (<details> for open and close, a radio input with :checked for tabs, popovertarget for a pop-up), or a listener in the section's <script> block: root.querySelector(".x").addEventListener("click", …). |
| `@click` | HTML where it does it alone (<details> for open and close, a radio input with :checked for tabs, popovertarget for a pop-up), or a listener in the section's <script> block: root.querySelector(".x").addEventListener("click", …). |
| `:key` | Nothing: a {% for %} needs no key. |
| `:attribute` | The attribute itself, with the value in it. |

## Errors

Nothing in the framework throws on bad input. Every stage returns either a result or a list of errors in one shape, which the code editor shows beside the line, the AI receives to fix its own output, and the importer attaches to a refused package.

```ts
interface ThemeError {
  stage: "parse" | "schema" | "template" | "css" | "script" | "package"
  message: string
  file?: string     // "sections/hero.storelib"
  line?: number     // 1-based, in that file
  column?: number
  path?: string     // "settings[3].default", for errors about data
}
```

Errors inside the schema's JSON are reported at the line of the `.storelib` file, not the line of the JSON, so an error always points where you would click. A **warning**, such as a setting the template never reads, does not stop a save.

| Stage | Refuses | Example message |
| --- | --- | --- |
| `parse` | A malformed file. | `<style> is never closed` |
| `schema` | JSON that breaks the schema rules. | `default "big" is not a range` at `settings[2].default` |
| `template` | Bad markup or a refused construct. | `a <script> tag inside <template>` |
| `css` | Syntax errors, `@import`, size. | `@import is not allowed` |
| `script` | Forbidden names, unknown capabilities, size. | `"window" is not available to a section` |
| `package` | A theme file that fails an import check. | `sha256 does not match the manifest` |

## Checklist for a new section

- `type` in the schema equals the file name.
- Every setting has an `id` you are willing to keep for ever. It is the key the creator's content is stored under.
- Every default is a valid value for its type.
- The template reads every setting, and declares every setting it reads.
- Repeated content is blocks, each root carrying `data-block-id="{{ block.id }}"`.
- Colour comes from `scheme`, type from the theme, spacing from range settings.
- Laid out for a phone first, with container queries for wider. See [Styling](https://storelib.com/developers/styling#responsive).
- No fixed `id="…"`; build ids from `{{ section.id }}`.
- At least one preset, or the section is not offered in Add Section.

---

<!-- https://storelib.com/developers/blocks -->

# Blocks

A block is a repeatable child of a section: one question in an FAQ, one slide in a carousel, one logo in a strip, one tier on a pricing table. The section declares which block types it accepts and what settings each has. The creator then adds, removes, reorders, duplicates and hides blocks in the builder, and the section's author writes none of that.

**Repeated content is always blocks.** Never `question_1`, `question_2`, `question_3` as settings. Numbered settings cannot be reordered, cannot grow past the number somebody guessed, and leave an empty control in the panel for every one that is not used.

## Declaring blocks

In the schema, `blocks` lists the types this section accepts:

```json
"blocks": [
  {
    "type": "question",
    "name": "Question",
    "limit": 20,
    "settings": [
      { "type": "text", "id": "question", "label": "Question", "default": "What is your return policy?" },
      { "type": "richtext", "id": "answer", "label": "Answer", "default": "<p>Thirty days, no questions asked.</p>" }
    ]
  },
  { "type": "divider", "name": "Divider", "limit": 3, "settings": [] }
],
"max_blocks": 30
```

| Key | Meaning |
| --- | --- |
| `type` | Unique within the section and stable for ever, like a setting id. |
| `name` | What the builder calls it. |
| `settings` | The block's own settings, declared exactly like a section's. See [Schema](https://storelib.com/developers/schema). |
| `limit` | The most of this type one section may hold. |

`max_blocks` on the section caps the total across all types. Both limits are enforced by the builder and by the importer, under a hard ceiling:

| Limit | Most allowed |
| --- | --- |
| One section file | 512 KB |
| A section's CSS | 128 KB |
| A section's script | 64 KB |
| Settings in one section | 120 |
| Blocks in one section | 50 |
| Sections on one page | 60 |
| One asset | 15 MB |
| Files in a theme package | 2000 |
| A theme package | 50 MB |

A section with no `blocks` key has no block controls at all.

## Rendering blocks

`blocks` is the instance's blocks in order, each `{ id, type, settings }`, with the block definition's defaults applied and hidden blocks already left out.

```html
{% for block in blocks %}
  {% if block.type == "question" %}
    <details class="faq__item" name="{{ section.id }}-faq" data-block-id="{{ block.id }}">
      <summary>{{ block.settings.question }}</summary>
      <div class="faq__answer">{{ block.settings.answer | raw }}</div>
    </details>
  {% elsif block.type == "divider" %}
    <hr data-block-id="{{ block.id }}">
  {% endif %}
{% else %}
  {% if page.in_editor %}<p class="faq__empty">Add a question</p>{% endif %}
{% endfor %}
```

- **`data-block-id="{{ block.id }}"` on each block's root** is what lets the creator click a block in the canvas to select it. Leave it out and the block can only be reached through the panel.
- Read a block's settings as `block.settings.<id>`. The id must be declared on that block type, or the template does not compile.
- The `{% else %}` branch of a `for` runs when there are no blocks. Keep an empty-state prompt behind `page.in_editor`, so it helps the creator and never reaches a visitor.

## How blocks are stored

In the page, as an ordered list on the section instance. A block stores only the settings the creator changed.

```json
"blocks": [
  { "id": "blk_8f2a", "type": "question", "settings": { "question": "Do you ship abroad?" } },
  { "id": "blk_c31d", "type": "question", "settings": {} }
]
```

- A block id is minted when the block is created and never changes. Reordering changes the order of the list only; duplicating mints a new id for the copy.
- A block whose type the section no longer declares is **kept** with its settings and drawn by nothing. Updating a section never deletes content, so the creator can decide what to do with it.
- An exported theme writes blocks in the portable form, `"blocks": { "blk_8f2a": { … } }` with a separate `"block_order"` array, and import converts it back. You will only meet that form inside a `.storelib-theme` file.

## Presets fill a new section

A **preset** is what Add Section offers. One that adds blocks makes the section arrive finished rather than empty:

```json
"presets": [
  {
    "name": "FAQ",
    "blocks": [{ "type": "question" }, { "type": "question" }, { "type": "question" }]
  },
  {
    "name": "Short FAQ",
    "settings": { "heading": "Quick answers" },
    "blocks": [{ "type": "question" }, { "type": "question" }]
  }
]
```

Each preset block becomes a real block with a fresh id and the preset's settings, if it gives any, over the block's defaults. A preset that names a block type or a setting the section does not declare is a schema error. **A section with no presets is not offered in Add Section** at all; it can still be placed by code or by import.

## Products are shaped like blocks

`products` holds the creator's published products in the same `{ id, type, settings }` shape, so a card written for `blocks` works for `products` with nothing changed but the loop:

```html
{% for block in products %}
  <a class="card" href="{{ block.settings.url | url }}">
    {% if block.settings.image != "" %}<img src="{{ block.settings.image }}" alt="{{ block.settings.title }}">{% endif %}
    <span class="card__title">{{ block.settings.title }}</span>
    <span class="card__price">{{ block.settings.price }}</span>
  </a>
{% endfor %}
```

`price` arrives formatted, such as `$48.00`. Templates do not do money.

---

<!-- https://storelib.com/developers/schema -->

# Schema

The `<schema>` block is JSON. It says what the section is, what a creator can change about it, which blocks it may hold, and how Add Section offers it. **The builder's settings panel for a section is generated from its schema and nothing else.** There is no per-section panel code to write: declare a setting and its control appears.

```json
{
  "schema_version": 1,
  "type": "features",
  "name": "Features",
  "category": "Content",
  "version": "1.0.0",
  "settings": [
    { "type": "header", "id": "hdr_content", "label": "Content" },
    { "type": "text", "id": "heading", "label": "Heading", "default": "Why us" },
    { "type": "range", "id": "columns", "label": "Columns", "default": 3, "min": 1, "max": 4, "step": 1, "responsive": true },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "white" }
  ],
  "blocks": [
    {
      "type": "feature",
      "name": "Feature",
      "limit": 12,
      "settings": [
        { "type": "icon_picker", "id": "icon", "label": "Icon", "default": "star" },
        { "type": "text", "id": "title", "label": "Title", "default": "Fast shipping" },
        { "type": "textarea", "id": "text", "label": "Text", "default": "" }
      ]
    }
  ],
  "max_blocks": 12,
  "presets": [
    { "name": "Three features", "blocks": [{ "type": "feature" }, { "type": "feature" }, { "type": "feature" }] }
  ],
  "capabilities": []
}
```

## Top level

| Key | Required | Meaning |
| --- | --- | --- |
| `schema_version` | no, defaults to 1 | The schema format this file is written in. A file from a newer engine is refused rather than misread. |
| `type` | yes | The section type. Must equal the file name, `sections/<type>.storelib`. |
| `name` | yes | What the builder calls it. |
| `category` | no | Groups Add Section. |
| `description`, `icon` | no | Shown in Add Section. |
| `version` | no | The section's own version, which `migrations` refer to. |
| `settings` | yes | The settings, in panel order. |
| `blocks` | no | The block types this section accepts. See [Blocks](https://storelib.com/developers/blocks). |
| `max_blocks` | no | Cap across all block types. |
| `presets` | no | What Add Section offers. No presets means the section is not offered. |
| `allowed_templates`, `disabled_templates` | no | The pages it may be placed on, or may not. One or the other, never both. |
| `capabilities` | no | What the section may reach: `embed` for a player frame, and the script capabilities. See [JavaScript](https://storelib.com/developers/javascript#capabilities). |
| `migrations` | no | Setting renames across versions. See [Changing a section safely](#changing-a-section-safely). |
| `supports_color_overrides`, `supports_typography_overrides` | no | Which colour and type overrides the builder offers for this section. See [Styling](https://storelib.com/developers/styling). |

A key the engine does not recognise is kept and written back untouched. Nothing you add is stripped.

## A setting

| Key | Meaning |
| --- | --- |
| `type` | One of the control types below. Nothing else exists. |
| `id` | Lowercase letters, digits and `_`, starting with a letter, unique within the section. **Stable for ever**: it is the key the creator's content is stored under, so renaming one is a migration, not an edit. |
| `label` | What the panel shows. |
| `info` | A short line of help under the control. |
| `placeholder` | Shown in an empty text field. |
| `default` | Must be a valid value for the type. Omitted means the control's own fallback. |
| `options` | Required for `select` and `radio`: `[{ "label": "…", "value": "…" }]`. The default must be one of the values. |
| `min`, `max`, `step`, `unit` | For `range` and `number`. A range needs `min` and `max`, and `min` below `max`. |
| `responsive` | `true`, on a type that allows it, makes the value `{ desktop, tablet, mobile }`. |

`header`, `paragraph` and `divider` draw in the panel and hold no value. They take no default.

## Every control type

This list is generated from the builder's control registry, the same one the compiler validates against and the panel draws from. If a type is here, it exists; if it is not, it does not.

| Type | What it is | Holds | Responsive |
| --- | --- | --- | --- |
| `text` | A single line of text. | text | no |
| `textarea` | Several lines of plain text. | text | no |
| `richtext` | Formatted text. Stored as sanitised HTML; output with the `raw` filter. | text | no |
| `number` | A number typed in. | a number | yes |
| `toggle` | On or off. | true or false | no |
| `checkbox` | On or off, drawn as a checkbox. Prefer `toggle` for a single switch. | true or false | no |
| `select` | One of a list, drawn as a dropdown. | one of its options | no |
| `radio` | One of a short list, every option visible. | one of its options | no |
| `range` | A number on a slider. | a number | yes |
| `color` | A hex colour. | a hex colour | no |
| `color_scheme` | One of the theme's named colour schemes, by key: the built-in white, light, dark, black and highlight (Light, Soft, Dark, Brand and Accent in the editor) or one the creator added. The editor offers every scheme the theme has; see docs/theme/16-design-tokens.md. | one of its options | no |
| `font_picker` | A font family from the theme's font list. | text | no |
| `alignment` | Left, centre or right. | one of its options | yes |
| `image_picker` | One image from the media library. Stored as an asset reference, rendered as a URL. | an asset | no |
| `image_gallery` | Several images, in order. | a list of assets | no |
| `video_picker` | A video file from the media library, or a hosted video URL. | an asset | no |
| `file_picker` | Any file from the media library. | an asset | no |
| `icon_picker` | One icon from Storelib's icon library, by name. | text | no |
| `url` | Where something links to: a page of the site, a product, or any address. | text | no |
| `page_picker` | One of the site's pages, by key. | text | no |
| `product_picker` | One of the creator's products, by id. | text | no |
| `community_picker` | One of the creator's communities, by id. | text | no |
| `header` | A heading in the sidebar. Holds no value. | nothing; it only draws in the panel | no |
| `paragraph` | A line of help text in the sidebar. Holds no value. | nothing; it only draws in the panel | no |
| `divider` | A rule between groups of settings. Holds no value. | nothing; it only draws in the panel | no |

A working declaration of each of the 25 types:

```json
[
  {
    "type": "text",
    "id": "heading",
    "label": "Heading",
    "default": "Welcome"
  },
  {
    "type": "textarea",
    "id": "body",
    "label": "Body"
  },
  {
    "type": "richtext",
    "id": "content",
    "label": "Content"
  },
  {
    "type": "number",
    "id": "columns",
    "label": "Columns",
    "min": 1,
    "max": 6,
    "default": 3
  },
  {
    "type": "toggle",
    "id": "show_badge",
    "label": "Show badge",
    "default": true
  },
  {
    "type": "checkbox",
    "id": "agree",
    "label": "Require agreement"
  },
  {
    "type": "select",
    "id": "layout",
    "label": "Layout",
    "options": [
      {
        "label": "Centre",
        "value": "center"
      },
      {
        "label": "Split",
        "value": "split"
      }
    ],
    "default": "center"
  },
  {
    "type": "radio",
    "id": "style",
    "label": "Button style",
    "options": [
      {
        "label": "Filled",
        "value": "filled"
      },
      {
        "label": "Outline",
        "value": "outline"
      }
    ],
    "default": "filled"
  },
  {
    "type": "range",
    "id": "padding",
    "label": "Padding",
    "min": 0,
    "max": 160,
    "step": 4,
    "unit": "px",
    "default": 64,
    "responsive": true
  },
  {
    "type": "color",
    "id": "background",
    "label": "Background",
    "default": "#ffffff"
  },
  {
    "type": "color_scheme",
    "id": "scheme",
    "label": "Colour scheme",
    "default": "white"
  },
  {
    "type": "font_picker",
    "id": "font",
    "label": "Heading font",
    "default": "Inter"
  },
  {
    "type": "alignment",
    "id": "align",
    "label": "Align",
    "default": "center"
  },
  {
    "type": "image_picker",
    "id": "image",
    "label": "Image"
  },
  {
    "type": "image_gallery",
    "id": "images",
    "label": "Images",
    "max": 12
  },
  {
    "type": "video_picker",
    "id": "video",
    "label": "Background video"
  },
  {
    "type": "file_picker",
    "id": "download",
    "label": "Downloadable file"
  },
  {
    "type": "icon_picker",
    "id": "icon",
    "label": "Icon",
    "default": "zap"
  },
  {
    "type": "url",
    "id": "button_url",
    "label": "Button link",
    "default": "/shop"
  },
  {
    "type": "page_picker",
    "id": "page",
    "label": "Page"
  },
  {
    "type": "product_picker",
    "id": "product",
    "label": "Product"
  },
  {
    "type": "community_picker",
    "id": "community",
    "label": "Community"
  },
  {
    "type": "header",
    "id": "hdr_content",
    "label": "Content"
  },
  {
    "type": "paragraph",
    "id": "note",
    "content": "Shown above the fold on every page."
  },
  {
    "type": "divider",
    "id": "div_1"
  }
]
```

### Older type names

Early sections used different names for some types. They still validate and mean the same thing, but new sections should use the names above.

| Older name | Means |
| --- | --- |
| `link` | `url` |
| `image` | `image_picker` |
| `video` | `video_picker` |
| `icon` | `icon_picker` |
| `font` | `font_picker` |
| `spacing` | `range` |

## How a value is resolved

A page stores only what the creator changed. Everything else is decided in one order, every time a section renders:

```text
resolved = saved value  ??  schema default  ??  control fallback
```

For a block setting, the block's saved value comes first, then the block definition's default, then the fallback. The theme is not a step in this chain: it provides tokens that a template reads directly, and never overrides a setting by name.

**Responsive values** arrive as `{ desktop, tablet, mobile }`, filled downwards. Set desktop only and tablet and mobile inherit it.

```json
saved:    { "columns": { "desktop": 4, "mobile": 1 } }
resolved: { "columns": { "desktop": 4, "tablet": 4, "mobile": 1 } }
```

Read one breakpoint in the template as `{{ settings.columns.desktop }}`, or pass all three to CSS as custom properties and pick with container queries.

**Saving strips defaults.** A value equal to the default is not stored, and a responsive value equal at every breakpoint collapses to a plain one. That keeps pages small, and it is why changing a default reaches every instance that never overrode it.

## Assets

An image, video, file or gallery setting holds an **asset reference**, `asset://<sha256>`, never a URL. By the time the template runs, the reference has been turned into the URL this account serves the file from, so you print it directly:

```html
{% if settings.image != "" %}
  <img src="{{ settings.image }}" alt="{{ settings.image_alt }}" width="1200" height="800">
{% endif %}
```

A reference held anywhere else goes through the `asset` filter: `{{ block.settings.clip | asset }}`. A reference the account does not have resolves to an empty string, so an empty image means "no image chosen", never an error. Because no stored page knows where bytes live, a theme moves between accounts and storage can change without a page being touched.

## Changing a section safely

Setting ids and block types are the contract between a section file and every page that uses it. An update may freely:

- add settings and block types; existing instances get the defaults,
- change defaults; instances that never overrode them follow,
- change markup and CSS.

It must not rename or remove an id without saying so. Declare the rename and the old value is read under the new name:

```json
"version": "1.1.0",
"migrations": [
  { "from": "title", "to": "heading", "since": "1.1.0" }
]
```

A removed setting's saved value is kept as an unknown key, so putting the setting back restores it.

## What the validator refuses

Each refusal names the path, such as `settings[3].default`, and the line in the file:

- a `type` that is not a control type, listing the ones that are,
- a bad or duplicate `id`,
- `options` missing on a `select` or `radio`, or a default that is not among them,
- a default of the wrong type, such as `default "big" is not a range`,
- `responsive` on a type that cannot be,
- a `range` without `min` and `max`, or with `min` not below `max`,
- a preset that sets a setting or adds a block the section does not declare,
- a block type declared twice,
- both `allowed_templates` and `disabled_templates`,
- a `schema_version` newer than the engine,
- more settings than the limit.

---

<!-- https://storelib.com/developers/styling -->

# Styling

A section's `<style>` applies to that section's instances and nothing else. Two sections that both declare `.title` do not fight, and one section cannot restyle the page around it. You do not write the scope and you cannot escape it: the compiler adds it.

## What scoping does

Given this in a section of type `hero`:

```css
.hero { padding: 64px 0; }
h1 { font-size: 48px; }
:root { --gap: 16px; }
@keyframes rise { from { translate: 0 8px; opacity: 0 } to { translate: 0; opacity: 1 } }
.hero h1 { animation: rise 400ms ease-out; }
```

the compiler emits

```css
[data-section-id="sec_9k2m"] .hero { padding: 64px 0; }
[data-section-id="sec_9k2m"] h1 { font-size: 48px; }
[data-section-id="sec_9k2m"] { --gap: 16px; }
@keyframes sl-hero-rise { … }
[data-section-id="sec_9k2m"] .hero h1 { animation: sl-hero-rise 400ms ease-out; }
```

- Every selector is prefixed with the instance, inside `@media`, `@supports` and `@container` too.
- `html`, `body` and `:root` are rewritten to mean the section's root. A rule written against them does not do what it looks like it does, so do not write them.
- `@keyframes` names are prefixed with the section type, and every `animation` that uses one is rewritten to match.
- `@import` is refused. A stylesheet cannot fetch anything.
- Global rules, such as resets and font faces, belong only in `layout/theme.storelib`.

## Settings in CSS

A rule can read a setting with the same `{{ }}` the template uses. The value is made safe for a stylesheet: braces and angle brackets are removed, because no legitimate CSS value holds one.

```css
.hero { padding-top: {{ settings.padding_top }}px; }
```

For anything that differs per instance, prefer a custom property set in the markup and a static rule that reads it. The stylesheet is then identical for every instance and cached once:

```html
<section class="hero" style="--hero-pt: {{ settings.padding_top }}px; --hero-pb: {{ settings.padding_bottom }}px">
```

```css
.hero { padding: var(--hero-pt) 24px var(--hero-pb); }
```

**Padding and spacing are settings.** Declare them as `range` settings with `"unit": "px"`, never as fixed numbers in the CSS, so a creator can tighten or loosen a section without asking for new code.

## Responsive

**Use container queries, not media queries.** A section is as wide as the column it sits in, and in the builder's phone preview that is not the width of the window. `@media (max-width: 640px)` asks about the window, so a section built on it looks right on a phone and wrong in the preview, or the other way round. A container query asks about the section itself, and is right in both.

Put `container-type: inline-size` on the outermost element, write the phone layout as the base rules, then widen:

```css
.grid { container-type: inline-size; }
.grid__items { display: grid; gap: 16px; grid-template-columns: 1fr; }

@container (min-width: 640px) {
  .grid__items { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}
@container (min-width: 1024px) {
  .grid__items { grid-template-columns: repeat(var(--cols, 3), minmax(0, 1fr)); }
}
```

A section must never scroll sideways. `minmax(0, 1fr)` instead of `1fr`, `min-width: 0` on flex children, and `overflow-wrap: anywhere` on long headings are what stop it.

The one place `@media` is right is **the visitor's own motion setting**, which is about them rather than about width:

```css
.card { transition: transform 200ms ease; }
.card:hover { transform: translateY(-2px); }
@media (prefers-reduced-motion: reduce) {
  .card { transition: none; }
  .card:hover { transform: none; }
}
```

## Colour schemes

A section does not choose colours. It chooses a **colour scheme**, and the creator decides what the scheme looks like in Theme settings. Change a scheme and every section on it changes, at once, in the builder and on the live site.

Declare a `color_scheme` setting, then read the scheme. In CSS, read the custom properties the renderer sets on the section's root. In the template, read `scheme.<key>`.

| In a template | In CSS |
| --- | --- |
| `scheme.background` | `var(--scheme-background)` |
| `scheme.background_secondary` | `var(--scheme-background-secondary)` |
| `scheme.text` | `var(--scheme-text)` |
| `scheme.text_muted` | `var(--scheme-text-muted)` |
| `scheme.heading` | `var(--scheme-heading)` |
| `scheme.accent` | `var(--scheme-accent)` |
| `scheme.link` | `var(--scheme-link)` |
| `scheme.border` | `var(--scheme-border)` |
| `scheme.primary_button_background` | `var(--scheme-button-primary)` |
| `scheme.primary_button_text` | `var(--scheme-button-primary-text)` |
| `scheme.primary_button_border` | `var(--scheme-button-primary-border)` |
| `scheme.secondary_button_background` | `var(--scheme-button-secondary)` |
| `scheme.secondary_button_text` | `var(--scheme-button-secondary-text)` |
| `scheme.secondary_button_border` | `var(--scheme-button-secondary-border)` |
| `scheme.input_background` | `var(--scheme-input)` |
| `scheme.input_text` | `var(--scheme-input-text)` |
| `scheme.input_border` | `var(--scheme-input-border)` |

```css
.card { background: var(--scheme-background-secondary); border: 1px solid var(--scheme-border); }
.card__title { color: var(--scheme-heading); }
.card__body { color: var(--scheme-text); }
.button { background: var(--scheme-button-primary); color: var(--scheme-button-primary-text); }
```

Five schemes are built in. Their keys are `white`, `light`, `dark`, `black` and `highlight`, shown to the creator as Light, Soft, Dark, Brand and Accent; a creator can rename them and add more. Renaming changes the name, never the key.

**Never hard-code a hex value the scheme already answers.** A hard-coded colour stops responding to the creator's theme, and on a dark scheme it is usually unreadable. Before publishing a new section, switch it between a light and a dark scheme in the builder and read it on both. The builder's AI reviews contrast in what it writes; the code editor does not do it for you.

### A section's own colour overrides

Behind **Advanced colors** in the builder, a creator can override a few of a section's colours without leaving the scheme. The override is applied on top of the scheme by the renderer, so your CSS keeps reading the same variables. Say which slots your section allows:

```json
"supports_color_overrides": ["background", "heading", "text"]
```

`true` offers every slot, `false` offers none. When the schema has a `color_scheme` setting and says nothing, every slot is offered.

## Type

The theme has three font roles and nine text styles, each with its own size at desktop, tablet and phone width, weight, line height, letter spacing and case.

| Style | Key |
| --- | --- |
| Heading 1 | `h1` |
| Heading 2 | `h2` |
| Heading 3 | `h3` |
| Heading 4 | `h4` |
| Body large | `body_large` |
| Body | `body` |
| Body small | `body_small` |
| Button | `button` |
| Caption | `caption` |

Font roles: `heading`, `body`, `accent`. A section's heading style is one of `h1`, `h2`, `h3`, `h4` or `custom`; its body style is `body`, `body_large`, `body_small` or `custom`.

A section chooses a heading style and a body style, and the theme turns the choice into custom properties on the section root. Read them, with a fallback for when nothing was chosen:

```css
.hero__title {
  font-family: var(--theme-font-heading), ui-sans-serif, system-ui, sans-serif;
  font-size: var(--section-heading-size, 32px);
  line-height: var(--section-heading-line-height, 1.15);
  font-weight: var(--section-heading-weight, 700);
  letter-spacing: var(--section-heading-tracking, -0.01em);
  text-transform: var(--section-heading-transform, none);
}
.hero__lead {
  font-size: var(--section-text-size, 17px);
  line-height: var(--section-text-line-height, 1.6);
}
```

Name a font family inside a section only as a fallback after the theme's variable. The tablet and phone sizes take over inside the section's own container, so the builder's phone preview draws phone sizes.

Set `"supports_typography_overrides": false` on a section that has its own size control, such as a hero with a heading size slider, so the builder does not offer two controls for one thing.

## Layout conventions

These are what the library's thirty sections do, and what makes a new section sit beside them without looking out of place:

```css
.s__in {
  margin: 0 auto;
  max-width: var(--theme-page-width, 1280px);
  padding-inline: var(--theme-padding-x, 24px);
}
```

- Page width and side padding come from the theme, through `--theme-page-width` and `--theme-padding-x`.
- Corner radius comes from the theme's tokens: `{{ theme.radius.medium }}px`.
- Vertical rhythm is the section's own `padding_top` and `padding_bottom` range settings.

---

<!-- https://storelib.com/developers/javascript -->

# JavaScript and forms

## Status: scripts run, in a sandbox

A section's `<script>` block is compiled and checked when the file is saved, and **run on the page, and in the builder, inside a sandbox**. It works for sliders that advance, counters, tabs with custom behaviour, and anything else built from listeners, classes, styles and text.

**Prefer HTML and CSS where they do the job alone.** They work before any script has loaded, they are faster, and they come with keyboard support. The patterns in the next part cover accordions, tabs, carousels, pop-ups and motion with no script at all. Reach for a script for what they cannot do: autoplay, a counter, a slider's dots.

### How the sandbox works

A section's script does not run in the page it is on. That page may have a visitor who is signed in, has a cart, or is halfway through a checkout, and a section's code is written by whoever wrote the section. So it runs in one hidden `<iframe sandbox="allow-scripts">` per page, whose origin is opaque: it cannot read the visitor's cookies, storage or session, and it cannot see the page.

Inside, `root` is **a copy of your section's own markup**, in a real document. `querySelector`, `classList`, `addEventListener`, `style` and `textContent` all work the ordinary way. Every change you make to the copy is sent to the page, checked, and applied to the real section. Every click, key and input on the real section is sent to the copy, so your listeners run.

| Crosses to the page | Does not |
| --- | --- |
| Classes, `hidden`, `open`, `aria-*`, `data-*`, and the other attributes that describe rather than load | `src`, `href`, `action`, `on*` and anything else that loads or runs something |
| Style properties, one at a time | A style value with `url(`, `expression(`, `javascript:` or a backslash |
| Text of an element that holds only text | Markup. Text arrives as text, never as HTML |
| Scrolling, through `storelib.scrollTo` | Adding or removing elements |
|  | Measurements. The copy is not laid out, so `getBoundingClientRect` and `offsetWidth` return 0 |

**Show and hide what the template drew.** A script cannot add an element, because the page's copy belongs to the renderer and would be put back. Draw every slide, message or panel in the template, and switch between them with `hidden` or a class.

**Scroll with `storelib.scrollTo`.** Setting `scrollLeft` changes the copy, which is not what the visitor sees:

```js
storelib.scrollTo(track, { left: slideWidth * index, behavior: "smooth" })
```

**Know where you are.** `storelib.inEditor` is `true` in the builder's canvas, so an autoplaying slider can hold still while somebody is designing it.

A script that throws stops on its own, and the section keeps whatever it had drawn. A script that changes the page thousands of times a second is stopped.

## Interaction without script

### Accordion

`<details>` and `<summary>` are an accordion with no script, keyboard support included. Give several the same `name` and opening one closes the others. Build the name from `section.id` so two FAQ sections on one page stay independent.

```html
{% for block in blocks %}
  <details class="faq__item" name="{{ section.id }}-faq" data-block-id="{{ block.id }}">
    <summary class="faq__q">{{ block.settings.question }}</summary>
    <div class="faq__a">{{ block.settings.answer | raw }}</div>
  </details>
{% endfor %}
```

```css
.faq__q { cursor: pointer; list-style: none; padding: 18px 0; font-weight: 600; }
.faq__q::-webkit-details-marker { display: none; }
.faq__q::after { content: "+"; float: right; transition: transform 200ms ease; }
.faq__item[open] .faq__q::after { transform: rotate(45deg); }
```

### Tabs

Radio inputs sharing a name, each followed by its label and panel. `order` puts the labels in a row and the panels beneath them; `:checked` shows the chosen one.

```html
<div class="tabs">
  {% for block in blocks %}
    <input class="tabs__radio" type="radio" name="{{ section.id }}-tab" id="{{ section.id }}-{{ block.id }}"{% if forloop.first %} checked{% endif %}>
    <label class="tabs__label" for="{{ section.id }}-{{ block.id }}" data-block-id="{{ block.id }}">{{ block.settings.title }}</label>
    <div class="tabs__panel">{{ block.settings.content | raw }}</div>
  {% endfor %}
</div>
```

```css
.tabs { display: flex; flex-wrap: wrap; }
.tabs__radio { position: absolute; opacity: 0; pointer-events: none; }
.tabs__label { order: 0; padding: 10px 16px; cursor: pointer; border-bottom: 2px solid transparent; color: var(--scheme-text); }
.tabs__panel { order: 1; width: 100%; display: none; padding-top: 20px; }
.tabs__radio:checked + .tabs__label { border-color: var(--scheme-accent); color: var(--scheme-heading); }
.tabs__radio:checked + .tabs__label + .tabs__panel { display: block; }
.tabs__radio:focus-visible + .tabs__label { outline: 2px solid var(--scheme-accent); outline-offset: 2px; }
```

### Carousel

A row that scrolls sideways and snaps to each slide. It swipes on a phone, scrolls with a trackpad and a keyboard, and needs no script.

```css
.slides {
  display: flex; gap: 16px;
  overflow-x: auto; overscroll-behavior-x: contain;
  scroll-snap-type: x mandatory; scrollbar-width: none;
}
.slides::-webkit-scrollbar { display: none; }
.slide { flex: 0 0 85%; scroll-snap-align: start; }
@container (min-width: 768px) { .slide { flex-basis: calc((100% - 32px) / 3); } }
```

### Pop-up

The `popover` attribute gives a panel the browser opens, closes and dismisses, with Escape and a tap outside, and no script.

```html
<button class="more" popovertarget="{{ section.id }}-details">Size guide</button>
<div class="sheet" popover id="{{ section.id }}-details">
  {{ settings.size_guide | raw }}
  <button popovertarget="{{ section.id }}-details" popovertargetaction="hide">Close</button>
</div>
```

### Motion

CSS transitions and `@keyframes`, on `opacity` and `transform`, which are cheap to animate. Height from `0` to `auto` does not transition; animate `grid-template-rows` from `0fr` to `1fr` instead. Every animation stops for a visitor who has asked for reduced motion; see [Styling](https://storelib.com/developers/styling#responsive).

## Forms

**An email box on a Storelib site collects emails for that site's creator.** A form in a section is submitted by the page that hosts it, not by a script, and every address lands in the creator's Subscribers, where their welcome email and automations pick it up. The section's author wires nothing, and the creator sets nothing up.

```html
<form class="signup" data-storelib-form="subscribe">
  <label class="signup__label" for="{{ section.id }}-email">Email</label>
  <input id="{{ section.id }}-email" type="email" name="email" required autocomplete="email" placeholder="you@example.com">
  <button type="submit">{{ settings.button_text }}</button>
  <p class="signup__done" data-storelib-success hidden>{{ settings.success_message }}</p>
</form>
```

### How the page decides what a form means

| The form has | It is |
| --- | --- |
| `data-storelib-form="subscribe"` | Sent to the creator's Subscribers. Saying so explicitly always wins. |
| `data-storelib-form="native"` | Left to the browser, action and all. |
| No attribute, no `action`, and an `<input type="email">` | Sent to the creator's Subscribers. This is the default, so a sign-up box works even when its author did not say. |
| No attribute and a real `action` | Left to the browser, such as a search box posting to `/search`. |
| Anything else | Stopped, so a form with nowhere to go does not reload the page. |

The email is read from the form's `<input type="email">`, and an optional name from `name="name"`.

### States

While it sends, the form carries `data-state="sending"` and its buttons are disabled. It then carries `data-state="done"` or `data-state="error"`, so your CSS can style each:

```css
.signup[data-state="sending"] button { opacity: 0.6; }
.signup[data-state="error"] input { border-color: #b91c1c; }
```

On success, an element inside the form marked `data-storelib-success` is shown and the rest of the form is hidden. Without one, a plain "Thanks, you're on the list." is shown instead. On error, the reason is shown under the form, which stays filled in so nobody has to type their address again.

### In the builder

Nothing is sent from the builder's canvas. A sign-up form there shows its success state with the line "Sign-ups go to Subscribers on your live site", because designing a page is not signing up to it.

### Sending to another mailing service

To post to Mailchimp, Kit, Buttondown or anything else instead, give the form that service's `action` and mark it native. A setting lets the creator choose:

```html
<form method="post"
  action="{% if settings.list_url %}{{ settings.list_url | url }}{% endif %}"
  data-storelib-form="{% if settings.list_url %}native{% else %}subscribe{% endif %}">
```

### Consent

A sign-up form is a request to be emailed, and the platform records where on the page it was given. A **contact** form is not: somebody asking a question has not agreed to a mailing list. Never make a contact form add its sender to Subscribers. Offer an unticked "Keep me updated" checkbox instead, and add the sender only when it was ticked.

Sign-ups are rate limited per visitor and per address, so a script cannot fill a creator's list.

## Embeds

An `<iframe>` hands part of the page to somebody else's code, so a section does not get one by asking. It declares the `embed` capability, and every frame takes its address from the `embed` filter:

```json
"capabilities": ["embed"]
```

```html
{% if settings.video_url != "" %}
  <iframe class="player" src="{{ settings.video_url | embed }}" title="{{ settings.video_title }}"
    loading="lazy" allow="autoplay; encrypted-media; picture-in-picture" allowfullscreen></iframe>
{% endif %}
```

```css
.player { display: block; width: 100%; aspect-ratio: 16 / 9; border: 0; border-radius: {{ theme.radius.medium }}px; }
```

The filter turns what people actually paste, a `youtu.be` link, a `watch?v=` link, a Vimeo page, into the player's address, and returns an empty string for everything else. A setting therefore cannot point a frame at an arbitrary site, whatever somebody types into it. It answers for:

- `youtube.com`
- `youtube-nocookie.com`
- `youtu.be`
- `vimeo.com`
- `player.vimeo.com`
- `open.spotify.com`
- `w.soundcloud.com`

YouTube links are served from `youtube-nocookie.com`. An `<iframe>` without the capability, or whose `src` comes from anywhere but the filter, is refused when the file is saved.

## The scripting API

The script is wrapped as a function and handed six things:

```js
"use strict";
(function (root, settings, blocks, theme, page, storelib) {
  // your <script> block
})
```

| Name | What it is |
| --- | --- |
| `root` | A copy of this instance's markup, in the sandbox. Query inside it; it is the whole of the page the script can see. |
| `settings`, `blocks`, `theme`, `page` | The same resolved data the template rendered from, as plain objects. |
| `storelib` | The platform API: `scrollTo`, `inEditor`, `capabilities`, and whatever the section's declared capabilities add. |

A slider that advances on its own and on a click. Every slide is in the template; the script only chooses which one shows. It declares `"capabilities": ["timers"]` for `setInterval`:

```js
const slides = root.querySelectorAll(".slide")
const dots = root.querySelectorAll(".dot")
let current = 0
function show(i) {
  current = (i + slides.length) % slides.length
  slides.forEach((el, j) => el.toggleAttribute("hidden", j !== current))
  dots.forEach((el, j) => el.classList.toggle("is-on", j === current))
}
root.querySelector("[data-next]")?.addEventListener("click", () => show(current + 1))
root.querySelector("[data-prev]")?.addEventListener("click", () => show(current - 1))
dots.forEach((el, j) => el.addEventListener("click", () => show(j)))
show(0)
if (!storelib.inEditor && settings.autoplay) setInterval(() => show(current + 1), settings.interval * 1000)
```

### What a script cannot name

These are refused by name when the file is saved. The check skips strings, comments and property access, so `"window"` in a string and `obj.window` are fine; only the bare name is refused.

`window`, `document`, `globalThis`, `self`, `top`, `parent`, `frames`, `opener`, `eval`, `Function`, `import`, `require`, `WebAssembly`, `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, `navigator`, `sendBeacon`, `localStorage`, `sessionStorage`, `indexedDB`, `cookie`, `location`, `history`, `postMessage`, `Worker`, `SharedWorker`, `ServiceWorker`, `setTimeout`, `setInterval`, `requestAnimationFrame`, `queueMicrotask`

Querying inside `root`, never the document, is also what makes a section safe to place twice on one page.

### Capabilities

A section declares what it needs in its schema, and the builder shows the creator what each section has been granted. Everything a capability exposes goes to Storelib's own endpoints for that site; a section never gets an arbitrary host.

| Capability | Grants | Works today |
| --- | --- | --- |
| `navigation` | `storelib.navigate(path)`: go to a page of this site. A path starting with one `/` only; the builder's canvas ignores it. | yes |
| `commerce` | `storelib.cart.add(variantId, quantity)` and `storelib.cart.get()`. Declaring it is accepted; the functions are not on `storelib` yet. | not yet |
| `analytics` | `storelib.analytics.track(event, props)`. Declaring it is accepted; the function is not on `storelib` yet. | not yet |
| `forms` | `storelib.forms.submit(name, fields)`, not on `storelib` yet. A sign-up form needs no script and no capability at all; see Forms. | not yet |
| `timers` | The names `setTimeout`, `setInterval` and `requestAnimationFrame`. | yes |
| `embed` | One `<iframe>` whose `src` comes from the `embed` filter. This is markup, not script, so it works today. | yes |

An unknown capability is refused, listing the ones that exist. A script is limited in size:

| Limit | Most allowed |
| --- | --- |
| One section file | 512 KB |
| A section's CSS | 128 KB |
| A section's script | 64 KB |
| Settings in one section | 120 |
| Blocks in one section | 50 |
| Sections on one page | 60 |
| One asset | 15 MB |
| Files in a theme package | 2000 |
| A theme package | 50 MB |

---

<!-- https://storelib.com/developers/selling -->

# Selling: products, checkout and payments

A Storelib website sells the creator's products, and the part that takes the money is Storelib's, not the section's. A section shows products and sends a buyer to checkout. It never takes a payment, never asks for a card, and never loads a payment script. This page is what a section, and whoever writes it, needs to know about that.

## Products reach a section as `products`

`products` holds the creator's published products, newest first, up to 24, in the same `{ id, type, settings }` shape as blocks:

| Field | What it is |
| --- | --- |
| `block.id` | The product's id. Checkout takes it. |
| `block.settings.title` | Its name. |
| `block.settings.price` | Its price, already formatted, such as `$48.00`. Empty when it costs nothing: write "Free" in the template if you show one. |
| `block.settings.compare_price` | The price before a sale, formatted, or empty. Show it struck through. |
| `block.settings.image` | Its main picture, or empty. |
| `block.settings.url` | Its page on this website, such as `/products/preset-pack`. |
| `block.settings.tag` | `Sold out` when there are none left, or empty. |

Templates do not do money: never compute, round or convert a price. Show the text you are given.

## Two ways to sell from a section

**Link to the product's page.** Every product has a page on the website with its pictures, its description and the Buy and Add to cart buttons, which already work. This is the right link for a card in a grid.

```html
{% for block in products %}
  <a class="card" href="{{ block.settings.url | url }}">
    {% if block.settings.image != "" %}<img src="{{ block.settings.image }}" alt="{{ block.settings.title }}">{% endif %}
    <span class="card__title">{{ block.settings.title }}</span>
    <span class="card__price">
      {% if block.settings.compare_price != "" %}<s>{{ block.settings.compare_price }}</s>{% endif %}
      {{ block.settings.price }}
    </span>
  </a>
{% endfor %}
```

**Link straight to checkout.** For a section whose job is the purchase, a hero with one product or a pricing table, send the buyer to Storelib checkout with the product's id:

```html
<a class="buy" href="/checkout?productId={{ block.id }}&src=website">Buy {{ block.settings.title }}</a>
```

`src=website` is how the order is recorded as a Website order in the creator's Orders. Keep it.

Do not link to checkout for a product that is `Sold out`. Show the tag instead.

## What checkout does

- It is Storelib's page, at storelib.com, where the buyer is signed in. On a website's own address, `/checkout` goes there.
- The buyer pays by card or Google Pay, through Stripe. Every price is charged in US dollars.
- **The price is read from the product, never from the link or the page.** Nothing a section writes can change what is charged.
- A buyer who already owns a product is not charged for it again.
- After paying, a digital product is in the buyer's Storelib library straight away, and the download link is emailed to them.
- The money goes to the creator's connected Stripe account, set up in Settings › Payments.

## The cart

A website has a cart. The header's bag opens it, the product page's **Add to cart** fills it, and `/cart` shows it and sends it to checkout as one payment. It is kept in the visitor's browser, per shop. A section cannot add to it: link to the product's page, where the button is.

## What a section may not do

- Build a payment form, or ask for a card number, a bank account or a password. Ever.
- Load Stripe, PayPal or any other payment or tracking script. A `<script>` tag in a template is refused when the file is saved, and a section's own script runs in a sandbox where `fetch` and the network are refused too.
- Put a price in a default, or invent a product, a discount or a review. Show the products the site has.
- Promise delivery times, refunds or guarantees the creator has not written. Those belong on the policy pages, which the creator edits.

## Where this lives in the builder

- **Website Settings › Commerce** shows how many products the website can show, what checkout takes and where payouts go.
- **Website Settings › Policies** has the refund, privacy and terms pages every website links to from its footer.
- A connected agent reads the site's products, with their ids, from `storelib_site`. See [Building with AI agents](https://storelib.com/developers/ai).

---

<!-- https://storelib.com/developers/examples -->

# Examples

Six complete sections. Each is a real `.storelib` file that the test suite compiles, and runs through the same quality checks the builder applies to AI-written sections, on every change to the platform. If one of these stopped compiling, the change that broke it would not ship. Copy any of them into the code editor as `sections/<type>.storelib` and it works as shown.

Every example follows the same conventions, which are the library's own:

- The root reads the colour scheme with `data-scheme="{{ settings.color_scheme }}"`, and every colour comes from a `--scheme-*` variable.
- Spacing is two `range` settings, passed to CSS as custom properties on the root.
- `container-type: inline-size` on the root, a phone layout as the base, and `@container` for wider.
- Ids are built from `{{ section.id }}`, so each section can appear on a page twice.
- Anything that moves stops under `prefers-reduced-motion`.
- Empty states sit behind `page.in_editor`.

## Sign-up card

A sign-up box that sends every address to the creator's Subscribers with no script and no setup. Shows the explicit `data-storelib-form="subscribe"`, a success message the creator can edit, a visually hidden label, and a form that stacks on a phone and sits in one row wider. See [Forms](https://storelib.com/developers/javascript#forms).

sections/signup_card.storelib

```html
<template>
<section class="su" data-scheme="{{ settings.color_scheme }}" style="--su-pt: {{ settings.padding_top }}px; --su-pb: {{ settings.padding_bottom }}px;">
  <div class="su__card">
    {% if settings.heading != "" %}<h2 class="su__h">{{ settings.heading }}</h2>{% endif %}
    {% if settings.text != "" %}<p class="su__p">{{ settings.text }}</p>{% endif %}
    <form class="su__form" data-storelib-form="subscribe">
      <label class="su__label" for="{{ section.id }}-email">Email address</label>
      <input class="su__input" id="{{ section.id }}-email" type="email" name="email" required autocomplete="email" placeholder="{{ settings.placeholder }}">
      <button class="su__btn" type="submit">{{ settings.button_text }}</button>
      <p class="su__done" data-storelib-success hidden>{{ settings.success_message }}</p>
    </form>
  </div>
</section>
</template>

<style>
.su { container-type: inline-size; background: var(--scheme-background); padding: var(--su-pt) var(--theme-padding-x, 24px) var(--su-pb); }
.su__card { max-width: 560px; margin: 0 auto; text-align: center; }
.su__h { margin: 0; color: var(--scheme-heading); font-size: var(--section-heading-size, 28px); line-height: var(--section-heading-line-height, 1.2); }
.su__p { margin: 12px 0 0; color: var(--scheme-text); font-size: var(--section-text-size, 16px); line-height: 1.6; }
.su__form { display: flex; flex-direction: column; gap: 10px; margin-top: 24px; }
.su__label { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
.su__input { min-width: 0; padding: 13px 16px; font: inherit; font-size: 16px; color: var(--scheme-input-text); background: var(--scheme-input); border: 1px solid var(--scheme-input-border); border-radius: {{ theme.radius.medium }}px; }
.su__btn { padding: 13px 22px; font: inherit; font-size: 15px; font-weight: 600; cursor: pointer; color: var(--scheme-button-primary-text); background: var(--scheme-button-primary); border: 1px solid var(--scheme-button-primary-border); border-radius: {{ theme.radius.medium }}px; }
.su__form[data-state="sending"] .su__btn { opacity: 0.6; }
.su__done { margin: 0; color: var(--scheme-heading); font-weight: 600; }
@container (min-width: 520px) {
  .su__form { flex-direction: row; }
  .su__input { flex: 1; }
}
</style>

<schema>
{
  "type": "signup_card",
  "name": "Sign-up card",
  "category": "Marketing",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Get the next drop first" },
    { "type": "textarea", "id": "text", "label": "Text", "default": "One email when something new is ready. Nothing else." },
    { "type": "text", "id": "placeholder", "label": "Placeholder", "default": "you@example.com" },
    { "type": "text", "id": "button_text", "label": "Button", "default": "Notify me" },
    { "type": "text", "id": "success_message", "label": "After signing up", "default": "You're on the list." },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "light" },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" },
    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" }
  ],
  "presets": [{ "name": "Sign-up card" }]
}
</schema>
```

## FAQ, one open at a time

Blocks, a `richtext` answer printed with `raw`, and `<details>` elements sharing a `name` so opening one closes the others, all without script.

sections/faq_exclusive.storelib

```html
<template>
<section class="fq" data-scheme="{{ settings.color_scheme }}" style="--fq-pt: {{ settings.padding_top }}px; --fq-pb: {{ settings.padding_bottom }}px;">
  <div class="fq__in">
    {% if settings.heading != "" %}<h2 class="fq__h">{{ settings.heading }}</h2>{% endif %}
    {% for block in blocks %}
      <details class="fq__item" name="{{ section.id }}-faq" data-block-id="{{ block.id }}">
        <summary class="fq__q">{{ block.settings.question }}</summary>
        <div class="fq__a">{{ block.settings.answer | raw }}</div>
      </details>
    {% else %}
      {% if page.in_editor %}<p class="fq__empty">Add a question from the panel.</p>{% endif %}
    {% endfor %}
  </div>
</section>
</template>

<style>
.fq { container-type: inline-size; background: var(--scheme-background); padding: var(--fq-pt) var(--theme-padding-x, 24px) var(--fq-pb); }
.fq__in { max-width: 760px; margin: 0 auto; }
.fq__h { margin: 0 0 24px; color: var(--scheme-heading); font-size: var(--section-heading-size, 32px); line-height: var(--section-heading-line-height, 1.15); }
.fq__item { border-bottom: 1px solid var(--scheme-border); }
.fq__q { display: flex; justify-content: space-between; gap: 16px; padding: 18px 0; cursor: pointer; list-style: none; color: var(--scheme-heading); font-weight: 600; }
.fq__q::-webkit-details-marker { display: none; }
.fq__q::after { content: "+"; flex: none; transition: transform 200ms ease; }
.fq__item[open] .fq__q::after { transform: rotate(45deg); }
.fq__a { padding: 0 0 18px; color: var(--scheme-text); line-height: 1.6; }
.fq__a > :first-child { margin-top: 0; }
.fq__empty { color: var(--scheme-text-muted); }
@media (prefers-reduced-motion: reduce) { .fq__q::after { transition: none; } }
</style>

<schema>
{
  "type": "faq_exclusive",
  "name": "FAQ, one open at a time",
  "category": "Content",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Questions" },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "white" },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 72, "min": 0, "max": 200, "step": 4, "unit": "px" },
    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "default": 72, "min": 0, "max": 200, "step": 4, "unit": "px" }
  ],
  "blocks": [
    {
      "type": "question",
      "name": "Question",
      "limit": 30,
      "settings": [
        { "type": "text", "id": "question", "label": "Question", "default": "How long does delivery take?" },
        { "type": "richtext", "id": "answer", "label": "Answer", "default": "<p>Most orders arrive within three working days.</p>" }
      ]
    }
  ],
  "max_blocks": 30,
  "presets": [
    { "name": "FAQ", "blocks": [{ "type": "question" }, { "type": "question" }, { "type": "question" }] }
  ]
}
</schema>
```

## Logo strip

Image blocks that fall back to a text name, a row that swipes on a phone with scroll snapping, and wraps into a centred row once there is room.

sections/logo_strip.storelib

```html
<template>
<section class="lg" data-scheme="{{ settings.color_scheme }}" style="--lg-pt: {{ settings.padding_top }}px; --lg-pb: {{ settings.padding_bottom }}px;">
  <div class="lg__in">
    {% if settings.heading != "" %}<p class="lg__h">{{ settings.heading }}</p>{% endif %}
    <ul class="lg__row">
      {% for block in blocks %}
        <li class="lg__item" data-block-id="{{ block.id }}">
          {% if block.settings.logo != "" %}
            {% if block.settings.link != "" %}
              <a href="{{ block.settings.link | url }}"><img class="lg__img" src="{{ block.settings.logo }}" alt="{{ block.settings.name }}" width="160" height="64" loading="lazy"></a>
            {% else %}
              <img class="lg__img" src="{{ block.settings.logo }}" alt="{{ block.settings.name }}" width="160" height="64" loading="lazy">
            {% endif %}
          {% else %}
            <span class="lg__name">{{ block.settings.name }}</span>
          {% endif %}
        </li>
      {% endfor %}
    </ul>
  </div>
</section>
</template>

<style>
.lg { container-type: inline-size; background: var(--scheme-background); padding: var(--lg-pt) 0 var(--lg-pb); }
.lg__in { max-width: var(--theme-page-width, 1280px); margin: 0 auto; }
.lg__h { margin: 0 0 20px; padding-inline: var(--theme-padding-x, 24px); text-align: center; color: var(--scheme-text-muted); font-size: 13px; font-weight: 600; letter-spacing: 0.12em; text-transform: uppercase; }
.lg__row {
  display: flex; gap: 40px; margin: 0; padding: 0 var(--theme-padding-x, 24px); list-style: none;
  overflow-x: auto; overscroll-behavior-x: contain; scroll-snap-type: x mandatory; scrollbar-width: none;
}
.lg__row::-webkit-scrollbar { display: none; }
.lg__item { flex: none; display: flex; align-items: center; scroll-snap-align: start; }
.lg__img { display: block; width: auto; height: 32px; object-fit: contain; opacity: 0.8; transition: opacity 200ms ease; }
.lg__img:hover { opacity: 1; }
.lg__name { color: var(--scheme-heading); font-weight: 600; white-space: nowrap; }
@container (min-width: 900px) { .lg__row { justify-content: center; flex-wrap: wrap; overflow: visible; } }
@media (prefers-reduced-motion: reduce) { .lg__img { transition: none; } }
</style>

<schema>
{
  "type": "logo_strip",
  "name": "Logo strip",
  "category": "Social proof",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "As seen in" },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "white" },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 48, "min": 0, "max": 160, "step": 4, "unit": "px" },
    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "default": 48, "min": 0, "max": 160, "step": 4, "unit": "px" }
  ],
  "blocks": [
    {
      "type": "logo",
      "name": "Logo",
      "limit": 16,
      "settings": [
        { "type": "text", "id": "name", "label": "Name", "default": "Publication", "info": "Shown when there is no image, and read aloud by screen readers." },
        { "type": "image_picker", "id": "logo", "label": "Logo", "default": "" },
        { "type": "url", "id": "link", "label": "Link", "default": "" }
      ]
    }
  ],
  "max_blocks": 16,
  "presets": [
    { "name": "Logo strip", "blocks": [{ "type": "logo" }, { "type": "logo" }, { "type": "logo" }, { "type": "logo" }] }
  ]
}
</schema>
```

## Video with text

The `embed` capability and the `embed` filter: a creator pastes whatever link they have, and the frame only ever points at a known player. See [Embeds](https://storelib.com/developers/javascript#embeds).

sections/video_feature.storelib

```html
<template>
<section class="vf" data-scheme="{{ settings.color_scheme }}" style="--vf-pt: {{ settings.padding_top }}px; --vf-pb: {{ settings.padding_bottom }}px;">
  <div class="vf__in">
    <div class="vf__copy">
      {% if settings.heading != "" %}<h2 class="vf__h">{{ settings.heading }}</h2>{% endif %}
      {% if settings.text != "" %}<p class="vf__p">{{ settings.text }}</p>{% endif %}
    </div>
    {% if settings.video_url != "" %}
      <iframe class="vf__player" src="{{ settings.video_url | embed }}" title="{{ settings.video_title }}" loading="lazy" allow="autoplay; encrypted-media; picture-in-picture" allowfullscreen></iframe>
    {% elsif page.in_editor %}
      <p class="vf__empty">Paste a YouTube, Vimeo, Spotify or SoundCloud link in the panel.</p>
    {% endif %}
  </div>
</section>
</template>

<style>
.vf { container-type: inline-size; background: var(--scheme-background); padding: var(--vf-pt) var(--theme-padding-x, 24px) var(--vf-pb); }
.vf__in { display: grid; gap: 28px; max-width: var(--theme-page-width, 1280px); margin: 0 auto; }
.vf__h { margin: 0; color: var(--scheme-heading); font-size: var(--section-heading-size, 32px); line-height: var(--section-heading-line-height, 1.15); }
.vf__p { margin: 14px 0 0; color: var(--scheme-text); font-size: var(--section-text-size, 17px); line-height: 1.6; }
.vf__player { display: block; width: 100%; aspect-ratio: 16 / 9; border: 0; border-radius: {{ theme.radius.medium }}px; background: var(--scheme-background-secondary); }
.vf__empty { margin: 0; padding: 48px 20px; text-align: center; color: var(--scheme-text-muted); border: 1px dashed var(--scheme-border); border-radius: {{ theme.radius.medium }}px; }
@container (min-width: 900px) { .vf__in { grid-template-columns: 2fr 3fr; align-items: center; gap: 48px; } }
</style>

<schema>
{
  "type": "video_feature",
  "name": "Video with text",
  "category": "Media",
  "capabilities": ["embed"],
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "See it in use" },
    { "type": "textarea", "id": "text", "label": "Text", "default": "Two minutes, start to finish." },
    { "type": "url", "id": "video_url", "label": "Video link", "default": "", "info": "A YouTube, Vimeo, Spotify or SoundCloud link, as you would copy it from the address bar." },
    { "type": "text", "id": "video_title", "label": "Video title", "default": "Product demo", "info": "Read aloud by screen readers." },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "white" },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 72, "min": 0, "max": 200, "step": 4, "unit": "px" },
    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "default": 72, "min": 0, "max": 200, "step": 4, "unit": "px" }
  ],
  "presets": [{ "name": "Video with text" }]
}
</schema>
```

## Product cards

The creator's own published products through `products`, in the same `{ id, type, settings }` shape as blocks. Prices arrive formatted, and a sale shows the old price struck through.

sections/product_cards.storelib

```html
<template>
<section class="pc" data-scheme="{{ settings.color_scheme }}" style="--pc-pt: {{ settings.padding_top }}px; --pc-pb: {{ settings.padding_bottom }}px; --pc-cols: {{ settings.columns }};">
  <div class="pc__in">
    {% if settings.heading != "" %}<h2 class="pc__h">{{ settings.heading }}</h2>{% endif %}
    <div class="pc__grid">
      {% for block in products %}
        <a class="pc__card" href="{{ block.settings.url | url }}">
          <span class="pc__media">
            {% if block.settings.image != "" %}<img class="pc__img" src="{{ block.settings.image }}" alt="{{ block.settings.title }}" width="600" height="600" loading="lazy">{% endif %}
            {% if block.settings.tag != "" %}<span class="pc__tag">{{ block.settings.tag }}</span>{% endif %}
          </span>
          <span class="pc__title">{{ block.settings.title }}</span>
          <span class="pc__price">
            {{ block.settings.price }}
            {% if block.settings.compare_price != "" %}<s class="pc__was">{{ block.settings.compare_price }}</s>{% endif %}
          </span>
        </a>
      {% else %}
        {% if page.in_editor %}<p class="pc__empty">Your published products appear here.</p>{% endif %}
      {% endfor %}
    </div>
  </div>
</section>
</template>

<style>
.pc { container-type: inline-size; background: var(--scheme-background); padding: var(--pc-pt) var(--theme-padding-x, 24px) var(--pc-pb); }
.pc__in { max-width: var(--theme-page-width, 1280px); margin: 0 auto; }
.pc__h { margin: 0 0 24px; color: var(--scheme-heading); font-size: var(--section-heading-size, 28px); line-height: var(--section-heading-line-height, 1.2); }
.pc__grid { display: grid; gap: 20px 16px; grid-template-columns: repeat(2, minmax(0, 1fr)); }
.pc__card { display: flex; flex-direction: column; gap: 6px; min-width: 0; color: inherit; text-decoration: none; }
.pc__media { position: relative; display: block; aspect-ratio: 1; overflow: hidden; border-radius: {{ theme.radius.medium }}px; background: var(--scheme-background-secondary); }
.pc__img { display: block; width: 100%; height: 100%; object-fit: cover; transition: transform 300ms ease; }
.pc__card:hover .pc__img { transform: scale(1.03); }
.pc__tag { position: absolute; top: 10px; left: 10px; padding: 3px 8px; font-size: 12px; font-weight: 600; color: var(--scheme-button-primary-text); background: var(--scheme-button-primary); border-radius: 999px; }
.pc__title { overflow-wrap: anywhere; color: var(--scheme-heading); font-weight: 600; }
.pc__price { color: var(--scheme-text); font-size: 14px; }
.pc__was { margin-left: 6px; color: var(--scheme-text-muted); }
.pc__empty { color: var(--scheme-text-muted); }
@container (min-width: 900px) { .pc__grid { grid-template-columns: repeat(var(--pc-cols), minmax(0, 1fr)); gap: 28px 20px; } }
@media (prefers-reduced-motion: reduce) { .pc__img { transition: none; } .pc__card:hover .pc__img { transform: none; } }
</style>

<schema>
{
  "type": "product_cards",
  "name": "Product cards",
  "category": "Products",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "New this week" },
    { "type": "range", "id": "columns", "label": "Columns on desktop", "default": 4, "min": 2, "max": 5, "step": 1 },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "white" },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" },
    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" }
  ],
  "presets": [{ "name": "Product cards" }]
}
</schema>
```

## Tabs

Blocks as tabs, switched with radio inputs and `:checked`, keyboard reachable, with the first tab open. The same pattern works for any "one of these at a time" layout.

sections/tabs_panel.storelib

```html
<template>
<section class="tb" data-scheme="{{ settings.color_scheme }}" style="--tb-pt: {{ settings.padding_top }}px; --tb-pb: {{ settings.padding_bottom }}px;">
  <div class="tb__in">
    {% if settings.heading != "" %}<h2 class="tb__h">{{ settings.heading }}</h2>{% endif %}
    <div class="tb__tabs">
      {% for block in blocks %}
        <input class="tb__radio" type="radio" name="{{ section.id }}-tab" id="{{ section.id }}-{{ block.id }}"{% if forloop.first %} checked{% endif %}>
        <label class="tb__label" for="{{ section.id }}-{{ block.id }}" data-block-id="{{ block.id }}">{{ block.settings.title }}</label>
        <div class="tb__panel">{{ block.settings.content | raw }}</div>
      {% else %}
        {% if page.in_editor %}<p class="tb__empty">Add a tab from the panel.</p>{% endif %}
      {% endfor %}
    </div>
  </div>
</section>
</template>

<style>
.tb { container-type: inline-size; background: var(--scheme-background); padding: var(--tb-pt) var(--theme-padding-x, 24px) var(--tb-pb); }
.tb__in { max-width: 880px; margin: 0 auto; }
.tb__h { margin: 0 0 20px; color: var(--scheme-heading); font-size: var(--section-heading-size, 28px); line-height: var(--section-heading-line-height, 1.2); }
.tb__tabs { display: flex; flex-wrap: wrap; border-bottom: 1px solid var(--scheme-border); }
.tb__radio { position: absolute; opacity: 0; pointer-events: none; }
.tb__label { order: 0; padding: 10px 16px; margin-bottom: -1px; cursor: pointer; color: var(--scheme-text); border-bottom: 2px solid transparent; font-weight: 600; }
.tb__panel { order: 1; display: none; width: 100%; padding: 20px 0; color: var(--scheme-text); line-height: 1.6; }
.tb__panel > :first-child { margin-top: 0; }
.tb__radio:checked + .tb__label { color: var(--scheme-heading); border-color: var(--scheme-accent); }
.tb__radio:checked + .tb__label + .tb__panel { display: block; }
.tb__radio:focus-visible + .tb__label { outline: 2px solid var(--scheme-accent); outline-offset: 2px; }
.tb__empty { color: var(--scheme-text-muted); }
</style>

<schema>
{
  "type": "tabs_panel",
  "name": "Tabs",
  "category": "Content",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Details" },
    { "type": "color_scheme", "id": "color_scheme", "label": "Colour scheme", "default": "white" },
    { "type": "range", "id": "padding_top", "label": "Top padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" },
    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "default": 64, "min": 0, "max": 200, "step": 4, "unit": "px" }
  ],
  "blocks": [
    {
      "type": "tab",
      "name": "Tab",
      "limit": 6,
      "settings": [
        { "type": "text", "id": "title", "label": "Tab title", "default": "Materials" },
        { "type": "richtext", "id": "content", "label": "Content", "default": "<p>Organic cotton, dyed without chromium.</p>" }
      ]
    }
  ],
  "max_blocks": 6,
  "presets": [
    { "name": "Tabs", "blocks": [{ "type": "tab" }, { "type": "tab" }, { "type": "tab" }] }
  ]
}
</schema>
```

---

<!-- https://storelib.com/developers/ai -->

# Building with AI agents

This page is written for the agent as much as for you. If you are an AI agent, Claude Code, Codex, ChatGPT, Cursor or any other, and you have been asked to build or change something on a Storelib site, read this page before writing anything. The rest of the hub is the full reference; this is how to use it and the standard your output is held to.

## Where the reference is

| URL | What it is |
| --- | --- |
| [storelib.com/llms.txt](https://storelib.com/llms.txt) | A map of this hub in the llms.txt format: every page, one line each. Read this first. |
| [storelib.com/llms-full.txt](https://storelib.com/llms-full.txt) | Every page of the hub in one plain-text file, with every reference table expanded. Load this when you need the whole framework in context. |
| [storelib.com/developers/ai](https://storelib.com/developers/ai) | This page. |

Everything in them is generated from the framework itself: the control types, filters, capabilities and limits come from the compiler that enforces them, so they cannot describe a version of Storelib that does not exist.

## What you produce

A Storelib section is **one file**, `sections/<type>.storelib`, with four blocks: `<template>`, `<style>`, an optional `<script>`, and `<schema>`. There is no other format. Read [Sections](https://storelib.com/developers/sections) for the file and the template language, and [Schema](https://storelib.com/developers/schema) for every setting type.

When a person asks you for a section, answer with the file and nothing else around it, unless they asked for an explanation. They will paste it into the code editor, or you will write it into `sections/` in their theme.

## Six things agents get wrong

These are the mistakes that produce a file which looks right and is not. Check each before you answer.

1. **A section's script runs against a copy.** It runs in a sandbox, and `root` is a copy of the section's own markup: toggle classes, set styles and text, add listeners, and the page mirrors each change. It cannot add or remove elements, measure layout, or set `src`, `href` or `on*`. Where HTML does it alone (`<details>`, radio inputs and `:checked`, scroll snapping, the `popover` attribute), use HTML. See [JavaScript](https://storelib.com/developers/javascript).
2. **The template language is not Vue, React, JSX or Liquid.** `v-if`, `@click`, `:class`, `{% assign %}` and JSX braces are refused. It is `{{ }}`, `{% if %}`, `{% for %}`, `{# #}` and filters, and nothing else.
3. **Every name must be declared.** `{{ settings.subtitle }}` does not compile unless the schema declares `subtitle`. Check every path your template and CSS read against your schema.
4. **Repeated content is blocks.** Never `feature_1`, `feature_2`, `feature_3`.
5. **Colour comes from the scheme.** Declare a `color_scheme` setting and read `var(--scheme-*)`. A hex code for anything the scheme answers stops responding to the creator's theme.
6. **Container queries, not media queries.** The builder's phone preview is not the width of the window.

## Know the website before you write for it

A section written without knowing the site is a section from another website: the wrong colours, an invented product, a headline for a business nobody runs. Before writing, find out:

- **What it sells.** The published products, with their real titles and prices. Never invent a product, a price or a review. A connected agent reads them with `storelib_site`; the builder's AI is given them.
- **What it is called and what it says about itself.** The brand name, tagline, site title and description. Write copy in the same voice and the site's language.
- **How it looks.** The colour schemes and fonts. Use `var(--scheme-*)` and the theme's type styles, never a new palette.
- **What is already on the page.** The sections each page has, so a new one does not repeat the one above it.

Then read [Selling](https://storelib.com/developers/selling) if the section shows a product, a price or a Buy button.

## An email box collects emails

A `<form>` with an `<input type="email">` in a section sends every address to the site creator's Subscribers. The page does it, with no script. Mark it `data-storelib-form="subscribe"`, and never write a script to submit a form or ask the creator to paste a mailing list URL to make it work. See [Forms](https://storelib.com/developers/javascript#forms).

## The loop your output goes through

This is what the builder's own AI does with every section it writes, and it is the loop you should run yourself when you can:

1. Write the whole file.
2. Compile it with the same compiler the code editor saves through. Every error comes back with its file and line.
3. Check it against the section contract: the colour scheme, the phone layout, no sideways scroll, safe to place twice, reduced motion, real elements for anything interactive.
4. Fix exactly what failed, quoting the errors back, and try again. The builder allows 3 attempts in all, then shows the person what is still wrong rather than keeping a file that does not compile.
5. Keep the file only when it compiles. A file that does not compile is never stored.

When you cannot run the compiler, the person will: the code editor compiles on save and shows each error as `file:line message`. Fix the line it names. Do not rewrite the file.

## Change content before source

Most requests are not new sections. "Make the heading bigger", "use the dark scheme", "add a fourth question" are changes to a section's **settings** or **blocks**, which the creator can make in the builder without new code. Write or change a section file only when no existing setting can do what was asked. When you do change one, change the least that does it, and never rename or remove a setting `id` without a `migrations` entry; see [Changing a section safely](https://storelib.com/developers/schema#changing-a-section-safely).

## What you may not do

- Write outside `sections/`, `templates/`, `config/`, `layout/`, `snippets/` and `locales/`.
- Invent an asset. Images are chosen by the creator through an `image_picker`; never put a URL to a picture into a default.
- Declare a capability the section does not need.
- Use `window`, `document`, `fetch`, `localStorage` or `eval`. They are refused when the file is saved; query inside `root` instead.
- Add a contact form's sender to the mailing list. Only a box they ticked may do that.

## The brief the builder's AI is given

When a creator asks the builder's AI to write a new section, this is the brief it receives, word for word. It is assembled from the same modules as this hub, so what you are reading is what it follows. If you follow it too, your sections and the builder's will be indistinguishable.

The full brief, word for word:

```text
A Storelib section is ONE file with four blocks, each tag on its own line:
  <template> markup </template>
  <style> CSS </style>
  <script> optional; runs in a sandbox against a copy of this section </script>
  <schema> JSON </schema>

THE TEMPLATE LANGUAGE IS NOT VUE, REACT OR JSX. v-if, @click, :class and JSX braces are refused by the compiler. It is:
  {{ settings.heading }}            print a value, HTML-escaped
  {% if x %} … {% elsif y %} … {% else %} … {% endif %}
  {% for block in blocks %} … {% else %} … {% endfor %}
  {# a comment, which never reaches the page #}
It can read: settings, blocks, section (.id .type .settings .blocks), theme, scheme, page (.template, .in_editor), products, and forloop inside a loop. settings and section.settings are the same thing.

EVERY NAME MUST BE DECLARED. {{ settings.foo }} compiles only when the schema declares a setting with id "foo". The same for block settings. The compiler checks every path the template reads against the schema beside it, so a typo is an error with a line number, not a blank space on the page.

FILTERS, after a pipe, argument after a colon:
  default upcase downcase capitalize strip size first last join truncate append prepend replace plus minus times divided_by round json escape raw url embed asset alpha
  url on every href. raw only on a richtext setting. asset on images.

SETTING TYPES:
  text textarea richtext number toggle checkbox select radio range color color_scheme font_picker alignment image_picker image_gallery video_picker file_picker icon_picker url page_picker product_picker community_picker header paragraph divider

REPEATED CONTENT IS BLOCKS, never question_1 / question_2. Declare a block type in the schema with its own settings, and loop over `blocks` in the template. Put data-block-id="{{ block.id }}" on each one so clicking it in the builder selects it. A preset with two or three blocks in it is what makes the section arrive with something in it rather than empty. Block settings are read as block.settings.<id> and must be declared on that block type.

COLOUR COMES FROM THE SCHEME. Declare a color_scheme setting and read the scheme in the template and CSS. The keys are: background, background_secondary, text, text_muted, heading, accent, link, border, primary_button_background, primary_button_text, primary_button_border, secondary_button_background, secondary_button_text, secondary_button_border, input_background, input_text, input_border. Older themes also read the shorter aliases bg, paragraph, primary_btn_bg and primary_btn_text, which still resolve. The built-in schemes are white, light, dark, black and highlight, shown in the editor as Light, Soft, Dark, Brand and Accent, and a creator can add more. Never hardcode a hex value for something the scheme already answers: a hardcoded colour stops responding to the creator's theme.

RESPONSIVE IS WRITTEN WITH CONTAINER QUERIES, NOT MEDIA QUERIES. A section is as wide as the column it is in, which in the builder's phone preview is not the width of the window, so @media asks the wrong question and a section built on it looks correct in the preview and wrong in the editor. Put container-type: inline-size on the outermost element, write the phone layout as the base rules, then @container (min-width: 640px) and @container (min-width: 1024px) for wider ones.

A SECTION'S CSS IS SCOPED AUTOMATICALLY, to that section's instances and nothing else. You do not write the scope and you cannot escape it. html, body and :root are rewritten to point at the section root, so a rule written against them does not do what it looks like it does; do not write them. The CSS may read settings with {{ }} the same way the template does.

AN EMPTY STATE BELONGS BEHIND {% if page.in_editor %}, so it prompts the creator in the builder and never reaches a visitor. The schema's preset is what a section arrives with: fill it, so adding the section produces something finished rather than a shell.

A SECTION CAN BE ON A PAGE MORE THAN ONCE. Nothing in it may assume it is alone: no literal id="..." in the markup, because two instances would then share one id. Build ids from {{ section.id }}, and have the script query inside root rather than the document.

A SECTION'S <script> RUNS IN A SANDBOX, against a copy of the section's own markup. root is that copy: query inside it, add listeners, toggle classes, set styles and text, and the page mirrors each change. It cannot add or remove elements (show and hide what the template drew, with hidden or a class), cannot measure layout, and cannot set src, href or on* attributes. Scroll with storelib.scrollTo(el, { left, behavior: "smooth" }); storelib.inEditor is true in the builder.
  PREFER HTML AND CSS where they do it alone, because they work before any script loads: <details> accordions (a shared name="{{ section.id }}-faq" keeps one open), radio :checked tabs, scroll-snap carousels, popovertarget pop-ups, CSS transitions stopped under prefers-reduced-motion. Use script for what they cannot: autoplay, counters, a slider's dots.
  window, document, fetch, localStorage, eval and Function are refused by name. Timers need the "timers" capability. Capabilities: navigation, commerce, analytics, forms, timers, embed.

AN EMAIL BOX COLLECTS EMAILS FOR THE SITE'S CREATOR. The page submits <form data-storelib-form="subscribe"> with <input type="email" name="email"> (and name="name" if asked) into the creator's Subscribers: no script, no action, and never ask the creator for a URL. It carries data-state="sending", "done" or "error" for the CSS, and an element marked data-storelib-success hidden replaces it on success. Give the input a <label>. For another mailing service, set its action and data-storelib-form="native".

TWO THINGS OUTRANK EVERY DESIGN RULE BELOW: what the creator explicitly asked for, and what this site has already established. Somebody who asks for a gradient gets a gradient. A site already built on pill buttons keeps pill buttons. These are defaults for the decisions nobody has made yet, not a house style to impose on work that already has one.

AVOID THE THINGS THAT MAKE A PAGE READ AS MACHINE-MADE, unless asked for or already the site's style:
- Decorative gradients, gradient text, and coloured glows behind cards.
- Glassmorphism and frosted panels.
- Everything at a large corner radius. Buttons and inputs sit around 6-10px; a card is not a pill.
- Eyebrow chips and badges above headings, and numbered markers like 01 / 02 / 03, when they carry no information.
- Three cards in a row as the answer to every layout. Use the number the content has.
- Icon tiles stacked above every heading, and the same four icons everywhere.
- Headings sized for a screenshot rather than for reading.
- Invented social proof of any kind: testimonials with made-up names, statistics nobody measured, logos of companies that are not customers, star ratings with no reviews behind them.
- Copy that would fit any business. "Streamline", "unlock", "elevate", "seamless", "transform", "empower". Write about this business instead.
- One-hue purple-and-indigo palettes, and neon on near-black, chosen as a default rather than because the brand is that.

WHAT GOOD LOOKS LIKE HERE: solid surfaces, restrained borders, shadows you have to look for. A clear type hierarchy doing the work that decoration was doing. Generous, consistent spacing on a scale the rest of the page already uses. Layouts that are simple on purpose, where every visual choice has a reason you could say out loud. If you cannot say why something is there, take it out.

USE THE SITE'S OWN DESIGN SYSTEM RATHER THAN INVENTING ONE:
- COLOUR comes from the colour scheme. A visual section declares a color_scheme setting and reads scheme.background, scheme.text, scheme.text_muted, scheme.heading, scheme.border, scheme.accent, scheme.link, scheme.primary_button_background, scheme.primary_button_text. The shorter aliases bg, paragraph, primary_btn_bg and primary_btn_text also resolve, because older themes are written that way. Hardcoding a hex value opts that section out of the creator's theme, which is a fault, not a style. Allow custom colours only where a section genuinely needs them, off by default, and only the few that matter: background, text, muted text, accent, border. Never ten colour pickers beside a scheme that already answers them.
- TYPE comes from the theme's fonts and type scale. Do not name a font family inside a section. Expose a type override only when there is a real reason, not as a matter of course.
- BUTTONS use the theme's button styles. Do not build a private button system inside each section.
- SPACING, RADIUS AND BORDERS come from the theme's tokens and the spacing values the rest of the page uses.
- MATCH THE PAGE THIS WILL SIT ON. Reuse a colour that is already there rather than one three shades off it. Follow the background rhythm the page has. Coherence comes from a small vocabulary used consistently.

SETTINGS ARE MERCHANT CHOICES, NOT CSS PROPERTIES. Good: colour scheme, layout, alignment, columns, content width, desktop spacing, mobile spacing, image position, slider speed and direction, whether the first item starts open. Bad: flex-direction, z-index, letter-spacing, a raw class name, anything that only means something to whoever wrote the CSS.
- Most visual sections start with colour scheme, content width, alignment, desktop spacing and mobile spacing, then whatever is specific to that section and nothing more.
- Different sections get different settings. An FAQ needs a style, an icon, and whether the first answer is open. A marquee needs direction, speed and gap. Testimonials need columns and whether ratings show. A hero needs layout, media position and heading size. Do not give them all the same list.
- A section must look finished with its defaults, before anybody opens the settings panel.

MOBILE IS DESIGNED, NOT SHRUNK. Write the phone layout first and let the wider ones be the addition. Decide, per section: what stacks and in what order, how wide text runs, what spacing changes, whether a grid becomes a slider, how images crop, and that nothing scrolls sideways. Touch targets stay comfortable. A desktop layout with smaller text is not a mobile design.

BEFORE YOU CALL A SECTION FINISHED, it must: compile; declare every name its template reads; take the site's colour scheme rather than hardcoded colours; inherit the theme's type and buttons; be laid out for a phone on purpose and not by shrinking; have no sideways scroll; work when the section is on the page twice, which means no fixed id="…" in the markup and no query outside the script's own root; keep its CSS to itself; use real elements for anything interactive, with alt text on images; and stop animating for anyone who has asked for reduced motion. Those are checked after you write, and you will be shown what failed.
```

Some reference is added only when a request is about it. These topics are included when the words in a request call for them:

typography:

```text
TYPE COMES FROM THE THEME. The theme carries font roles (heading, body, accent) and a type scale (h1, h2, h3, h4, body_large, body, body_small, button, caption), each with its own desktop, tablet and mobile size. Read them from theme rather than naming a font family inside a section. Expose a type control only when the section genuinely needs one.
```

embed:

```text
AN <iframe> NEEDS PERMISSION AND AN ADDRESS FROM THE embed FILTER. Declare "capabilities": ["embed"] in the schema and write <iframe src="{{ settings.video_url | embed }}" title="…" loading="lazy" allowfullscreen></iframe>. Any other iframe, or an iframe whose src comes from anywhere else, is refused when the file is saved. The filter accepts youtube.com, youtube-nocookie.com, youtu.be, vimeo.com, player.vimeo.com, open.spotify.com, w.soundcloud.com, turns what people paste (a youtu.be link, a watch?v= link) into the player's address, and returns "" for everything else, so put the frame inside {% if settings.video_url != "" %}. Size it with aspect-ratio: 16 / 9 and width: 100% in the CSS.
```

animation:

```text
ANIMATION IS CSS FIRST. Transition the properties that are cheap to animate: opacity and transform. Height from 0 to auto does not transition; use grid-template-rows 0fr to 1fr, or max-height, or transform. Anything that moves must be wrapped so it stops for people who have asked it to: @media (prefers-reduced-motion: reduce) { … } with the transition or animation set to none. That media query is about the visitor's own setting, not about width, so it is the one place @media is right.
```

assets:

```text
IMAGES come from an image_picker setting and are printed through the asset filter. Give every img a width, a height and an alt, and set object-fit where the crop matters. A section that renders an empty image box when nothing has been chosen looks broken; put the placeholder behind {% if %}.
```

settings resolution:

```text
A SETTING'S VALUE is the creator's choice if they made one, otherwise the schema's default. A field id that does not exist, and a value the control cannot take, are both ignored silently by the renderer, so a change written against either looks like it worked and does nothing. Padding and spacing belong in range settings with a px unit rather than fixed numbers in the CSS.
```

accessibility:

```text
INTERACTIVE THINGS MUST BE REACHABLE. A control that can be clicked is a button or a link, not a div with a handler. <details>/<summary> is keyboard-accessible for free. Anything that opens says so with aria-expanded, every image has alt text, and text keeps at least 4.5:1 against what is behind it. Headings go in order and describe the section.
```

## Setting up your agent

**Claude Code.** Add this to the `CLAUDE.md` at the root of your theme folder:

```md
This is a Storelib theme. Sections are .storelib files written in the
Storelib Builder Framework. Before writing or changing any file under
sections/, read https://storelib.com/llms-full.txt and follow
https://storelib.com/developers/ai. A section's script runs in a
sandbox against a copy of its own markup: prefer HTML and CSS.
```

**Codex.** Put the same paragraph in `AGENTS.md` at the root of the theme folder.

**Cursor.** Type `@Docs`, choose Add new doc, and give it `https://storelib.com/llms-full.txt`. Mention it with `@Docs` whenever you ask for a section, or add the paragraph above to a rule in `.cursor/rules`.

**ChatGPT, Claude.ai and others.** Give it the link, or download [llms-full.txt](https://storelib.com/llms-full.txt) and attach it, and ask for "a Storelib section, as one .storelib file".

## Two ways to connect

|  | Through GitHub | Direct connection |
| --- | --- | --- |
| What it is | The site's sections live in a repository you own. | A token that lets an agent on your computer read and save the site's sections. |
| How a change arrives | The agent pushes to the branch. Storelib compiles every changed section and saves it. | The agent calls `storelib_write_section`. |
| Best for | Claude Code or Codex working in a repository, a team, a history of every change. | One person and one agent, nothing to set up on GitHub. |
| What you see | The change in the builder within seconds, and a Storelib check on the commit. | The change in the builder within seconds. |

Both reach one site and nothing else, both save drafts that go live only when you publish, and both are under **Website Settings › Advanced** in the builder, which the plug button in the top bar (**Connect Claude Code, Codex or ChatGPT**) opens. Pick your tool there and it shows only the steps for it.

**ChatGPT** works through GitHub. Codex in ChatGPT edits a GitHub repository, so link one below, ask Codex for the change, and merge it into the linked branch: it reaches the site like any other push.

## Connect through GitHub

1. In the builder, press the plug button in the top bar, or open **Website Settings › Advanced**.
2. Press **Connect GitHub**. GitHub asks which repositories to give Storelib; pick one, or make an empty one first.
3. Back in the builder, pick the repository, the branch (its default branch unless you say otherwise) and, if the site should live in a folder of a bigger repository, the folder. Press **Link and send sections**.

Storelib writes one commit into the repository: every section file the site has, under `sections/`, and an `AGENTS.md` and a `CLAUDE.md` that tell an agent what the files are and how a push reaches the site. From then on:

- **Push a change** to `sections/<type>.storelib` on that branch and it is compiled and saved to the site as a draft. An open builder shows it within a few seconds; a new section is placed on the page being edited.
- **Every push gets a status** named Storelib on its commit: green with how many sections were saved, or red with the first error and its line. A file that does not compile is not saved, and nothing else in the push is held back by it.
- **Only `sections/*.storelib` is read.** Everything else in the repository is yours and ignored. Deleting a section file on GitHub does not remove the section from the site, because a page may be using it.
- **Send to GitHub**, in Connections, writes the site's current sections into the repository again, for instance after editing in the builder.
- At most 30 section files are taken from one push. Storelib's own commits are recognised and not synced back.

With Claude Code, the whole loop is a conversation: open the repository, ask for the section, and let it commit and push.

```bash
git clone https://github.com/you/your-site && cd your-site
claude "Add a pricing section with three tiers to sections/, then commit and push"
```

## Connect an agent directly

An agent can work on a site directly: list its files, read them, compile a section until it is clean, and save it. The creator connects it once, from the builder.

1. Open the site in the website builder, then **Website Settings › Advanced**, and pick **Claude Code** or **Codex**.
2. Name the connection, for example "Claude Code", and press **Connect**.
3. Copy the token it shows. It is shown once. Storelib keeps only its hash, so a lost token is disconnected and replaced, never recovered.

**Claude Code.** Run this in a terminal, with the token in place of `slb_...`:

```bash
claude mcp add --transport http storelib https://storelib.com/api/mcp --header "Authorization: Bearer slb_..."
```

**Codex.** Add this to `~/.codex/config.toml`, and set the environment variable `STORELIB_TOKEN` to the token (`export STORELIB_TOKEN="slb_..."` in the terminal you start Codex from):

```toml
[mcp_servers.storelib]
url = "https://storelib.com/api/mcp"
bearer_token_env_var = "STORELIB_TOKEN"
```

**Anything else** that speaks MCP over HTTP takes the same address and header. An agent or script that does not speak MCP can use the same token with plain HTTP, below.

### The tools

| Tool | What it does |
| --- | --- |
| `storelib_guide` | This framework, in full. Read it before writing a section. |
| `storelib_site` | What this website is: its name and address, brand, title and description, fonts and colour schemes, the sections on each page, and its published products with their prices and ids. Read it before writing, so the section fits this site. |
| `storelib_list_files` | Every file of the site's theme, marked `yours` or `theme`. |
| `storelib_read_file` | One file, the saved draft where there is one, with its `updated_at`. |
| `storelib_compile` | Compiles a section without saving it, and answers `file:line message` for every error. |
| `storelib_write_section` | Saves a section as a draft. It is compiled first and refused with its errors if it does not compile. |

The loop that works: read the guide and the site, write the file, compile it until it is clean, then save it. When changing a file that exists, pass the `updated_at` you read as `base_updated_at`, and a save made elsewhere in the meantime is refused rather than overwritten.

### What a connection can and cannot do

- It reaches **one site**. Not the creator's other sites, orders, buyers, subscribers or account. It sees the site's published products only as a visitor does: title, price, picture and address.
- It writes **section files only**: `sections/<type>.storelib`, lower case, digits, `_` and `-`. Templates, settings and layout are the creator's.
- **Every save is a draft**, held to exactly the rules a save in the code editor is: it must compile, and its name must be free. Nothing reaches visitors until the creator publishes.
- It cannot delete, rename or publish anything.
- **A new section appears on the page the creator has open** in the builder, above the footer, labelled with the connection's name. If the builder is closed it waits in Add Section, under Created by you.
- The creator can disconnect it at any time; the token stops working on its next request.

### Over plain HTTP

Every request carries `Authorization: Bearer slb_...`.

| Request | Does |
| --- | --- |
| `GET /api/agent/v1/site` | What the website is, as `storelib_site` answers it. |
| `GET /api/agent/v1/files` | Lists the theme's files. |
| `GET /api/agent/v1/files?path=sections/x.storelib` | Reads one. |
| `POST /api/agent/v1/compile` with `{ "path", "source" }` | Compiles without saving. `422` with `errors` when it does not compile. |
| `PUT /api/agent/v1/files` with `{ "path", "source", "base_updated_at"? }` | Saves a section as a draft. |

```bash
curl -X PUT https://storelib.com/api/agent/v1/files \
  -H "Authorization: Bearer slb_..." -H "Content-Type: application/json" \
  -d '{"path":"sections/pricing.storelib","source":"<template>..."}'
```

## Without a connection

- **One section.** Open the code editor in the website builder, create `sections/<type>.storelib`, paste the file and save. It compiles, appears in Add Section, and can be placed on any page.
- **A whole theme.** Export the theme from the builder as a `.storelib-theme` file, unzip it, let the agent work on the folder, zip it and import it. The import checks every file and refuses the package with the reasons if anything is wrong, so a broken edit never reaches a live site.

---

<!-- https://storelib.com/developers/changelog -->

# Changelog

Changes to the Storelib Builder Framework: the section format, the template language, the schema, the controls and the rules the compiler enforces. Changes to the builder's interface that do not change what a section can do are not listed.

## Versions

Four things carry a version, and they move independently so that one changing does not force the others.

| What | Version | Moves when |
| --- | --- | --- |
| The engine | 1 | The engine gains something a theme can require. |
| The section schema format | 1 | The `<schema>` JSON gains or changes a key. Written as `schema_version`. |
| The theme package format | 1 | The layout of a `.storelib-theme` file changes. |
| A section | its own `version` | Its author says so. `migrations` refer to it. |

A file written for a newer version is **refused, not misread**: a schema declaring `"schema_version": 2` against an engine that reads 1 is rejected with both numbers named. A file written for an older version is always read, and keys the engine does not recognise survive every read and write.

Every change since 1.0 has been additive. Nothing a section could do on 11 September 2026 has stopped working since, which is why every version above is still 1.

## 23 September 2026

**Added**

- Section scripts run. A section's `<script>` runs on the published page and in the builder, inside a sandbox with an opaque origin, against a copy of the section's own markup. Changes to classes, allowed attributes, styles and text are mirrored to the page; clicks, keys and input are sent back. See [How the sandbox works](https://storelib.com/developers/javascript#how-the-sandbox-works).
- `storelib.scrollTo(element, options)`, `storelib.inEditor`, and `storelib.navigate(path)` for a section that declares `navigation`.
- [Selling](https://storelib.com/developers/selling): the fields `products` gives a section, the checkout link `/checkout?productId={{ block.id }}&src=website`, the cart, what checkout does with the money, and what a section may never do with payments.
- `storelib_site`, and `GET /api/agent/v1/site`: what a connected website is, its brand, fonts, colour schemes, the sections on each page and its published products, so an agent writes for the site it is connected to.
- Agent connections. A creator connects Claude Code, Codex or any MCP client to one site from Website Settings › Advanced (first shipped as Website settings › Connections). It can list, read, compile and save that site's section files, as drafts, over MCP at `/api/mcp` or HTTP at `/api/agent/v1`. See [Connect an agent directly](https://storelib.com/developers/ai#connect-an-agent-directly).
- GitHub. A site can be linked to a repository. Its section files and an `AGENTS.md` are written into it, and every push to the linked branch that changes `sections/*.storelib` is compiled and saved to the site as a draft, with a Storelib status on the commit. See [Connect through GitHub](https://storelib.com/developers/ai#connect-through-github).
- [Using the website builder](https://storelib.com/developers/website-builder): every panel, control and theme setting, drawn from the lists the builder reads.
- The `timers` capability grants working `setTimeout`, `setInterval` and `requestAnimationFrame`.
- Forms. A `<form>` in a section is submitted by the page, with no script. `data-storelib-form="subscribe"`, or any form with an email box and no action of its own, sends each address to the creator's Subscribers; `data-storelib-form="native"` leaves a form to the browser. The form carries `data-state` while it sends, and shows an element marked `data-storelib-success` when it is done. See [Forms](https://storelib.com/developers/javascript#forms).
- The library's Newsletter Signup section collects sign-ups with nothing set up. It previously showed no form until an outside mailing list address was pasted in.
- The Storelib Developer Hub, [llms.txt](https://storelib.com/llms.txt) and [llms-full.txt](https://storelib.com/llms-full.txt), built from the same modules as the builder's AI.

**Changed**

- The compiler's messages for `@click`, `v-on:` and `on*=` name the section's `<script>` block, beside the HTML that needs no script.

**Security**

- Creator HTML in `richtext` settings is cleaned on import and publish as well as on save and read.
- Sign-up endpoints are rate limited per visitor and per address.

## 20 September 2026

**Fixed**

- A link is no longer styled as a button by theme rules that assumed every `<a>` in a section was one.

## 19 September 2026

**Added**

- Shop and search pages exist on every published site from the day it is published, built from the home page's header and footer, and can be opened and edited in the builder like any other page.

## 13 September 2026

**Added**

- A theme export carries its videos and files as well as its images, each by content hash, or the export fails rather than producing a theme with holes in it.

## 12 September 2026

**Changed**

- A section's type is its file name. A schema whose `type` disagrees with the file it is in is refused, naming both.
- Secondary buttons take the scheme's own secondary button colours.

**Fixed**

- Every section in the library was audited against its schema. Controls that changed nothing were removed rather than left in the panel.

## 11 September 2026

**Added**

- **Storelib Builder Framework 1.0.** The `.storelib` section format with `<template>`, `<style>`, `<script>` and `<schema>` blocks; the template language; the control registry; the compiler, with every error carrying its file and line; CSS scoping; and the script checker with capabilities.
- The section library: thirty sections in ten categories, every one a `.storelib` file.
- Blocks, presets, `max_blocks` and per-type `limit`.
- Responsive settings, resolved as `{ desktop, tablet, mobile }`.
- Colour schemes and text styles as theme tokens, with per-section overrides.
- `migrations` for renaming a setting without losing content.
- Themes export to and import from a single `.storelib-theme` file, checked as a whole, with every file hashed.
- An accessibility baseline: on every built-in colour scheme, body text meets a contrast of 4.5 to 1 against its background and headings meet 3 to 1.