Skip to content

Organização do tema ​

Organize seu trabalho por responsabilidade. O formato dos arquivos é um contrato da plataforma; nomes de classes, aparência e composição visual são escolhas suas.

Arquivo ou pastaResponsabilidadeExemplo de alteração
theme.jsonManifesto técnico e caminhos dos templatesConsultar qual template atende a Home
layout.liquidDocumento HTML que envolve as páginasEstrutura compartilhada e chamadas de componentes
templates/*.jsonPresença e ordem das sectionsColocar uma vitrine depois de um banner
sections/*.liquidEstrutura de uma seção da páginaCriar uma vitrine
components/*.liquidTrechos reutilizáveisReutilizar um card de produto
assets/theme.cssAparência e responsividadeAlterar espaçamento e colunas
assets/theme.jsInterações visuais do tema-basePreservar no fluxo de importação atual
assets/images/Imagens do tema, inclusive subpastasAdicionar um banner próprio

Um caminho para trabalhar ​

Comece pelo template da página, identifique as sections e depois os components que elas renderizam. Crie nomes descritivos, como vitrine_presentes, e agrupe o CSS por componente ou seção. Evite espalhar o mesmo markup por várias páginas quando um component puder recebê-lo por parâmetros.

No formato tradicional não há settings visuais ou presets obrigatórios. JSON compõe, Liquid estrutura e CSS desenha. dataSources serve para declarar consultas comerciais, não para guardar cores, fontes ou resultados de produtos.

No Aura preparado para o editor visual, selecione Banner principal e use Adicionar slide ou Enviar várias imagens. Cada slide tem imagem desktop, imagem mobile opcional e URL opcional. Sem mobile, aparece a desktop; sem URL, a imagem não abre um destino. Reordene pelas setas ou remova slides individualmente. São aceitas até 12 imagens desktop, com PNG, JPEG ou WebP de até 5 MB por arquivo. O banner é somente imagem: título, frase e chamada ficam escritos na própria arte, sem texto HTML sobreposto. Para mudar a mensagem, envie outra imagem ou gere uma com IA escrevendo no pedido a frase desejada. Em Descrição da imagem, resuma a mensagem e o conteúdo da arte: ela é lida por leitores de tela e buscadores e não aparece sobre o banner. No topo da Home, um título principal (H1) oculto mantém o nome da loja.

Escolha troca automática, intervalo de 3 a 15 segundos, transição, setas e indicadores. Confira desktop e celular antes de publicar. As imagens ficam nos assets da revisão, com caminhos em settings.slides; Liquid gera a estrutura, CSS desenha e o runtime compartilhado controla a navegação. Revisões existentes exigem preparação explícita; nenhum tema publicado é convertido automaticamente.

Organizar e ocultar instâncias ​

Em Seções da página, localize pelo nome ou identificador e selecione o bloco. Quando ele estiver confirmado na prévia, a seleção abre sua edição com IA. Use a alça de arraste ou os botões Mover para cima/baixo para organizar. Ocultar e Mostrar preservam a instância e seus dados. O painel atende Home, Produto, Categoria, Busca, Página estática, Carrinho, Cadastro/Conta, Checkout, Confirmação e Contato, conforme os templates disponíveis. Adicione blocos editoriais e reorganize a página; no editor visual, use os campos declarados ou o Designer Virtual para mudar o desenho. Blocos que contêm formulários ou controles funcionais podem ser movidos e editados, mas os comandos diretos não permitem removê-los, duplicá-los, ocultá-los ou limitar sua exibição por dispositivo. Blocos extras mantêm essas opções. A proteção acompanha o conteúdo e os partials, inclusive em templates compartilhados com a Home. Checkout e Confirmação usam demonstrações, sem pedidos, cotações ou pagamentos reais. Confira o aviso de compartilhamento: alterar um template alcança todas as páginas atendidas por ele. Adicionar seção continua disponível pela IA.

Em telas largas, a lista fica à esquerda, a prévia no centro e a edição à direita. Expanda uma seção para acessar textos e outros elementos confirmados. Esses itens são atalhos de edição, sem arraste independente. Áreas do layout identificadas aparecem separadamente como compartilhadas. Temas próprios compatíveis usam a mesma composição e não precisam declarar um schema visual. Elementos ambíguos, repetidos ou não confirmados não recebem edição individual; o assistente continua disponível. Veja o guia de navegação lateral.

No arquivo JSON, use disabled: true para ocultar uma instância e false para reexibi-la. O campo é opcional, booleano e exclusivo da composição. A instância oculta não gera HTML nem consultas exclusivas, mas continua sujeita à validação completa e aos limites do bundle. O Liquid e as demais utilizações do mesmo type são preservados. Veja o exemplo de vitrine.

Desfazer/refazer cobrem somente a sequência de organização em memória. Outras edições iniciam nova sequência; navegar preserva o rascunho. Falha de prévia permite corrigir ou desfazer. Revise antes de publicar; recarregar ou sair não salva alterações pendentes entre sessões.

Componentes recebem argumentos ​

Use render e passe explicitamente os dados necessários. Um component não deve presumir que herda todos os objetos da página. Veja o exemplo completo de vitrine.

Escolha o alcance da alteração ​

Mudar um component afeta todos os locais que o usam. Mudar o template institucional afeta todas as páginas atendidas por ele. Se uma seção precisa aparecer duas vezes, cada instância deve ter um id diferente.

Confira o contrato completo dos arquivos e os limites de importação.

Partir de um tema pronto ​

O Aura é diretamente o tema padrão do sistema e do laboratório; não existe um bundle separado default. A biblioteca do editor oferece Aura, Lumen, Brisa, Fluxo, Nova, Cobalto, Pulso, Vértice, Elo, Faro, Marea, Nexo, Orbe, Prisma, Sereno, Solis, Trama, Vela, Vista e Zênite. Selecionar um deles abre um rascunho; a vitrine publicada muda somente após a publicação explícita.

O Lumen traz tipografia Inter, fundo branco, botões arredondados e cabeçalho fixo. Sua Home compõe um banner e uma grade de produtos da loja. Para personalizar o banner, edite sections/hero.liquid e o asset assets/images/banner.webp; a logo usa a identidade global da loja. As demais páginas já incluem os hooks de produto, carrinho, checkout, pagamentos e conta do runtime compartilhado.

O Brisa traz a direção editorial da referência: Newsreader nos títulos, Red Hat Text no corpo, preto e branco, cantos retos e imagens amplas. A Home combina hero, coleções, produto em destaque, quatro produtos, banner editorial e um comparador de imagens. Textos e estrutura ficam nas sections; cores, proporções e espaçamentos ficam em assets/theme.css. As fotografias decorativas estão em assets/images/banner.webp e assets/images/detail.webp, resolvidas por asset_url. A logo continua sendo a identidade global da loja.

Coleções e produtos vêm dos dados da loja; blocos sem dados comerciais são omitidos ou exibem o estado vazio. O comparador é apenas visual, e compra, carrinho, checkout, pagamentos e conta usam o runtime compartilhado.

O Fluxo usa Instrument Sans sobre fundo escuro em oliva e creme; sua Home divide o hero entre declaração e imagem, lista categorias em tiles tipográficos, alterna dois blocos de mídia com texto e mostra oito produtos. O Nova usa Liter, creme quente, laranja e lilás: o hero apresenta a marca em largura total sobre a imagem editorial, seguido por dois blocos de cor, oito produtos e um par de categorias; a página de produto termina com uma faixa em movimento das categorias. O Cobalto usa Proza Libre e Archivo com bordas de 2px, cantos arredondados e sombras sólidas em creme e framboesa: hero com caixa de texto, cards de categoria e oito produtos. O Pulso usa Oswald em caixa alta sobre preto com amarelo neon e ciano: hero dividido com título gigante, quatro produtos em retrato e uma faixa de categorias; o rodapé abre com uma faixa de busca. O Vértice usa Cormorant em petróleo sobre branco: título centralizado, faixa de imagem, seis produtos em três colunas e dois blocos em petróleo.

Essas escolhas pertencem aos arquivos do tema e podem ser redesenhadas. Nenhuma delas cria um novo campo visual no manifesto ou uma configuração paralela.

Todos os vinte temas incluem três depoimentos demonstrativos preenchidos na Home, com relatos e nomes fictícios em settings.items no template. O arquivo sections/testimonials.liquid percorre essa lista. No painel direito, configure título, nome, texto, complemento, foto e nota de 1 a 5 estrelas. É possível ocultar fotos ou estrelas, adicionar até 24 relatos, reordená-los e criar várias seções independentes. Fotos aceitam PNG, JPEG ou WebP de até 5 MB. Os cards não mostram rótulos de exemplo nem avisos de substituição. Para trocar os relatos, use o formulário ou edite os valores do template; para mudar o visual, edite assets/theme.css; para remover ou reordenar o bloco, altere templates/home.json. Não há leitura de avaliações ou compras cadastradas para esse conteúdo. A seção aparece na prévia e na loja pública sem confirmação de autenticidade; use disabled: true para ocultá-la. Um confirmedContentHash antigo não interfere na renderização. A orientação ao cliente sobre a troca dos relatos ocorre fora da vitrine. Revisões publicadas recebem a alteração somente por uma nova revisão.

Os temas-base incluem a assinatura “Tecnologia LojaVirtual” no rodapé, com link para o site da plataforma. A imagem fica em assets/images/lojavirtual/ e o component components/footer.liquid a resolve por asset_url, inclusive na prévia. Aura, Lumen, Brisa e Vértice usam a versão para fundo claro; Fluxo, Nova, Cobalto e Pulso, cujo rodapé é escuro ou saturado, usam a versão para fundo preto. Nos novos temas, Elo, Faro, Marea, Trama e Vela usam a versão clara; Nexo, Orbe, Prisma, Sereno, Solis, Vista e Zênite usam a versão para fundo preto. Ao redesenhar o rodapé, mantenha o contraste adequado e a proporção da imagem em assets/theme.css.

Essa assinatura é separada de shop.logo, que continua identificando o lojista. Lojas com revisões anteriores recebem esse rodapé somente ao publicar uma nova revisão com os arquivos atualizados.

Entregar imagens junto com um tema novo ​

Inclua as imagens editoriais finais utilizadas pelo layout em assets/images/ antes de entregar o tema. Banners devem combinar com sua direção visual e funcionar no celular; a mensagem fica na própria imagem, descrita no alt do slide. Não deixe placeholders provisórios nem dependa de fotos do catálogo para a identidade do hero.

Os vinte temas incluem artes completas em assets/images/banner.webp (1942 × 809) e assets/images/banner-mobile.webp (1122 × 1402), geradas com GPT Image 2.5 Flare. Título, subtítulo e chamada estão nos pixels, e o alt do slide descreve a chamada. O <picture> escolhe a versão de cada dispositivo e preserva sua proporção sem recorte. No Aura, a partir de 768px de largura, o banner tem no máximo 500px de altura visível (max-height com object-fit: cover), recortando o excesso vertical a partir do centro. O banner gerado na criação da loja já sai em 1536 × 500. O Vela mantém a imagem depois da grade de produtos. As imagens secundárias permanecem independentes. São cenas demonstrativas substituíveis; preserve fotos reais nos cards e o estado vazio quando faltar imagem comercial. Os prompts estão em docs/design/banner-campaigns-25.json.

Siga os critérios de resolução, acessibilidade, otimização e validação da referência de estrutura. Escolha livremente os nomes e a quantidade de arquivos, sem adicionar um cadastro de imagens ao manifesto.

Editor visual optativo ​

Revisões com editorVersion: 1 no manifesto usam editor.json para declarar campos e settings em cada ocorrência da composição para armazenar valores. O Liquid lê section.settings; cabeçalho e rodapé leem theme.settings, encaminhado explicitamente nos renders. O editor gera os formulários dessas declarações e aplica alterações sem IA. O Designer Virtual mantém o mesmo rascunho e precisa preservar a coerência dos campos. Consulte o capítulo Editor visual com configurações declaradas no manual oficial para tipos, limites, imagens, links e compatibilidade. O Aura mantém seu preparador; os outros dezenove bundles oficiais já declaram os controles, sem migrar temas personalizados ou alterar a revisão publicada.

No editor visual, Adicionar componente abre os tipos preparados pelo tema. O painel reúne filtros da vitrine, aparência dos cartões e Mostrar em (todos, computador ou celular). Duplicar e Remover exigem confirmação e mantêm desfazer/refazer. displayOn aplica celular até 767 px e computador a partir de 768 px. As consultas ficam em dataSources.products.query, com os mesmos limites e isolamento comercial existentes.

Nas revisões compatíveis dos vinte temas oficiais, o cabeçalho declara visibilidade de logo, menu, conta e carrinho, modo de busca e disposição no computador. A seleção e a ordem de categorias da Home são independentes dos links do menu. A biblioteca inclui as seções Busca e Categorias. Os nomes e destinos comerciais vêm do cadastro; os arquivos da revisão guardam somente referências e opções editoriais.

Adicionar, remover e reordenar categorias atualiza a prévia imediatamente com a lista atual. A troca entre modo automático e seleção manual também é aplicada ao rascunho. Aguarde a aplicação antes de editar novamente; a loja pública continua dependendo de publicação explícita.

Veja como configurar menu, busca e categorias. Os demais temas mantêm a disposição original em Padrão do tema e oferecem três alternativas no computador. Seus banners editoriais permanecem na composição; o carrossel Banner principal é adicionável. Imagem, Texto, HTML e Vitrine de produtos também fazem parte da biblioteca. Revisões existentes não são convertidas automaticamente.

A faixa de benefícios usa uma lista de itens no JSON de cada seção: ícone, título, descrição e link. O painel e a edição direta usam os mesmos valores.

Cores globais e cores dos elementos ​

editor.json guarda a paleta em shared.palette; as ocorrências em templates/*.json podem usar campos theme_color declarados pelo tema. Cada parte pode preservar o padrão, referenciar um ID da paleta ou receber uma cor própria. O Liquid recebe a cor resolvida, enquanto os arquivos mantêm o vínculo original. Confira o exemplo de cores vinculadas.

Rodapé com blocos ​

Nos temas oficiais compatíveis, shared.footer em editor.json reúne Aparência, Conteúdo e Faixa inferior. O campo blocks, do tipo footer_blocks, ordena até oito blocos de marca, menus, categorias, atendimento e redes sociais. Menus podem se repetir. Os demais tipos são únicos. Ocultar preserva os valores; remover retira o bloco. A apresentação e o título das categorias permanecem nos campos description e categories_title.

O Liquid e o CSS continuam editáveis. A base comum é distribuída dentro de cada bundle, preservando a portabilidade por ZIP. Rodapés personalizados não são sobrescritos pela preparação dos controles. Confira o guia de configuração do rodapé.

Identidade nativa para a IA ​

O arquivo opcional theme-identity.json acompanha o tema e suas revisões. Descreve sua linguagem visual, tipografia, composição, cores, imagens, textos e adaptação ao celular. Os vinte temas oficiais incluem uma descrição própria.

O Designer Virtual, as sugestões de blocos, as imagens e a adaptação na troca de tema recebem essa referência automaticamente. Na troca, vale a identidade do tema escolhido; as cores personalizadas da loja anterior continuam como referência. Pedidos explícitos e personalizações atuais prevalecem sobre padrões nativos. Confira o resultado na prévia antes de publicar.

O arquivo não altera a renderização nem substitui CSS, Liquid ou configurações. Revisões antigas sem ele continuam funcionando com seus arquivos atuais. Uma atualização do tema oficial não reescreve a identidade das revisões já instaladas. A IA lê a descrição, mas não a modifica por patch; autores externos podem atualizá-la no ZIP. Consulte os limites na referência de arquivos.

Exemplo de identidade para um tema próprio:

json
{
  "version": 1,
  "description": "Editorial delicado, imagens amplas e bastante espaço em branco.",
  "typography": "Newsreader leve nos títulos e Red Hat Text no corpo; contraste entre serifa delicada e texto simples.",
  "layout": "Cantos retos, linhas finas, cards verticais e alternância entre coleções, destaque e blocos editoriais; cabeçalho com marca central.",
  "colors": "Base branca e preta com contraste limpo; cores personalizadas devem manter a leveza.",
  "imagery": "Fotografia ampla e serena, luz natural, detalhes táteis e composição pouco carregada.",
  "copy": "Calmo e refinado, títulos breves e descrições cuidadosas sem excesso promocional.",
  "responsive": "Manter respiro e detalhes fotográficos sem seções excessivamente altas; empilhar conteúdos preservando hierarquia."
}

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