Arquivos do tema

Estrutura e responsabilidade dos arquivos

Um bundle de tema contém:

theme.json
layout.liquid
templates/
sections/
components/
assets/
  theme.css
  theme.js
  images/

• theme.json é o manifesto técnico. Mapeia os papéis fixos home, category, product, static, search, cart, checkout, confirmation e o papel opcional account, os components técnicos e somente os entrypoints assets/theme.css e assets/theme.js; não descreve escolhas visuais. A IA pode lê-lo, mas não alterá-lo. Revisões anteriores sem search usam explicitamente seu próprio template category como fallback. O tema Aura V3 declara cart; seu header usa cart.quantityTotal, isto é, a soma das quantidades de todas as linhas, como contador. Checkout e confirmação são inicialmente implementados pelo Aura; a confirmação recebe somente dados localizados por token opaco e nunca por um número sequencial informado isoladamente.

O carrinho anônimo atual é stateless e cada mutação substitui o cookie assinado completo. O runtime compartilhado serializa as operações na mesma página para evitar respostas concorrentes locais, mas isso não coordena múltiplas abas ou dispositivos. Uma garantia mais forte exigirá estado coordenado no servidor. Prévia e laboratório anunciam capabilities.cartMutations: false e nunca compartilham o carrinho da vitrine pública.

• layout.liquid é o documento-base que envolve o conteúdo renderizado. Enquanto a política atual permanecer, é somente leitura para a IA.
• templates/*.json compõem uma página. Cada item de sections informa id, type e, opcionalmente, dataSources. O array determina presença, identidade e ordem; HTML e CSS não pertencem a esse JSON.
• sections/*.liquid são blocos grandes e de estrutura livre, como hero, produtos, banners, categorias, depoimentos e conteúdo institucional.
• components/*.liquid são partes menores reutilizáveis, como header, footer e card de produto. Na política atual, a IA altera somente components existentes.
• assets/theme.css controla livremente a apresentação visual, sem paleta, layout ou variante predefinida obrigatória.
• assets/theme.js é somente leitura para a IA até existir um sandbox seguro para JavaScript gerado.
• assets/images/ é uma árvore livre de imagens do tema. Arquivos suportados são descobertos recursivamente e não são cadastrados, nomeados semanticamente nem enumerados em theme.json.

Os formatos aceitos nessa árvore são avif, gif, ico, jpg, jpeg, png, svg e webp, inclusive em subpastas. No Liquid, o formato canônico é o caminho relativo a assets, resolvido pelo filtro asset_url:

{{ 'images/banner.webp' | asset_url }}

O filtro converte o caminho na URL pública da revisão (ou em uma URL de dados na prévia) e falha explicitamente quando o arquivo não existe ou o caminho tenta sair da pasta permitida. O Liquid não deve conhecer IDs, revisões ou prefixos de armazenamento. O arquivo banner.webp é usado pelo tema Aura e pela sua preparação inicial; o runtime continua resolvendo qualquer asset permitido, sem atribuir significado especial a esse nome.

No CSS publicado, referências relativas ao próprio entrypoint funcionam normalmente:

.hero-banner {
  background-image: url('./images/banner.webp');
}

Quando o CSS é inserido inline no laboratório, a plataforma resolve apenas referências locais ./images/... existentes no bundle efetivo. URLs http:, https:, data: e blob: não são reescritas.

Exemplo mínimo de composição:

{
  "sections": [
    { "id": "hero", "type": "hero" },
    { "id": "featured_products", "type": "featured_products" }
  ]
}

O arquivo sections/hero.liquid recebe section.id e section.type. Um type precisa corresponder ao arquivo sections/{type}.liquid existente ou entregue como parte válida da alteração.

id e type aceitam letras minúsculas ASCII e números, com _ ou - entre grupos alfanuméricos. Por exemplo, type: "banner-promocional" aponta para sections/banner-promocional.liquid. Não use espaços, barras, pontos, acentos, separadores repetidos ou separadores no início/fim. Cada id deve ser único no template; o mesmo type pode ser usado em instâncias diferentes.

Os oito temas oficiais incluem sections/testimonials.liquid na Home, com três depoimentos demonstrativos completos e nomes fictícios. Os textos são estáticos e editáveis no Liquid; a apresentação e a responsividade ficam em assets/theme.css. Os cards aparecem preenchidos, sem rótulos de exemplo ou avisos na vitrine. As notas de demonstração usam comentários Liquid, que não são emitidos no HTML. Esses relatos não vêm de um cadastro de avaliações ou de compras. A orientação para substituir o conteúdo pelos relatos do cliente ocorre fora da vitrine. A seção pode ser reescrita, reorganizada ou removida como qualquer outra section; essa composição dos bundles oficiais não é um schema visual obrigatório. Lojas já publicadas recebem o bloco atualizado apenas por uma nova revisão.

Imagens editoriais na entrega de um tema

O Aura é diretamente o tema padrão do sistema e do laboratório. O catálogo oficial contém Aura, Lumen, Brisa, Fluxo, Nova, Cobalto, Pulso e Vértice; não mantenha um bundle duplicado chamado default. A origem técnica system-default identifica a revisão zero, não outro tema.

Ao criar um tema, entregue também as imagens finais utilizadas pelo layout. Heroes e banners editoriais precisam de imagens coerentes com a direção visual, sem placeholders provisórios, imagens esticadas ou dependência de um produto cadastrado para compor sua identidade. A quantidade, os nomes e a composição permanecem livres; essa orientação não cria campos no manifesto ou settings.

• Grave os arquivos em assets/images/, com nomes descritivos e resolução suficiente para os recortes de desktop e celular. Os banners oficiais atuais usam 1536 × 1024.
• Prefira WebP otimizado para fotografias. Confira nitidez e peso; procure manter cada banner abaixo de 500 KiB, como orientação editorial, não limite do validador.
• Não incorpore textos, preços, botões ou logos à fotografia: mantenha conteúdo e ações no HTML. Preserve contraste e ajuste object-position para o recorte.
• Resolva as imagens com asset_url no Liquid e caminhos relativos no CSS. Não use hotlinks nem URLs absolutas para assets distribuídos com o tema.
• Declare dimensões intrínsecas, decoding="async", prioridade alta somente para a imagem principal e loading="lazy" para imagens abaixo da primeira dobra. Use alt vazio para decoração e descrição útil para imagens informativas.
• Imagens editoriais não substituem fotos comerciais de produtos nem shop.logo. Produtos sem foto mantêm seu estado sem imagem; não atribua a eles fotografias genéricas que possam sugerir um item diferente do realmente vendido.
• Use imagens próprias, geradas ou com autorização de uso e registre sua origem. Composições abstratas geradas por script (SVG rasterizado) são aceitas como imagem editorial final quando coerentes com a direção do tema; Fluxo, Nova, Cobalto, Pulso e Vértice usam esse método, documentado em docs/design/theme-imagery.md. Valide bytes, resolução, referências e renderização com catálogo vazio em testes; confira recortes e legibilidade no navegador em ambiente autorizado.

Uma atualização do bundle oficial só entra em lojas já publicadas por nova revisão, com publicação explícita. Nunca regrave snapshots ativos para trocar fotografias.