Primeiros passos

Os temas são Liquid em sandbox — templates somente de dados renderizados no servidor contra um contrato de dados fixo. Os temas vêm com zero JavaScript: carrinho, opções de item e checkout vêm do runtime de comércio da plataforma, ao qual sua marcação se vincula de forma declarativa.

Baixar o tema inicial (.zip)

1. Baixe e descompacte o tema inicial.
2. Renomeie o slug em theme.json.
3. Edite seções em sections/; adicione snippets em snippets/.
4. Compacte o conteúdo da pasta e envie para revisão.

Estrutura do pacote

mytheme.zip
├── theme.json                  # manifest (data, never code)
├── templates/index.json        # OS 2.0 sectioned template (or index.liquid single-file)
├── sections/*.liquid           # section files, each with its schema block
├── snippets/*.liquid           # reusable partials for the render tag
├── config/settings_schema.json # theme-level settings (Shopify-style groups)
├── locales/en.json …           # theme strings for the t filter
├── assets/                     # css / images / fonts — static only
└── preview.png                 # listing screenshot

Limites: 10 MB CEP 2 MB por arquivo, profundidade de pasta ≤ 3. Tipos de arquivo permitidos: .liquid .json .css .png .jpg .jpeg .webp .svg .woff2. Sem PHP. Sem JavaScript. SVGs não devem conter script nem foreignObject.

theme.json Manifesto

{
  "name": "My Theme",
  "slug": "my-theme",          // letters/numbers/dashes — becomes the install path
  "version": "1.0.0",          // published versions are immutable; ship updates as new versions
  "author": "You",
  "description": "…",
  "min_platform_version": "2.0"
}

Templates e seções (OS 2.0)

templates/index.json listas instâncias de seção; cada seção é um arquivo Liquid em sections/ carregando seu schema de configurações em um bloco schema. Limites: ≤ 25 seções por template, ≤ 50 blocos por seção.

// templates/index.json
{
  "sections": {
    "hero":  { "type": "hero", "settings": { "heading": "Welcome" } },
    "menu":  { "type": "menu-grid",
               "blocks": { "b1": { "type": "badge", "settings": { "label": "New" } } },
               "block_order": ["b1"] }
  },
  "order": ["hero", "menu"]
}

Dentro de um arquivo de seção você recebe section.id, section.type, section.settings.* e section.blocks (cada bloco: id / type / settings.*). Tipos de configuração: text, textarea, color, checkbox, select (Opções), range (mín/máx), image_picker.

Dados — a referência de Drop

Os templates podem acessar apenas as propriedades abaixo (geradas a partir das classes Drop da plataforma — esta tabela não pode divergir). Globais: restaurant, options, settings, menu, allergies, banners, branches, active_branch, table, customer, localization, flags, stats, e section dentro dos arquivos de seção. Qualquer outra coisa renderiza em branco (e gera erro no upload).

AllergyDrop

id int image string title string

BannerDrop

id int image string image_url string link_url string subtitle string title string

BlockDrop

id string settings App\Storefront\Drops\SettingsDrop type string

BranchDrop

accepts_orders bool id int is_open bool name string status string

CategoryDrop

id int image_url string items array name string

CustomerDrop

name string phone string store_credit float store_credit_formatted string

ExtraDrop

id int name string price float

FlagsDrop

allow_order bool delivery bool on_table bool payment bool scheduling bool takeaway bool

ItemDrop

description string dietary_tags array extras array has_variants bool id int image string is_daily_special bool is_gluten_free bool is_halal bool is_popular bool is_sold_out bool is_vegan bool name string option_groups array price float rating float rating_count int variants array

LanguageDrop

code string direction string name string

LocalizationDrop

currencies array current App\Storefront\Drops\LanguageDrop direction string languages array

MenuDrop

categories array is_empty bool items array

OptionGroupDrop

choices array id int max_select int min_select int name string required bool

OptionsDrop

allow_call_waiter bool allow_coupons bool allow_dietary_filters bool allow_multi_branch_switch bool allow_order_scheduling bool allow_tips bool currency_code string currency_pos string currency_sign string customer_auth_mode string delivery_charge float enable_multi_currency bool menu_sections string min_order_value float open_close_store bool tax_charge float tax_label string whatsapp_number string

RestaurantDrop

address string color string cover string description string id int logo string main_image string phone string slug string sub_title string title string

SectionDrop

blocks array id string settings App\Storefront\Drops\SettingsDrop type string

SettingsDrop

StatsDrop

scans_today int

TableDrop

id int table_no string

VariantDrop

id int name string price float

Filtros e tags

Filtros da plataforma (mais o conjunto Liquid seguro padrão — escape, date, where, map, sort, size…):

media_urlmoneymoney_codettheme_asset

• t — traduz uma chave. Somente leitura; chaves desconhecidas retornam a própria chave.
• money / money_code — formata um preço com a moeda do restaurante.
• media_url — URL da imagem do restaurante: {{ item.image | media_url: 'menu' }} (tipos: menu, logo, capa, alergia, banner).
• theme_asset — URL de um dos seus assets incluídos: {{ 'css/style.css' | theme_asset }}.

Etiquetas schema (configurações da seção, removidas da saída), render (snippets por nome — seu snippets/ diretório apenas), commerce (emite o runtime de comércio uma vez por página). Filtros/tags desconhecidos falham no upload.

Runtime de comércio

Largar {% commerce %} uma vez (normalmente no final do seu template) e depois vincule com atributos data — o runtime controla o estado do carrinho, a folha de opções e o checkout:

<button data-mb-add="{{ item.id }}">Add</button>
<span   data-mb-cart-count></span>
<span   data-mb-cart-total></span>
<button data-mb-open-cart>Cart</button>
<button data-mb-call-waiter>Call waiter</button>
<div    data-mb-item-sheet-mount hidden></div>
<div    data-mb-cart-mount hidden></div>

Estilize a interface do runtime por meio de suas .mb-* classes e propriedades CSS personalizadas (--mb-sheet-bg, --mb-sheet-ink, --mb-accent).

Configurações do lojista

Os lojistas personalizam seu tema no painel contra seus schemas. Precedência: padrões do schema ← valores do template ← valores do lojista. As configurações são armazenadas independentemente da versão do tema, então lançar uma atualização nunca apaga a personalização de um lojista.

Regras e limites

• Não <script>, sem manipuladores de evento inline, sem javascript: URLs, sem iframes — rejeitados no upload.
• Faça escape dos dados visíveis ao usuário: {{ item.name | escape }}.
• As renderizações têm recursos limitados (limites de tamanho de saída + trabalho do motor). Uma seção que falha em tempo de execução é ignorada, nunca uma página em branco; no upload é um erro fatal.
• As versões publicadas são imutáveis — atualizações são novas versões que passam por revisão.
• Use propriedades CSS lógicas (inline-size, margin-inline…) — os menus também são renderizados em RTL.