Skip to content

Arquivos do tema ​

Estrutura e responsabilidade dos arquivos ​

Um bundle de tema contém:

text
theme.json
theme-identity.json  (opcional)
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 os papéis opcionais account e contact, 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.

  • theme-identity.json descreve a identidade nativa do tema para a IA. É opcional em revisões antigas e temas próprios; os vinte bundles oficiais o incluem. Possui version: 1 e os textos livres description, typography, layout, colors, imagery, copy e responsive, cada um com 1 a 1.500 caracteres, sem outras propriedades, em até 16 KiB. Não define presets, não configura o renderizador e não substitui CSS, Liquid ou editor.json. O arquivo acompanha instalação, importação/exportação e revisões imutáveis; é somente leitura para patches da IA. Para autoria externa, pode ser atualizado no ZIP e validado antes de uma nova revisão. Revisões sem o arquivo continuam usando seus arquivos atuais, sem buscar descrições pelo nome no catálogo oficial.

A identidade é enviada automaticamente ao planejamento, à edição, às sugestões de blocos, à personalização inicial, à adaptação na troca de tema e à geração de imagens do tema. Na troca, a descrição vem do destino; cores anteriores e a paleta aprovada são enviadas separadamente. Gerações de imagens posteriores ao patch recebem os valores resultantes da edição. O banner inicial progressivo usa o Aura oficial e a paleta aprovada do cadastro. A identidade orienta o resultado, mas não garante conformidade estética: confira a prévia. Não altera publicação, autorização, isolamento por loja ou acompanhamento por tarefas.

  • layout.liquid é o documento-base que envolve o conteúdo renderizado. É editável pela IA para scripts adicionais solicitados; preserve o marcador de conteúdo e os entrypoints técnicos.
  • templates/*.json compõem uma página. Cada item de sections informa id, type e, opcionalmente, dataSources e disabled booleano. confirmedContentHash é aceito apenas por compatibilidade com revisões anteriores, sem efeito na renderização; não o crie em novos temas. 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 permanece somente leitura para a IA e deve conservar o JavaScript original na importação. Códigos adicionais autorizados pelo lojista ficam como tags script literais em Liquid, sem alterar esse entrypoint.
  • custom-codes.json é opcional e registra códigos adicionais nomeados do tema. É mantido por compatibilidade com revisões que já usam esse formato. Não é obrigatório para identificar ou editar scripts; novas inclusões devem usar diretamente os arquivos Liquid.
  • 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:

liquid
{{ '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:

css
.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:

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

disabled é opcional e aceita somente booleano. Ausente ou false mantém a instância visível; true omite sua renderização no servidor, inclusive o Liquid, as consultas query_products executadas por ela e suas fontes dataSources exclusivas. O campo pertence exclusivamente ao template JSON da revisão. Preserve id, type, posição e dataSources para mostrar a mesma instância novamente; outras instâncias do mesmo tipo continuam independentes. Mesmo oculta, a instância precisa de definição e referências válidas e continua contando nos limites de tamanho, quantidade, fontes e segurança do bundle. Não use CSS display:none, hidden, enabled, settings ou arquivos laterais para representar essa visibilidade. Temas antigos sem disabled continuam válidos.

O arquivo sections/hero.liquid recebe section.id, section.type e section.position (1, 2, ... entre as seções ativas do template, útil para escolher o título principal). 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 vinte temas oficiais incluem sections/testimonials.liquid na Home, com três depoimentos demonstrativos completos e nomes fictícios. Os textos, fotos e notas são editáveis no painel direito e salvos em settings.items da ocorrência no template. O Liquid percorre esses itens; preserve esse vínculo ao editar com IA. A apresentação e a responsividade ficam em assets/theme.css. Os cards aparecem na prévia e na loja pública conforme a visibilidade da seção. Não há botão, hash obrigatório ou etapa de confirmação de autenticidade. Alterar os relatos não oculta a seção; disabled: true continua impedindo sua renderização. Revise e substitua os exemplos por relatos reais autorizados antes de publicar. 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. Revisões anteriores também seguem essa regra, independentemente de um confirmedContentHash antigo.

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 vinte temas, incluindo Aura, Lumen, Brisa, Fluxo, Nova, Cobalto, Pulso, Vértice, Elo, Faro, Marea, Nexo, Orbe, Prisma, Sereno, Solis, Trama, Vela, Vista e Zênite. 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.

Temas V3 · Liquid estrutura, CSS desenha, JSON compõe.