Sections, blocks and settings

Section schemas

{
  "primitive": "banner",
  "name": { "ar": "واجهة", "en": "Hero" },
  "templates": ["home", "page", "collection"],
  "blocks": ["heading", "button"],
  "maxBlocks": 4,
  "settings": [
    { "id": "image", "type": "image", "label": { "ar": "الصورة", "en": "Image" } },
    { "id": "overlay", "type": "range", "label": { "ar": "التعتيم", "en": "Overlay" }, "default": 30, "min": 0, "max": 90, "step": 5, "unit": "%" }
  ]
}

blocks lists the block types a section accepts (@theme accepts any theme block). minBlocks, maxBlocks and limit (instances per template) are enforced when merchants edit.

Block schemas

Blocks use the same shape. Container blocks (group, accordion, accordion-item) list allowedChildren and can nest up to four levels. Set repeatable: false for blocks that may appear only once among their siblings.

Render primitives

Every section and block names a primitive. Theme Check verifies that the primitive exists, that the settings it reads are present with the right types, and that it is placed correctly.

Commerce primitives render the platform's own product form, collection and cart, so buying works the same in every theme.

Setting types

text, textarea, richtext, number, range, select, toggle, color, image, url, product, collection, font.

• Set localized: true on text settings to store Arabic and English values.
• font accepts only fonts the storefront serves under its security policy.
• url accepts store-relative paths, #anchors, https links, mailto: and tel:; image accepts package assets (asset://assets/…) and store media.
• Values are validated when a merchant saves, and again before they reach CSS.

Dynamic sources

Settings marked dynamic: true can bind to store data instead of a fixed value, for example { "$source": "product.title" }. Theme Check checks that the source exists, has a compatible type and is available on the template.

Templates and theme-placed nodes

A template is a tree of sections with nested blocks. Give each node a stable id. Mark a node static: true to keep merchants from removing or moving it, or locked: true to also keep its settings read-only and the node visible. Store Studio, the save endpoint and the renderer all enforce these flags, and a merchant cannot add them to their own nodes.

Styling hooks

Rendered markup exposes stable hooks for your CSS:

• classes saas-section--<primitive>, saas-s-<section-type> and saas-block--<primitive>;
• data-s-<setting> attributes for select and toggle values;
• --t-<setting> custom properties for validated scalar values.

App blocks

Apps of type theme extension can add blocks to themes. In your section or container block schema, list @app (any installed app's block) or an exact app:<app-slug>/<type> in blocks or allowedChildren to let merchants place them there.

App developers declare blocks on a draft app version in the Developer Portal (Storefront blocks). Each block has a lower-kebab-case type, a bilingual name, one of the primitives heading, text, button, image, spacer, divider, announcement, newsletter-form, social-links, payment-icons or testimonial, and a settings schema. Blocks are reviewed with the app version and cannot change after submission. No app code runs in the storefront.

If the merchant uninstalls the app, the block stays in their template but customers no longer see it; it comes back if the app is reinstalled.