miketropi/nextora-site-composition

Composição do site Nextora

Possui a camada de composição de um tema de bloco proveniente do Nextora: templates/, parts/, patterns/ e as declarações theme.json que os descrevem. Os blocos internos são ../nextora-gutenberg-blocks/SKILL.md; os dados de aparência e predefinição são ../nextora-design-system/SKILL.md; a inicialização do tema filho e seus ativos são ../nextora-child-themes/SKILL.md.

Referências para carregar

• references/templates-and-patterns.md — a hierarquia de templates com os nomes de arquivo reais, regras de propriedade de partes e substituição, o cabeçalho de padrão e as convenções de categoria, a receita de padrão oculto mais template fino, composição de consulta e os auxiliares de sanitização, personalização via sistema de arquivos versus banco de dados, os defeitos observados e a receita de aceitação do WordPress downstream. Carregue-a antes da etapa 3.
• source-map.md — procedência para cada âncora nomeada ali.
• quality-gates.md — os portões que decidem se a composição está concluída.

Os arquivos locais têm precedência sobre qualquer valor citado nestas referências.

Fluxo de trabalho ordenado

1. Resolver as raízes do tema e ler as superfícies locais

O pai é o diretório de templates, o tema ativo é o diretório de folhas de estilo:

get_template_directory();      // raiz do pai
get_stylesheet_directory();    // raiz do tema ativo (filho quando um estiver ativo)

Leia, nesta ordem: theme.json (customTemplates, templateParts), templates/, parts/, patterns/, os nomes blocks/*/block.json do alvo, e inc/ para auxiliares de consulta ou template. A cópia de um template ou parte por parte do filho substitui o arquivo do pai de mesmo nome, então o que já existe decide a maior parte da resposta.

2. Encontrar o que já existe antes de compor qualquer coisa

Reutilizar vence inventar, nesta ordem:

1. Um padrão existente que já é a seção.
2. Um bloco existente (pai nextora/* ou o próprio filho) que já renderiza a seção.
3. Um novo padrão filho composto a partir de blocos existentes.
4. Um template fino que monta esses padrões.
5. Uma substituição de parte filha — apenas para uma superfície que o filho realmente possui.
6. Um novo bloco — apenas quando o comportamento solicitado ou a estrutura de edição não puder ser expressa por nenhum bloco existente.

Nunca envie posts simulados como conteúdo de produção, e nunca clone o backend do formulário de contato do pai: o pai já envia o bloco nextora/contact-form, e a página de contato do exemplo o compõe dentro de um grupo wrapper filho.

3. Colocar a composição no template correto

Aplique a hierarquia de references/templates-and-patterns.md:

• front-page.html rege a página inicial quando presente; home.html é o índice de posts, não um sinônimo para a página inicial; index.html é o fallback.
• Os templates de arquivo, post único, pesquisa e página específicos precedem o fallback do índice.
• Um nome declarado em theme.json customTemplates deve ter um templates/<nome>.html correspondente no tema que o declara.

Leia a listagem templates/ do próprio tema em vez de adivinhar nomes de arquivo: o pai envia front-page, home, index, archive, single, search, page, page-full-width, about-us, contact-us, frequently-asked-questions, theme-terms-conditions, theme-privacy-policy, 404; o filho de exemplo envia seu próprio conjunto, com nomes diferentes.

4. Decidir a propriedade da parte, então referenciar a parte

Uma referência wp:template-part resolve contra o diretório stylesheet primeiro, então um parts/header.html filho substitui o cabeçalho do pai onde quer que seja usado.

• Mantenha o cabeçalho/rodapé do pai se o filho não tiver motivo para possuí-los: não adicione uma parte copiada.
• Se o filho possui uma parte, dê a ela um corpo de propriedade do filho e diga isso na referência; não deixe um atributo theme que fixe a cópia do pai.
• O parts/header.html e parts/footer.html do filho de exemplo são uma referência de bloco cada (nextsaas/site-header, nextsaas/site-footer); a parte do cabeçalho do pai compõe nextora/scrolling-promotion e nextora/header.
• A sintaxe de referência nas fontes é {"slug":"header","tagName":"div"} no filho e {"slug":"header","tagName":"header","area":"header"} no pai. Corresponda à convenção do próprio alvo; nunca codifique um caminho de sistema de arquivos.

5. Criar padrões como arquivos PHP com um cabeçalho real

Os padrões residem em patterns/*.php. Seu registro vem do cabeçalho do arquivo, não de uma chamada register_block_pattern() — nenhum dos temas fonte a chama; ambos registram apenas categorias em PHP. Os campos de cabeçalho obrigatórios e as regras de slug estão em references/templates-and-patterns.md:

• Title, Slug: <slug-do-filho>/<slug-do-padrao> (único), Categories, e uma Description que diz quando usá-lo.
• O corpo do padrão é a marcação serializada do bloco que o editor insere, começando após o fechamento */ do comentário do cabeçalho.
• Ele deve ser analisável, usar apenas blocos registrados e permanecer editável após a inserção.

6. Dar a uma composição de página completa exatamente uma autoridade

Para uma nova composição de página completa, coloque a lista de seções em um padrão de sistema de arquivos oculto — Inserter: no no cabeçalho — e referencie-a a partir de um template fino:

<!-- wp:template-part {"slug":"header","tagName":"div"} /-->

<!-- wp:pattern {"slug":"nextfolio/page-landing"} /-->

<!-- wp:template-part {"slug":"footer","tagName":"div"} /-->

Não repita a lista de seções também no template. O exemplo atualmente contém a mesma lista duas vezes (patterns/page-home.php e templates/front-page.html), e os templates do pai incorporam marcação de padrão carregando metadata.patternName; essa duplicação é o que esta regra substitui para trabalhos novos. Ao meramente editar um bloco existente, mantenha a duplicação existente — atualize as outras cópias apenas se o conteúdo da seção realmente mudou.

7. Compor consultas com blocos principais e contexto explícito

• Arquivos, o índice de posts, pesquisa e detalhe do post delegam a wp:query com "inherit":true, então a consulta principal fornece o contexto; o index.html, home.html, archive.html e search.html do exemplo fazem isso.
• Construa o loop a partir de core/post-template mais blocos core/post-*, adicione wp:query-pagination e sempre forneça wp:query-no-results.
• Use wp:query-title, core/post-title, core/post-content, core/comments + core/comment-template + wp:comments-pagination + wp:post-comments-form para a superfície de post único, em vez de um loop clássico.
• Um bloco que inicia seu próprio loop passa atributos sanitizados: reutilize os auxiliares inc/blocks/query.php do filho onde eles existirem, caso contrário, limite os tamanhos de página e valide tipos de post, taxonomias e termos contra valores permitidos. SQL preparado não substitui essa validação.

8. Manter as declarações theme.json precisas

Declare entradas customTemplates e templateParts apenas para superfícies que o tema possui, e apenas para nomes que não são templates principais. Veja references/templates-and-patterns.md para a re-declaração observada no exemplo e a regra para novos trabalhos.

9. Levar em conta o Editor de Site

Templates e partes do sistema de arquivos podem ser mascarados por personalizações do banco de dados salvas no Editor de Site. Se uma edição de arquivo não alterar o front-end, procure por um template salvo ou estilo antes de tocar no arquivo. Nunca sobrescreva silenciosamente as personalizações de um site real; inspecione ou redefina apenas um ambiente descartável.

10. Verificar contra o site em execução

Resolva cada template e parte no front-end, confirme que os padrões inserem e permanecem editáveis, confirme a versão mínima do WordPress solicitada e a versão suportada atual, e execute a receita do navegador em references/templates-and-patterns.md. Marque qualquer coisa que você não testou como não verificado.

Verificações de conclusão

• Cada template e parte usados resolvem para o tema pretendido; nenhum atributo theme perdido fixa uma parte do pai a partir de um template filho.
• Nenhum novo bloco desnecessário, nenhum template de página PHP clássico, nenhum conteúdo simulado de produção.
• Nova composição de página completa: uma autoridade em um padrão oculto, referenciado a partir de um template fino; nenhuma lista de seção duplicada.
• Padrões analisáveis, usam blocos registrados, mantêm slugs únicos e suas categorias são aquelas que o tema registra em PHP.
• Loops de consulta usam contexto explícito, atributos sanitizados e um estado de nenhum resultado.
• theme.json declara apenas nomes de template próprios e não principais.
• quality-gates.md aplicado, incluindo sua seção de aceitação de composição.

Limites

Apenas instrução em Markdown: nenhum script de tempo de execução, geradores, árvores de tema copiadas ou instaladores, e nenhuma edição no pai ou no filho de exemplo. A biblioteca de padrões do pai e as composições do exemplo são evidências para ler, não arquivos para copiar.