miketropi/nextora-site-composition

Composición del sitio Nextora

Posee la capa de composición de un tema de bloques con Nextora: templates/, parts/, patterns/ y las declaraciones theme.json que los describen. Los bloques internos están en ../nextora-gutenberg-blocks/SKILL.md; los datos de apariencia y preajustes están en ../nextora-design-system/SKILL.md; el arranque y los recursos del tema hijo están en ../nextora-child-themes/SKILL.md.

Referencias a cargar

• references/templates-and-patterns.md — la jerarquía de plantillas con los nombres de archivo reales, las reglas de propiedad de partes y anulación, las convenciones de encabezado y categoría de patrones, la receta de patrón oculto más plantilla delgada, la composición de consultas y los ayudantes de saneamiento, la personalización entre sistema de archivos y base de datos, los defectos observados y la receta de aceptación downstream de WordPress. Cárgala antes del paso 3.
• source-map.md — procedencia para cada ancla nombrada allí.
• quality-gates.md — los controles de calidad que deciden si la composición está terminada.

Los archivos locales tienen prioridad sobre cualquier valor citado en estas referencias.

Flujo de trabajo ordenado

1. Resolver las raíces del tema y leer las superficies locales

El padre es el directorio de plantillas; el tema activo es el directorio de hojas de estilo:

get_template_directory();      // raíz del padre
get_stylesheet_directory();    // raíz del tema activo (hijo cuando hay uno activo)

Leer, en este orden: theme.json (customTemplates, templateParts), templates/, parts/, patterns/, los nombres de blocks/*/block.json del destino, y inc/ para ayudantes de consulta o plantilla. Una copia de una plantilla o parte en el hijo anula el archivo del padre con el mismo nombre; por lo tanto, lo que ya existe decide la mayor parte de la respuesta.

2. Encontrar lo que ya existe antes de componer algo nuevo

La reutilización supera a la invención, en este orden:

1. Un patrón existente que ya es la sección.
2. Un bloque existente (del padre nextora/* o del hijo) que ya renderiza la sección.
3. Un nuevo patrón hijo compuesto a partir de bloques existentes.
4. Una plantilla delgada que ensambla esos patrones.
5. Una anulación de parte del hijo — solo para una superficie que el hijo posee genuinamente.
6. Un bloque nuevo — solo cuando el comportamiento solicitado o la estructura de edición no pueda expresarse con ningún bloque existente.

Nunca enviar publicaciones de prueba como contenido de producción, y nunca clonar el backend del formulario de contacto del padre: el padre ya incluye el bloque nextora/contact-form, y la página de contacto de la muestra lo compone dentro de un grupo contenedor hijo.

3. Colocar la composición en la plantilla correcta

Aplicar la jerarquía de references/templates-and-patterns.md:

• front-page.html gobierna la página de inicio cuando está presente; home.html es el índice de entradas, no un sinónimo de la página de inicio; index.html es la reserva.
• Las plantillas específicas de archivo, entrada individual, búsqueda y página preceden a la reserva de index.
• Un nombre declarado en theme.json customTemplates debe tener un templates/<nombre>.html correspondiente en el tema que lo declara.

Leer el listado de templates/ del propio tema en lugar de adivinar nombres de archivo: el padre incluye 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; el tema hijo de muestra incluye su propio conjunto, con nombres diferentes.

4. Decidir la propiedad de las partes, luego referenciar la parte

Una referencia wp:template-part resuelve primero contra el directorio de hoja de estilo, por lo que un parts/header.html del hijo reemplaza el encabezado del padre en todos los lugares donde se use.

• Mantener el encabezado/pie de página del padre si el hijo no tiene razón para poseerlos: no agregar una parte copiada.
• Si el hijo posee una parte, darle un cuerpo propiedad del hijo y decirlo en la referencia; no dejar un atributo theme que fije la copia del padre.
• El parts/header.html y parts/footer.html del tema hijo de muestra tienen una referencia de bloque cada uno (nextsaas/site-header, nextsaas/site-footer); la parte de encabezado del padre compone nextora/scrolling-promotion y nextora/header.
• La sintaxis de referencia en las fuentes es {"slug":"header","tagName":"div"} en el hijo y {"slug":"header","tagName":"header","area":"header"} en el padre. Coincidir con la convención del destino; nunca codificar una ruta del sistema de archivos.

5. Crear patrones como archivos PHP con un encabezado real

Los patrones viven en patterns/*.php. Su registro proviene del encabezado del archivo, no de una llamada a register_block_pattern() — ninguno de los temas fuente la llama; ambos registran solo categorías en PHP. Los campos de encabezado requeridos y las reglas de slug están en references/templates-and-patterns.md:

• Title, Slug: <slug-del-hijo>/<slug-del-patrón> (único), Categories, y una Description que indique cuándo usarlo.
• El cuerpo del patrón es el marcado de bloque serializado que inserta el editor, comenzando después del cierre */ del comentario de encabezado.
• Debe analizarse correctamente, utilizar solo bloques registrados y permanecer editable después de la inserción.

6. Dar a una composición de página completa exactamente una autoridad

Para una nueva composición de página completa, colocar la lista de secciones en un patrón oculto del sistema de archivos — Inserter: no en el encabezado — y referenciarlo desde una plantilla delgada:

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

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

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

No repetir la lista de secciones también en la plantilla. La muestra actualmente contiene la misma lista dos veces (patterns/page-home.php y templates/front-page.html), y las plantillas del padre incluyen marcado de patrón en línea con metadata.patternName; esa duplicación es lo que esta regla reemplaza para trabajo nuevo. Al simplemente editar un bloque existente, mantener la duplicación existente — actualizar las otras copias solo si el contenido de la sección realmente cambió.

7. Componer consultas con bloques centrales y contexto explícito

• Archivos, el índice de entradas, búsqueda y detalle de entrada delegan en wp:query con "inherit":true, por lo que la consulta principal proporciona el contexto; los index.html, home.html, archive.html y search.html de la muestra hacen esto.
• Construir el bucle a partir de core/post-template más bloques core/post-*, agregar wp:query-pagination, y siempre proporcionar wp:query-no-results.
• Usar wp:query-title, core/post-title, core/post-content, core/comments + core/comment-template + wp:comments-pagination + wp:post-comments-form para la superficie de entrada individual en lugar de un bucle clásico.
• Un bloque que inicia su propio bucle pasa atributos saneados: reutilizar los ayudantes de inc/blocks/query.php del hijo si existen; de lo contrario, limitar los tamaños de página y validar tipos de entrada, taxonomías y términos contra valores permitidos. SQL preparado no es un sustituto de esa validación.

8. Mantener las declaraciones theme.json precisas

Declarar entradas customTemplates y templateParts solo para superficies que el tema posee, y solo para nombres que no son plantillas centrales. Ver references/templates-and-patterns.md para la re-declaración observada en la muestra y la regla para trabajo nuevo.

9. Tener en cuenta el Editor del Sitio

Las plantillas y partes del sistema de archivos pueden ser enmascaradas por personalizaciones en la base de datos guardadas en el Editor del Sitio. Si una edición de archivo no cambia el front-end, buscar una plantilla o estilo guardado antes de tocar el archivo. Nunca sobrescribir silenciosamente las personalizaciones de un sitio real; inspeccionar o restablecer solo un entorno desechable.

10. Verificar contra el sitio en ejecución

Resolver cada plantilla y parte en el front-end, confirmar que los patrones se insertan y permanecen editables, confirmar la versión mínima de WordPress solicitada y la versión compatible actual, y ejecutar la receta del navegador en references/templates-and-patterns.md. Marcar cualquier cosa que no se haya ejercitado como no verificado.

Verificaciones de finalización

• Cada plantilla y parte utilizada resuelve al tema previsto; ningún atributo theme suelto fija una parte del padre desde una plantilla del hijo.
• Sin bloques nuevos innecesarios, sin plantillas de página PHP clásicas, sin contenido de producción ficticio.
• Nueva composición de página completa: una autoridad en un patrón oculto, referenciado desde una plantilla delgada; sin lista de secciones duplicada.
• Los patrones se analizan correctamente, usan bloques registrados, mantienen slugs únicos, y sus categorías son las que el tema registra en PHP.
• Los bucles de consulta usan contexto explícito, atributos saneados y un estado de sin resultados.
• theme.json declara solo nombres de plantilla no centrales y propiedad del tema.
• quality-gates.md aplicado, incluyendo su sección de aceptación de composición.

Límites

Solo instrucción en Markdown: sin scripts de ejecución, generadores, árboles de tema copiados o instaladores, y sin ediciones al padre o al tema hijo de muestra. La biblioteca de patrones del padre y las composiciones de la muestra son evidencia para leer, no archivos para bifurcar.