Um novo Theme (baseado em seções e blocos) organiza seu código em pastas com responsabilidades bem delimitadas: sections, blocks e snippets separam o editável do estrutural, templates/ define a composição de páginas, e config/ centraliza os settings globais do Theme.
Visão geral
ipanema/
├── blocks/ # Blocos reutilizáveis com schema (usados dentro de sections)
├── config/
│ ├── settings_schema.json # Schema de settings globais do Theme
│ └── settings_data.json # Valores salvos dos settings globais
├── layouts/
│ ├── layout.tpl # Wrapper HTML principal (head, header, content, footer)
│ └── resources/
│ ├── icons-sprite.tpl # Sprite SVG inline
│ └── style-tokens.tpl # Custom properties CSS (fontes, cores)
├── sections/ # Sections de página com schema (header, footer, hero, banners, ...)
├── snippets/ # Partials sem schema (cart/, payments/, product/, forms/, ...)
├── static/
│ ├── css/
│ │ ├── style-critical.css # CSS crítico inlinado no <head>
│ │ ├── style-utilities.css # Classes utilitárias inlinadas no <head>
│ │ └── style-async.css # CSS não crítico, carregamento assíncrono
│ ├── js/
│ │ ├── store.js # Lógica client-side do Theme (vanilla JS)
│ │ ├── libraries-standalone.js
│ │ └── libraries.js.tpl
│ └── checkout.scss.tpl # Estilos de branding para o checkout
├── templates/
│ ├── pages/ # Templates de página (home.json, product.json, ...)
│ │ └── account/ # Páginas de conta (login, register, orders, ...)
│ └── layout/ # Templates de layout (header.json, footer.json)
└── translations/
├── <locale>.json # Strings do storefront (orientados ao comprador)
└── <locale>.schema.json # Labels do editor (orientados ao usuário)
| Pasta | Propósito |
|---|---|
blocks/ | Componentes reutilizáveis com schema, usados dentro de sections. |
config/ | Schema e valores salvos dos settings globais do Theme. |
layouts/ | O wrapper HTML dentro do qual toda página é renderizada. |
sections/ | Unidades de largura total com schema, settings, blocos e presets. |
snippets/ | Partials sem schema para funcionalidades de experiência de compra. |
static/ | CSS compilado, JavaScript e estilos de checkout. |
templates/ | Arquivos JSON que definem como as páginas são compostas. |
translations/ | Traduções do storefront (*.json) e labels do editor (*.schema.json). |
Detalhe por pasta
layouts/
Contém o wrapper HTML que envolve toda página, além dos assets inline compartilhados.
| Arquivo | O que faz |
|---|---|
layout.tpl | Shell HTML principal: <head>, fontes, CSS crítico, tokens de estilo, header, {{ page_template_content }}, footer, modais, notificações. |
resources/icons-sprite.tpl | Sprite SVG inline, incluído próximo ao início do <body>. |
resources/style-tokens.tpl | Custom properties CSS (tokens de fontes e cores) injetados como <style> inline no <head>. |
A página ativa é renderizada através de:
<main id="MainContent" class="main-content main-container" role="main">
{{ page_template_content }}
</main>
O header e o footer são renderizados a partir de layout templates compartilhados entre todas as páginas:
{% layout_template 'header' %}
{# ... contenido de página ... #}
{% layout_template 'footer' %}Essas duas chamadas renderizam templates/layout/header.json e templates/layout/footer.json, respectivamente.
config/
Settings de escopo global do Theme (cores, tipografia, defaults de header/footer, …) como JSON. Apenas dois arquivos: um para o schema, outro para os valores salvos.
| Arquivo | O que faz |
|---|---|
settings_schema.json | Schema de settings globais — favicon, cores, tipografia, botões, header, footer, product card, carrinho, checkout, etc. |
settings_data.json | Valores salvos dos settings globais. |
Os settings globais são acessíveis a partir de qualquer .tpl via settings.*:
{{ settings.background_color }}
{{ settings.font_headings }}sections/
As sections são as unidades de largura total de uma página. Se agrupam em famílias:
| Grupo | Arquivos representativos | Propósito |
|---|---|---|
| Layout | header.tpl, footer.tpl, announcement-bar.tpl | Chrome compartilhado em cada página. |
| Conteúdo principal | main-product.tpl, main-cart.tpl, main-products-grid.tpl, main-blog.tpl, … | Conteúdo central de um tipo de página específico. |
| Marketing / marca | hero.tpl, banners.tpl, slideshow.tpl, video.tpl, image-with-text.tpl, testimonials.tpl, featured-brands.tpl, newsletter.tpl, rich-text.tpl, faq.tpl, timer-offers.tpl | Sections reutilizáveis de storytelling e merchandising. |
| Produto | product-list.tpl, featured-product.tpl, related-products.tpl, product-description.tpl | Apresentação de produtos ao longo das páginas. |
Cada arquivo de section termina com um bloco {% schema %}. O nome que aparece no editor vem do campo name do schema (uma chave t:).
blocks/
Os blocks são renderizados dentro de sections e se agrupam por função:
| Categoria | Exemplos |
|---|---|
| Conteúdo genérico | heading.tpl, text.tpl, image.tpl, button.tpl, video.tpl, menu.tpl, group.tpl, accordion.tpl |
| Slideshow / banners | slide.tpl, carousel-slide.tpl, banner.tpl |
| Produto | product-media.tpl, product-info.tpl, purchase-info.tpl, products.tpl, description.tpl, product-recommendations.tpl |
| Categorias / marcas | category-nav.tpl, category-item.tpl, brand-group.tpl, brand-logo.tpl |
| FAQ / depoimentos / icon-text | faq-group.tpl, faq-list.tpl, faq-item.tpl, testimonial-group.tpl, testimonial.tpl, icon-text-group.tpl, icon-text-item.tpl |
| Header / footer | header-logo.tpl, header-navigation.tpl, header-utilities.tpl, footer-institutional.tpl, footer-menu.tpl, footer-newsletter.tpl |
| Formulários / utilitários | newsletter-form.tpl, announcement.tpl, payment-icons.tpl |
Cada arquivo de block também termina com um {% schema %}.
snippets/
Partials sem schema, organizados por domínio de experiência de compra:
| Subpasta | Cobre |
|---|---|
cart/ | Itens do carrinho, modal/drawer, totais, fulfillment, cross-selling. |
payments/ | Parcelas, meios de pagamento, bancos, detalhe de pagamento. |
product/ | Formulário de produto, variações, galeria de imagens, vídeo, quantidade, detalhe de pagamento. |
product-list/ | Card de grade de produtos, filtros (preço, propriedades, categoria), paginação, ordenação. |
forms/ | Inputs, selects, dropdowns, formulários de login/cadastro, reCAPTCHA. |
shipping/ | Calculadora de frete, opções, filiais, progresso de frete grátis. |
header/ | Formulário de busca, navegação mobile, seletor de idioma. |
navigation/ | Painéis de navegação, menu hambúrguer. |
footer/ | Links legais, info de claim, logos de meios de pagamento e envio. |
social/ | Botões de compartilhamento, links de contato, chat de WhatsApp. |
subscriptions/ | Planos de assinatura, preço, alertas. |
promotions/ | Labels de promoção, mensagens de presente, tabelas de desconto. |
placeholders/ | Skeleton loaders. |
modals/ | Modal de quick-shop, wrapper de modal genérico. |
| (raiz) | icon.tpl, image.tpl, card.tpl, breadcrumbs.tpl, labels.tpl, notification.tpl. |
Os snippets são incluídos com {% include 'snippets/<caminho>.tpl' %}, opcionalmente com contexto:
{% include 'snippets/notification.tpl' with { type: 'add_to_cart' } %}static/
CSS compilado, JavaScript e o template SCSS de checkout. São referenciados a partir de layouts/layout.tpl.
| Arquivo | O que faz |
|---|---|
css/style-critical.css | CSS above-the-fold, inlinado no <head>. |
css/style-utilities.css | Classes utilitárias, inlinadas no <head>. |
css/style-async.css | CSS below-the-fold, carregado de forma assíncrona. |
js/libraries-standalone.js | Bibliotecas de terceiros empacotadas (Swiper, lazysizes, …). |
js/libraries.js.tpl | Loader com template para bibliotecas adicionais e configuração. |
js/store.js | Lógica client-side do Theme (vanilla JS). |
checkout.scss.tpl | Estilos de branding para o checkout. |
templates/
Arquivos JSON que compõem páginas e regiões de layout compartilhadas. Há dois tipos:
Page templates — templates/pages/*.json. Definem o que é renderizado dentro de <main> para cada tipo de página.
| Arquivo | Página |
|---|---|
pages/home.json | Home |
pages/product.json | Detalhe de produto. |
pages/category.json | Categoria / coleção. |
pages/cart.json | Carrinho de compras. |
pages/search.json | Resultados de busca. |
pages/blog.json, pages/blog-post.json | Listagem de blog e post. |
pages/page.json | Página personalizada genérica. |
pages/contact.json | Formulário de contato. |
pages/password.json | Loja protegida com senha. |
pages/404.json | Erro 404. |
pages/account/*.json | Páginas de conta (login, register, reset, newpass, info, addresses, address, orders, order). |
Layout templates — templates/layout/*.json. Definem as regiões de header e footer compartilhadas entre todas as páginas. São renderizados a partir de {% layout_template 'header' %} e {% layout_template 'footer' %} em layouts/layout.tpl.
| Arquivo | Região |
|---|---|
layout/header.json | Header do site, compartilhado entre todas as páginas. |
layout/footer.json | Footer do site, compartilhado entre todas as páginas. |
translations/
Dois tipos de arquivos de locale: strings do storefront (orientados ao comprador) e labels do editor (orientados ao usuário).
| Padrão de arquivo | Propósito |
|---|---|
<locale>.json (ex. en.json, es.json, pt.default.json) | Strings exibidas ao comprador no storefront. |
<locale>.schema.json (ex. en.schema.json, es.schema.json) | Labels exibidos ao usuário no editor. |
Locales disponíveis: en, es, es_AR, es_CL, es_CO, es_MX, pt.default.
Fallback de locale — quando o storefront solicita um locale (por exemplo pt_BR), o resolver busca o arquivo de tradução nesta ordem:
translations/pt_BR.json— correspondência exata.translations/pt.json— correspondência apenas por idioma.translations/<qualquer>.default.json— o default regional para esse idioma (ex.translations/pt.default.json).
O mesmo fallback se aplica aos arquivos .schema.json. Isso permite distribuir um único default regional (ex. pt.default.json) e adicionar arquivos por país apenas quando o copy precisa se diferenciar.