Do primeiro clique ao tema pronto para publicar.
Um guia direto para montar, editar, validar e manter temas no SitePerto — escrito para quem está começando e para IAs que precisam gerar um pacote consistente.
01 · Comece aqui
O ciclo de um tema
Um tema pode ser um modelo da biblioteca, um ZIP compatível ou uma cópia de outro tema. Em todos os casos, revise primeiro e publique por último.
Crie ou instale
Abra Editar site → Temas. Instale um tema da biblioteca ou importe um ZIP. O primeiro tema compatível do projeto pode entrar em uso; os seguintes entram como rascunho.
Duplique quando quiser uma variação
Na biblioteca, use Duplicar. A cópia recebe o nome “Cópia de …”, preserva arquivos e configurações e sempre nasce como rascunho.
Edite o tema
Abra o editor visual para seções, blocos, configurações, menus e apps. Se seu plano permitir, abra também Editar código para trabalhar nos arquivos.
Salve como rascunho
Clique em Salvar. O rascunho é enviado para a API, validado e persistido sem alterar o tema que está em uso. Uma alteração em outra sessão gera conflito e não é sobrescrita.
Pré-visualize e publique
Use a prévia dentro do editor ou em nova aba. Quando a composição estiver aprovada, volte à biblioteca e use Usar este tema. Publicar desativa o tema anterior e ativa o escolhido.
02 · Arquivos
Um tema é um pacote, não apenas uma tela
O arquivo obrigatório é theme.json. Ele descreve a composição e os espelhos usados pelo renderer; os demais arquivos formam a fonte e os recursos do pacote.
theme.jsonManifesto obrigatório: formato, documento, seções, configurações, menus, schemas e código vinculado.layout/theme.htmlLayout nativo. Use {{sections}} para posicionar as seções na ordem salva.templates/Arquivos de organização do pacote. São preservados, mas não viram automaticamente um runtime.sections/Fontes de seções: .html, .css, .js, .block.html e schemas JSON vinculados.assets/CSS, JavaScript, SVGs, imagens, fontes, vídeo e áudio compatíveis.config/settings_data.json e settings_schema.json podem espelhar configurações globais do tema nativo.sectionPresets · blockPresetsPresets são opções prontas para adicionar uma seção ou bloco; cada um traz sua composição, rótulo, descrição e valores iniciais.snippets/ · locales/Arquivos aceitos e preservados no pacote; só serão usados se o runtime compatível os referenciar.O que é aceito
O importador reconhece texto UTF-8 em CSS, HTML/HTM, JS/MJS/JSX, JSON, SVG, Markdown, TXT, XML, YAML/YML, TS/TSX, CSV, mapas e webmanifest. Também preserva binários com MIME conhecido, como PNG, JPG/JPEG, WEBP, GIF, AVIF, ICO, WOFF/WOFF2, TTF/OTF, MP4, WEBM, MP3, OGG e WAV. Arquivos não reconhecidos ficam opacos e não são executados.
{
"schemaVersion": 2,
"sourceFormat": "native",
"editorDocument": { "version": 1, "operationVersion": 1 },
"sections": [{
"id": "hero",
"type": "slideshow",
"group": "template",
"title": "Capa",
"subtitle": "Apresentação principal",
"enabled": true,
"settings": { "title": "Uma mensagem clara" },
"blocks": []
}],
"settings": { "pageWidth": 1180, "primaryColor": "#6842c2" },
"menus": [{ "id": "header-menu", "name": "Menu principal", "location": "header", "items": [] }],
"code": { "html": "<main>{{sections}}</main>", "css": "", "js": "" }
}03 · Editor visual
Seções, blocos e campos
A estrutura do editor mantém a página legível: a coluna esquerda organiza; a prévia mostra o resultado; os ajustes editam o item selecionado.
Adicione seções pelo catálogo, altere a ordem, selecione, oculte, duplique ou remova.
Ajuste aparência global, cores, componentes, tipografia, movimento, marca e blog.
Edite os menus de cabeçalho e rodapé, seus itens, destinos, estado e abertura em nova aba.
Instale atalhos nativos opcionais, como WhatsApp, telefone, Instagram, avaliações e voltar ao topo.
Seções
- O catálogo separa seções, sobreposições e apps.
- A ordem é ajustável por arraste ou pelos controles de subir/descer.
- A movimentação respeita o grupo: cabeçalho, modelo, rodapé e sobreposições.
- Ocultar alterna
enablede preserva o item para depois. - Duplicar cria uma nova identidade e copia blocos e fonte da seção; cabeçalho e rodapé não são duplicados por esse comando.
- Remover tira a seção da composição. O pacote não ressuscita a seção só porque ela foi removida.
Blocos
- Um bloco é um item repetido dentro de uma seção: serviço, pessoa, depoimento, imagem ou ação.
- Os controles dependem do schema da seção; campos que o código não usa ficam indisponíveis.
- Blocos podem ser reordenados, ocultados e removidos. Em
flex-layout, grupos podem conter blocos aninhados. - O catálogo de blocos aplica limites declarados pela seção, como
maxBlockse limites por tipo. - Use o campo de título da seção para nomear a estrutura, não para substituir o conteúdo editorial.
{
"id": "servicos",
"type": "feature-grid",
"group": "template",
"title": "Serviços",
"subtitle": "O que sua empresa oferece",
"enabled": true,
"settings": {
"title": "Soluções para cada etapa",
"columns": "3",
"backgroundColor": "#ffffff"
},
"blocks": [
{ "id": "servico-1", "type": "feature", "title": "Estratégia", "enabled": true, "settings": { "description": "..." } }
]
}04 · Ajustes
Aparência que continua editável
Os controles visuais só aparecem quando existe schema e vínculo real no renderer. Um tema pode oferecer menos campos; isso é compatibilidade, não erro do editor.
Cores e contraste
Use cor principal, destaque, fundos, texto, superfície, bordas, texto secundário e foco do teclado. Botões, campos, cards, ícones e sobreposições têm cores próprias quando declaradas. Confirme contraste também sobre imagens.
Tipografia
Defina fonte de títulos e corpo, ritmo compacto/equilibrado/editorial, pesos, altura de linha, espaçamento entre letras, tamanho base e escala dos títulos.
Espaçamento e forma
A largura da página varia de 960 a 1440 px no controle global. Espaçamento entre seções e interno, raios de botões/campos/blocos e sombra mudam o ritmo sem editar CSS.
Responsividade
Alterne desktop e mobile na barra do editor. Schemas podem declarar valores para tablet ou celular que herdam de um campo no mesmo escopo; o editor preserva o override quando o valor não cabe no breakpoint.
Imagens e fundos
Escolha mídia da biblioteca ou envie um arquivo permitido. Ajuste proporção, encaixe, foco, posição desktop/mobile, sobreposição, degradê e textura no compositor de fundo.
Links e menus
Use URLs de páginas, âncoras ou destinos externos válidos. Menus têm até 8 menus e até 20 itens por menu. Revise o destino no desktop e no celular.
05 · Prévia
Veja o rascunho sem colocar o site no ar
A prévia é montada pela API a partir do estado local do editor. Ela não salva por si só, não publica e não envia formulários reais.
O que é rápido
Alterações de configurações são aplicadas no iframe existente quando cabem em um patch de até 128 operações e 32 KB. Isso mantém a posição da página e reduz atualizações pesadas.
O que exige render completo
Alterar código, menus ou estrutura — adicionar, remover, duplicar ou mover itens — usa a recompilação autoritativa. A última prévia válida continua visível enquanto ela acontece.
Boas práticas
- Faça um conjunto pequeno de mudanças e confira antes do próximo.
- Use o seletor de dispositivo para revisar desktop e mobile.
- Evite colar documentos HTML enormes em uma seção quando um arquivo do pacote resolve.
- Não use a prévia como teste de persistência: clique em Salvar e reabra para confirmar.
- Se a prévia falhar, leia o aviso e corrija o arquivo ou campo indicado; não repita uma gravação incerta.
06 · Proteção
Limites e compatibilidade
Os limites reduzem custo de processamento, evitam arquivos perigosos e mantêm a prévia previsível.
Bloqueios de caminho
Não use .git, .svn, node_modules, caminhos absolutos, .. ou arquivos de credencial como .env, credentials, chaves privadas e service accounts.
O que não é executado
O servidor não executa código do ZIP. Liquid/Shopify, dependências externas e formatos desconhecidos não ganham runtime por mudar o rótulo. Arquivos opacos podem ser exportados, mas não viram controles ou preview.
Onde o código roda
JavaScript nativo, quando permitido pelo plano e pelo tema, roda no renderer público. A prévia HTML usa uma sessão isolada com sandbox; o código não roda na origem autenticada do painel nem na API.
Por que a API grava
A API central valida projeto, permissão, formato, manifesto, arquivos, conflitos e limites em uma única transação. Painel e renderer são consumidores; não há fallback de gravação via Prisma no painel.
07 · Para IAs
Como gerar um tema robusto
Uma IA deve tratar o tema como um artefato portátil, com estrutura, dados e fonte coerentes. Aparência sem contrato produz um pacote difícil de editar e validar.
Defina a composição
Escolha uma intenção por seção, uma ordem clara e poucos blocos. Use IDs estáveis, minúsculos, sem espaços, e não reutilize o ID de outro item.
Gere a fonte vinculada
Para tema nativo, gere theme.json, layout/theme.html, assets/theme.css, assets/theme.js quando necessário e os arquivos de sections/ correspondentes.
Declare só o que funciona
Cada campo em settings ou blocks precisa aparecer no schema e ser consumido pelo HTML/CSS/runtime. Se um campo não tem vínculo, não o anuncie como configurável.
Prefira plataforma a dependências
Use HTML, CSS e JavaScript compatíveis com navegador. Não exija build, Node, servidor, Liquid, import maps ou uma API externa para a composição principal.
Valide antes do ZIP
Confira JSON, caminhos relativos, tamanho, contagem, referências de assets, slots e os estados desktop/mobile. Depois importe como tema separado, abra, pré-visualize e só então considere publicação.
Checklist de arquivos
theme.jsoné um objeto JSON e permanece na raiz.sourceFormatidentifica o runtime real; não use o rótulo para contornar capacidade.editorDocument.versioneoperationVersionsão1no contrato atual.- Use
{{sections}},{{settings.campo}},{{blocks}}e menus somente no contexto previsto. - Preserve chaves desconhecidas, schemas, presets, BOM, quebras de linha e arquivos extras.
Checklist de não compatibilidade
- Não inclua segredos, tokens, dados de clientes ou URLs temporárias.
- Não dependa de uma biblioteca instalada no servidor.
- Não espere que
templates/ousnippets/sejam interpretados como Liquid. - Não edite o mesmo campo no manifesto e no arquivo espelhado com valores divergentes.
- Não gere uma página sem
data-section-idoudata-block-idquando quiser seleção contextual no editor.
08 · Qualidade
Um tema que envelhece bem
A primeira versão deve ser bonita, mas também legível, rápida, acessível e fácil de substituir.
Acessibilidade
- Use HTML semântico, uma hierarquia de títulos coerente e foco visível.
- Forneça texto alternativo que explique a função da imagem.
- Não transmita informação somente por cor, movimento ou ícone.
- Respeite teclado e
prefers-reduced-motion.
Desempenho
- Comprima imagens, use a proporção do componente e evite duplicar mídia mobile sem necessidade.
- Prefira CSS local e poucos scripts pequenos; carrosséis e reveal devem ser opcionais.
- Não faça chamadas externas essenciais para a primeira pintura.
- Meça uma mudança por vez: a janela local registra duração e erros de preview.
SEO e conteúdo
- Um título principal, descrições verdadeiras e links que levam ao lugar certo.
- Não publique avaliações, números, certificados, endereços ou promessas inventadas.
- Use páginas e blog existentes nos menus; confirme status e slug antes de vincular.
- Prévia, rascunho e sites protegidos não devem ser tratados como conteúdo indexável.
Manutenção
- Exporte e guarde uma cópia antes de edições estruturais.
- Faça mudanças pequenas e nomeie seções para encontrá-las depois.
- Preserve arquivos desconhecidos ao editar o pacote.
- Após salvar, reabra o tema e teste o caminho de publicação.
09 · Ajuda
Perguntas frequentes
Quando o resultado não aparece, descubra primeiro em qual camada está o problema: seleção, schema, fonte, API ou renderer.
Salvei, mas a prévia não mudou. O que faço?
Confira se o campo está realmente vinculado ao código da seção. Um schema pode exibir um campo que o código não consome; nesses casos o editor o marca como indisponível. Reabra a prévia depois de salvar e confira o estado do tema.
Por que aparece “conflito entre theme.json e …”?
O manifesto e o arquivo espelhado foram alterados desde a última versão e não têm o mesmo valor. Escolha uma fonte, deixe os dois conteúdos coerentes, recarregue se outra sessão tiver salvo e tente novamente.
Posso importar um tema Shopify?
Não como tema compatível. Arquivos Liquid podem ser identificados e preservados durante a leitura, mas o SitePerto não executa Liquid. Gere ou exporte um pacote nativo SitePerto, ou use um HTML autônomo compatível.
Por que meu HTML autônomo não abre?
A entrada precisa ser HTML válido, estar na raiz do pacote e ser reconhecida como index.html/index.htm ou como entrada compatível. Recursos públicos precisam usar caminhos relativos seguros e extensões permitidas.
O preview envia um formulário ou abre o link?
Não. A prévia é isolada e protegida; formulários não enviam dados reais e a experiência de preview impede navegação externa. Ainda assim, trate o código como código real e valide a versão pública separadamente.
Perdi a conexão durante o autosave. Posso clicar várias vezes?
Não repita cegamente uma gravação de resultado incerto. O editor preserva o rascunho local, bloqueia novas tentativas automáticas após falha e libera nova tentativa quando houver outra edição. Se houver conflito 409, recarregue a versão atual e reconcilie.
Por que um app não aparece?
Apps são entradas nativas do catálogo e dependem do schema, da configuração e do dado necessário — por exemplo, um destino de WhatsApp ou rede social. Sem configuração, alguns apps permanecem instalados, mas não renderizam conteúdo útil.