Aparência
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 pasta | Responsabilidade | Exemplo de alteração |
|---|---|---|
theme.json | Manifesto técnico e caminhos dos templates | Consultar qual template atende a Home |
layout.liquid | Documento HTML que envolve as páginas | Estrutura compartilhada e chamadas de componentes |
templates/*.json | Presença e ordem das sections | Colocar uma vitrine depois de um banner |
sections/*.liquid | Estrutura de uma seção da página | Criar uma vitrine |
components/*.liquid | Trechos reutilizáveis | Reutilizar um card de produto |
assets/theme.css | Aparência e responsividade | Alterar espaçamento e colunas |
assets/theme.js | Interações visuais do tema-base | Preservar no fluxo de importação atual |
assets/images/ | Imagens do tema, inclusive subpastas | Adicionar 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.
Banner com várias imagens
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.
Navegação configurável nos temas oficiais
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."
}