Temas e CLI › Temas

Verificador de temas

O verificador confere o código de um tema e aponta cada problema com o código da regra, o arquivo, a linha e a coluna. É o mesmo em todo lugar: no servidor, a cada gravação do tema; no editor de arquivos do painel; na conferência antes de publicar; na API Admin (GET /themes/{id}/check e GET /themes/{id}/files); e no CLI, sem rede (denaryx tema check, ver Os comandos). O que passa na sua máquina passa na plataforma.

Cada regra tem uma gravidade:

• erro: o tema pode ser salvo assim, pela metade, mas não pode ser publicado;
• aviso: não impede nada; aponta o que a página mostra errado, ou o que ninguém usa.

O código da regra (unknown_snippet) é estável, em inglês, e é por ele que um programa decide; a mensagem, em português, é para gente ler. Na API Admin, o problema traz code, file, line, column, end_line, end_column, message e severity (error ou warning).

Um aviso que não serve ao projeto se desliga no denaryx.json, e só no CLI: "verificador": { "regras": { "unused_snippet": "desligada" } }. Erro não se desliga, e o servidor ignora essa configuração: o que impede a publicação é igual para todos.

Os limites de peso também se ajustam no denaryx.json, em KB: "verificador": { "limites": { "js": 300 } }. Os padrões são js 250, css 150, imagem 500, fonte 200, video 5120, html 500. O servidor confere com os padrões, e o aviso de peso que o projeto aceitou continua aparecendo no painel.

O código e as páginas

A maioria das regras lê o código do tema, sem desenhar nada: é o que o servidor, o painel e o denaryx tema check rodam. Algumas só são exatas no HTML final, com os dados da loja: o denaryx tema check --paginas desenha, pela prévia, a página de exemplo de cada template (o primeiro produto, a primeira categoria, a primeira página institucional, a busca, o carrinho, a página inicial e a 404), como o ensaio do "Antes de publicar", e passa sobre o HTML de cada uma as regras marcadas com "páginas" na coluna Onde. Também mostra o tempo de cada página e as seções mais lentas.

Nas páginas, um erro (a página que não abre, o Liquid que falha com os dados da loja) não impede publicar, porque depende dos dados de agora; mas faz o check --paginas sair com o código 1, para o CI parar antes.

Versão do conjunto de regras: 6. Quando ela sobe, o tema guardado com uma versão anterior é conferido de novo ao conferir e ao publicar.

As regras

Estrutura

invalid_file

Arquivo fora da estrutura do tema · erro · código

O arquivo está fora das oito pastas do tema (layout, templates, sections, blocks, snippets, assets, config, locales), numa subpasta, com uma extensão que a pasta não aceita, repetido, grande demais, ou o locale tem o nome fora do formato idioma-REGIÃO. Mova, renomeie ou divida o arquivo.

invalid_json

JSON inválido · erro · código

O arquivo (ou o {% schema %} de uma seção ou de um bloco) não é um JSON válido: falta uma vírgula, sobra uma vírgula no fim de uma lista ou uma aspa não fecha. A mensagem traz o que o leitor de JSON achou.

missing_layout

Falta o layout theme · erro · código

Todo tema precisa de layout/theme.liquid: é o layout das páginas que não escolhem outro.

missing_required_template

Falta um template obrigatório · erro · código

Toda loja usa os templates index, product, collection, search, cart, page e 404. Sem um deles, aquela página da vitrine fica sem desenho. Crie o template, em JSON ou em Liquid.

unknown_section

Seção que não existe · erro · código

Um template ou um grupo de seções cita uma seção cujo arquivo não existe em sections/. Crie a seção ou corrija o "type".

unknown_layout

Layout que não existe · erro · código

O template pede um layout que não existe em layout/. Crie o layout ou corrija o nome.

unknown_snippet

Snippet que não existe · erro · código

O {% render %} chama um snippet que não existe em snippets/. Na loja publicada, a seção inteira some sem aviso; por isso é erro. Crie o snippet ou corrija o nome.

unknown_asset

Asset que não existe · aviso · código

O filtro asset_url aponta para um arquivo que não existe em assets/, e o navegador recebe um 404. Envie o arquivo ou corrija o nome.

unused_snippet

Snippet que ninguém usa · aviso · código

Nenhum {% render %} do tema chama este snippet. Apague-o, se sobrou de uma versão antiga. A regra só roda quando todos os {% render %} do tema usam o nome entre aspas.

unreachable_section

Seção que ninguém alcança · aviso · código

A seção não tem preset, então o lojista não consegue acrescentá-la no editor, e nenhum template, grupo, layout ou {% section %} a usa. O nome dela entre aspas em outro arquivo (o JavaScript que a pede pela renderização de seção, com ?section_id=) conta como uso. Dê a ela um preset, use-a num template ou apague o arquivo.

Liquid

liquid_syntax_error

Erro de sintaxe do Liquid · erro · código

O Liquid do arquivo não pode ser lido: uma tag não fecha, uma expressão está incompleta, ou há mais de um {% stylesheet %} ou {% javascript %} no arquivo. Enquanto o erro existir, o arquivo não desenha nada.

unknown_filter

Filtro que não existe · erro · código

O filtro usado não existe no motor da plataforma. Confira a grafia; quando há um nome parecido, a mensagem sugere. A lista dos filtros fica no editor de arquivos, ao completar o código.

unknown_tag

Tag que não existe · erro · código

A tag usada não existe no motor da plataforma. Confira a grafia; quando há um nome parecido, a mensagem sugere. {% include %} e {% block %} também são recusados: use {% render %} e os blocos do schema.

missing_translation

Texto que falta no locale padrão · aviso · código

O filtro t pede uma chave que o arquivo de locale padrão (locales/*.default.json) não tem, e a página mostra "Translation missing" no lugar do texto. Acrescente a chave ao locale padrão ou corrija o nome.

undefined_object

Objeto que o tema não recebe · aviso · código

O layout, o template, a seção ou o bloco lê uma variável que não é um objeto do tema nem foi criada antes com assign, capture ou for, e ela sai sempre vazia. Confira a grafia ou crie a variável antes de usar. Os snippets ficam de fora: as variáveis deles vêm de quem os chama.

page_failed

Página que não abre · erro · páginas

A página de exemplo do template não foi desenhada: o desenho passou do tempo ou do tamanho, o layout falhou ou a página respondeu com erro. Na loja, o visitante vê uma página de erro. A mensagem diz o motivo; o denaryx tema dev mostra a página com o erro.

render_error

Erro ao desenhar a página · erro · páginas

O Liquid falhou ao desenhar a página de exemplo com os dados da loja (um laço sobre o que não é lista, uma conta com texto, um filtro com o argumento errado). Na loja, a parte que falhou sai em branco. A mensagem traz o arquivo e a linha.

Schema e arranjos

invalid_schema

Schema inválido · erro · código

O {% schema %} de uma seção ou de um bloco, ou o config/settings_schema.json, não segue o formato: falta um campo obrigatório, um ajuste tem tipo desconhecido, uma chave se repete ou há mais de um {% schema %} no arquivo. A mensagem diz onde.

invalid_template

Arranjo de seções inválido · erro · código

Um template em JSON, um grupo de seções ou o config/settings_data.json não segue o formato: uma seção aparece em "order" e não em "sections" (ou o contrário), um preset citado não existe ou um campo tem o tipo errado.

template_setting_not_in_schema

Ajuste que o schema não tem · aviso · código

O template ou o grupo dá valor a um ajuste que o schema da seção (ou do bloco) não declara. O valor é ignorado. Acrescente o ajuste ao schema ou tire o valor.

block_type_not_accepted

Bloco que a seção não aceita · aviso · código

O template ou o grupo põe na seção (ou num bloco) um bloco de um tipo que ela não declara, nem como bloco próprio nem pelos blocos do tema ({ "type": "@theme" }). O bloco não aparece na página.

O <head> da página

missing_content_for_header

Layout sem {{ content_for_header }} · erro · código

O layout precisa de {{ content_for_header }} dentro do <head>: é por ele que a plataforma põe a descrição, o canônico, a prévia nas redes, os dados estruturados, a medição e o carrinho.

missing_content_for_layout

Layout sem {{ content_for_layout }} · erro · código

O layout precisa de {{ content_for_layout }} no <body>: é onde entra o conteúdo do template.

duplicate_head_tag

Tag do <head> que a plataforma já escreve · aviso · código

O tema escreve uma tag que o {{ content_for_header }} já põe na página: a descrição, o canônico, o robots, as de Open Graph (og:) e do X (twitter:) ou os dados estruturados de produto (JSON-LD). Repetidas, os buscadores e as redes escolhem uma das duas. Tire a do tema.

missing_title_tag

Layout sem <title> · aviso · código

O título da página é do tema (a plataforma não escreve o <title>). Ponha no <head> do layout, com page_title, ou com seo_title quando o lojista escreveu um.

missing_viewport_meta

Layout sem a meta viewport · aviso · código

Sem <meta name="viewport" content="width=device-width, initial-scale=1">, o celular desenha a página como num computador, encolhida.

missing_html_lang

<html> sem lang · aviso · código

O <html> do layout precisa do idioma (lang="pt-BR"): o leitor de tela escolhe a pronúncia por ele, e o navegador, a tradução.

missing_charset

Layout sem <meta charset> · aviso · código

Ponha <meta charset="utf-8"> no começo do <head>, para os acentos nunca saírem trocados.

Recursos da plataforma

unsupported_filter

Filtro de outra plataforma · erro · código

O filtro existe nos temas em Liquid de outras plataformas, mas não nesta. A mensagem diz o que usar no lugar. Junto com unsupported_tag e unsupported_object, é o relatório de migração de um tema que veio de fora.

unsupported_tag

Tag de outra plataforma · erro · código

A tag existe nos temas em Liquid de outras plataformas, mas não nesta. A mensagem diz o que usar no lugar.

unsupported_object

Objeto de outra plataforma · aviso · código

O objeto existe nos temas em Liquid de outras plataformas, mas não nesta. O trecho que depende dele nunca aparece; tire-o ou troque pelo recurso da plataforma que a mensagem indica.

platform_setting_wrong_type

Ajuste da plataforma com o tipo errado · aviso · código

O config/settings_schema.json usa o nome de um ajuste que a plataforma lê (logo, favicon, corFundo, corTexto, corDestaque, corTopo, corRodape, cantos, largura, fonteTitulos, fonteTexto) com outro tipo, ou o select sem as opções que ela conhece. O checkout, os e-mails e o ícone da aba ignoram o valor. Use o tipo do guia da agência (Convenções da plataforma), ou outro nome para o ajuste.

missing_platform_settings

Faltam ajustes da plataforma · aviso · código

O config/settings_schema.json não tem alguns dos ajustes que ligam o tema ao resto da plataforma (o logo, o ícone da aba, as cores, os cantos, a largura e as fontes). Sem eles, o checkout e as páginas abertas pelos e-mails ficam no visual padrão da plataforma, e não no da loja. A mensagem diz quais faltam; o guia da agência (Convenções da plataforma) diz o tipo de cada um.

missing_cookie_preferences_link

Sem o link "Preferências de cookies" · aviso · código

Nenhum elemento do tema tem o atributo data-denaryx-preferencias-de-cookies, e nenhum script dispara o evento denaryx:preferencias-de-cookies. Sem um dos dois, quem aceitou ou recusou os cookies não tem como mudar de ideia, como a LGPD pede. Ponha o link no rodapé (<button type="button" data-denaryx-preferencias-de-cookies>Preferências de cookies</button>), mostrado só quando Denaryx.customerPrivacy.shouldShowBanner() é verdadeiro.

missing_account_link

Sem o link "Entrar" da área do cliente · aviso · código

Nenhum arquivo do tema usa routes.account_login_url. Quando o lojista liga a área do cliente (Configurações › Conta do cliente), o comprador não acha onde entrar para ver os pedidos. Ponha no cabeçalho, só com {% if shop.customer_accounts_enabled %}, o link "Entrar" (routes.account_login_url, com ?voltar= e o request.path para voltar à página) ou, com o comprador na conta ({% if customer %}), "Olá, {{ customer.first_name | escape }}" levando a routes.account_url. O guia da agência (Área do cliente) tem o trecho.

hardcoded_route

Endereço da loja escrito à mão · aviso · código

Um href ou um action com um endereço da loja escrito à mão (href="/carrinho", action="/busca"). Use o objeto routes ({{ routes.cart_url }}, {{ routes.search_url }}): é por ele que o tema acompanha a loja quando um endereço muda (outro idioma, por exemplo). O endereço da página inicial (/) não acusa.

cart_without_components

O carrinho não mostra os complementos da linha · aviso · código

O tema tem o template do carrinho, mas nenhum arquivo lê line_item.item_components (ou components) nem line_item.prescription_status. Numa loja com montagens (a armação com a lente e os tratamentos, um kit), o comprador não vê no carrinho o que escolheu, nem a situação da receita. Mostre os complementos embaixo do nome da linha ({% for componente in item.item_components %}) e a situação da receita quando item.requires_prescription é verdadeiro; os temas da plataforma fazem isso no snippet kit-complementos-da-linha. O guia da agência (Item composto e propriedades) tem os objetos.

missing_try_on

Sem o provador virtual na página da armação · aviso · código

O tema é de ótica, mas nenhum arquivo chama o kit do provador virtual de óculos. O verificador reconhece a ótica pelo código: o tema já usa o provador (product.try_on, product.has_try_on, shop.try_on ou o link #provador) ou a receita oftalmológica (shop.prescriptions, os campos prescription[...], product.prescription_type ou o template prescription). Quando o lojista liga o provador (Configurações › Provador virtual), a página da armação não mostra o botão "Experimentar no rosto", e o link do cartão leva a uma página sem a janela. Chame {% render 'kit-provador', product: product %} no bloco de compra, fora do {% form 'product' %}: o snippet só desenha alguma coisa com o provador ligado e um arquivo na armação, e carrega o kit-provador.js. O guia da agência (Provador virtual) tem o passo a passo.

Segurança

secret_in_theme

Token da plataforma dentro do tema · erro · código

Um arquivo do tema tem um token da API Admin, um token pessoal do CLI ou um segredo de webhook. O código do tema chega ao navegador de qualquer visitante. Tire o token do arquivo e revogue-o no painel (Configurações › Integrações): ele já pode ter sido visto.

http_url

Recurso em http:// · aviso · código

Um script, um estilo, uma imagem, uma fonte, um vídeo ou um iframe vem de um endereço http://. A loja é servida em https://, e o navegador bloqueia o recurso sem criptografia (conteúdo misto): ele simplesmente não aparece. Use https://, ou envie o arquivo em assets/.

cookie_with_domain

Cookie gravado com Domain · aviso · código

O código grava um cookie com o atributo Domain (no document.cookie ou no cookieStore.set). No endereço da plataforma (<loja>.denaryx.store), todas as lojas dividem o mesmo domínio, e um cookie com Domain chegaria às outras lojas: a plataforma tira o atributo, e o cookie fica só no endereço da loja. Grave sem o Domain. Só no domínio próprio da loja o cookie vale para os subdomínios dele.

Desempenho

asset_too_large

Asset pesado · aviso · código

Um arquivo de assets/ passa do limite: JavaScript acima de 250 KB, CSS acima de 150 KB, imagem acima de 500 KB, fonte acima de 200 KB ou vídeo acima de 5 MB. Todo visitante baixa o arquivo, e no celular isso pesa no tempo até a página aparecer. Comprima a imagem (WebP ou AVIF), divida o JavaScript, tire o CSS que ninguém usa ou use WOFF2 só com os caracteres do português. O projeto ajusta os limites no denaryx.json (verificador.limites, em KB), para o CLI.

parser_blocking_script

Script que trava a página · aviso · código e páginas

Um <script src> sem defer, sem async e sem type="module", ou o filtro script_tag, que escreve um assim: o navegador para de ler a página até baixar e rodar o script, e a página demora a aparecer. Use <script src="{{ 'tema.js' | asset_url }}" defer></script>.

remote_asset

Script, estilo ou fonte de outro endereço · aviso · código

Um script, um estilo ou uma fonte vem de outro endereço (uma CDN pública, um serviço de fontes). Cada endereço novo custa uma conexão a mais antes de a página aparecer, e o visitante é visto por um terceiro antes de dar o consentimento, o que pesa na LGPD. Envie o arquivo em assets/ (a fonte de ajuste font_picker a plataforma já serve no próprio endereço da loja). Medição e anúncios entram pelas integrações do painel, que respeitam o consentimento.

img_without_dimensions

Imagem sem largura e altura · aviso · código

Um <img> sem width e height: o navegador não sabe o tamanho da imagem antes de baixá-la, e o texto pula quando ela chega. Ponha width e height (a proporção basta; o CSS ainda manda no tamanho), ou desenhe a imagem com o filtro image_tag, que já os escreve.

image_url_without_width

image_url sem largura · aviso · código

O filtro image_url sem width entrega a maior variante da imagem, mesmo para uma miniatura. Peça a largura em que a imagem aparece: {{ imagem | image_url: width: 600 }}. Seguido de image_tag, que monta o srcset com todas as larguras, não acusa.

large_paginate

Paginação com muitos itens · aviso · código

O {% paginate %} pede mais de 50 itens por página. Cada item é desenhado no servidor e baixado pelo visitante, e a página da lista demora. Use até 50 e deixe o resto para as páginas seguintes.

page_too_large

Página pesada · aviso · páginas

O HTML da página de exemplo passa de 500 KB, sem contar imagens, CSS e JavaScript. Costuma ser um laço que desenha itens demais, um SVG grande repetido ou JSON escrito na página. O projeto ajusta o limite no denaryx.json (verificador.limites.html).

Acessibilidade

img_without_alt

Imagem sem texto alternativo · aviso · código e páginas

Um <img> sem o atributo alt: o leitor de tela lê o nome do arquivo no lugar. Descreva a imagem (alt="{{ imagem.alt | escape }}"), ou use alt="" na imagem só decorativa, que o leitor de tela pula.

empty_link

Link sem nome · aviso · código

Um <a href> sem texto dentro, sem imagem com alt e sem aria-label: o leitor de tela diz só "link". Comum nos links de ícone (o carrinho, as redes sociais). Ponha um texto, mesmo escondido na tela, ou aria-label="Carrinho".

empty_button

Botão sem nome · aviso · código

Um <button> sem texto dentro, sem imagem com alt e sem aria-label: o leitor de tela diz só "botão". Comum nos botões de ícone (fechar, abrir o menu). Ponha um texto, mesmo escondido na tela, ou aria-label="Fechar".

input_without_label

Campo sem rótulo · aviso · código e páginas

Um <input>, <select> ou <textarea> sem <label> (em volta dele, ou com for igual ao id do campo), sem aria-label e sem aria-labelledby. O placeholder não serve de rótulo: some quando a pessoa digita, e nem todo leitor de tela o lê. No código, a regra só acusa quando não há dúvida (o id do campo vem do Liquid, por exemplo, e ela não acusa).

positive_tabindex

tabindex maior que zero · aviso · código

Um tabindex positivo tira o elemento da ordem da página: quem navega pelo teclado pula para ele antes de todo o resto. Use tabindex="0" (entra na ordem natural) ou tabindex="-1" (só pelo script), e ponha os elementos na ordem certa no HTML.

zoom_disabled

Zoom desligado no celular · aviso · código

A <meta name="viewport"> tem user-scalable=no ou maximum-scale abaixo de 2: quem enxerga mal não consegue ampliar a página no celular. Use só content="width=device-width, initial-scale=1".

outline_removed

Foco sem contorno · aviso · código

O CSS tira o contorno do foco (outline: none ou 0 num seletor com :focus) sem pôr outro destaque na mesma regra: quem navega pelo teclado não vê onde está. Tire o contorno só de quem usa o mouse, com :focus:not(:focus-visible), ou dê um destaque no :focus-visible.

default_contrast

Cores padrão com pouco contraste · aviso · código

Os valores padrão do tema (o current do config/settings_data.json, ou um dos presets) põem o texto ou a cor de destaque sobre o fundo com contraste abaixo de 4,5:1, o mínimo para leitura. O editor visual já recusa essas cores do lojista; o padrão do tema precisa passar também. Vale para as chaves corFundo, corTexto e corDestaque.

duplicate_id

id repetido na página · aviso · páginas

Dois elementos da página têm o mesmo id. O <label for>, o aria-labelledby e o script acham só o primeiro, e o segundo campo fica sem rótulo. Costuma ser uma seção usada duas vezes no mesmo template: junte o section.id ao id ("busca-{{ section.id }}").

heading_order

Títulos fora de ordem · aviso · páginas

A página pula um nível de título (um <h2> seguido de um <h4>, ou a página que começa no <h3>). O leitor de tela navega pelos títulos como por um índice, e o nível pulado parece uma parte que falta. Use o nível seguinte e mude o tamanho pelo CSS.