roi-theme/_planeacion/theme_referencias/_old/brief.txt

# Brief para crear un **tema clásico** de WordPress: **apus-theme**

## Contexto

* Sitio actual en WordPress, se desarrollará un **tema nuevo** (no child) copiando como base la estructura de `twentytwentyfour` pero **renombrando** y **creando carpeta propia** para el tema final.
* **Repositorio y rutas locales de referencia:**

  * Base de referencia visual: [https://www.rsmeans.com/resources/rsmeans-data-outperforms-generic-estimates](https://www.rsmeans.com/resources/rsmeans-data-outperforms-generic-estimates)
  * Referencias internas: `D:\_Desarrollo\02AnalisisDePreciosUnitarios\analisisdepreciosunitarios.com\_planeacion\theme-references`
  * Origen de análisis (solo referencia): `D:\_Desarrollo\02AnalisisDePreciosUnitarios\analisisdepreciosunitarios.com\wp-content\themes\twentytwentyfour`
  * Tema final: `\wp-content\themes\apus-theme`

## Objetivo

Construir **apus-theme** como **tema clásico** (PHP templates, **sin** FSE/Gutenberg), **altamente optimizado para Core Web Vitals y SEO**, con **Bootstrap local** y un **panel de opciones independiente** en el admin.

## Compatibilidad

* WordPress: **última versión estable**
* PHP: **última versión estable**
* Bootstrap: **última versión estable** (copias locales)

## Stack y assets

* **Sin** Vite/Webpack; **sin** jQuery.
* Incluir localmente: `bootstrap.min.css` y `bootstrap.bundle.min.js`.
* Directorios:

  * CSS: `\wp-content\themes\apus-theme\assets\css\`
  * JS: `\wp-content\themes\apus-theme\assets\js\`
* **Tipografías**: sin llamadas externas; permitir **autohospedadas** y opción para usar familias del sistema; **configurable en panel**.
* **SVGs locales** para iconografía (no icon fonts).

## Arquitectura del tema

* Tema **clásico** (no FSE). Desactivar Gutenberg (el sitio usa plugin para editor clásico).
* `add_theme_support('title-tag')` **activado**.
* **Sin comentarios** en todo el sitio (front y admin).
* **Sin búsqueda nativa**:

  * Rutas de buscador (p. ej. `/search/` o consultas a la plantilla de búsqueda): **404**.
  * Si una URL válida recibe `?s=` u otros parámetros, **entregar la página normal** e **ignorar** el parámetro (no 404 ni redirección).
* **Bloat** de WP: desactivar (emoji, oEmbed, `wp-embed`, feeds, RSD, WLW manifest, `dashicons` para no logueados).
* **404**: la gestiona un plugin; el tema no impone plantilla 404.

## Plantillas prioritarias (orden de entrega)

1. `index.php`, `header.php`, `footer.php`, `sidebar.php`, `comments.php`, **paginación**
2. `home.php` / `front-page.php` (la portada será una página existente; el usuario final la definirá)
3. `single.php`
4. `page.php`
5. `search.php` (**bloqueada** para forzar 404 en rutas de buscador)
6. `404.php` (solo si no interfiere con el plugin; en principio no usada)
7. `author.php`
8. `date.php`
9. `attachment.php`
10. `archive.php` (NO prioritaria)
11. `category.php`, `tag.php` (NO prioritarias)
12. `taxonomy.php` (NO prioritaria)

> **Nota**: no habrá vistas de **index** ni **search** como listados de posts para navegación pública; mantener archivos básicos por jerarquía WP, pero la experiencia de usuario **no** dependerá de esas vistas.

## Header y navegación

* **Header sticky**.
* **Menú hamburguesa sin logo**.
* **Móvil**: la hamburguesa **despliega hacia abajo** y **carga el menú existente en WP**.
* **Escritorio**: seguir los patrones de los **ejemplos compartidos** (referencias RSMeans/`theme-references`).
* **Ubicaciones de menú**: registrar `primary` (header) y `footer` (pie).

## Home

* La **Home** será **una página** de WP ya creada; la define el usuario en Ajustes → Lectura (no fijar en código).

## Footer

* **4 áreas de widgets** con opción de **ancho configurable por widget**.

## Contenido y single

* **Imagen destacada**: **activada por defecto**; si no existe, **no mostrar nada** (no placeholder).
* **Sin breadcrumbs** por títulos largos; **optimizado para SEO**.
* **Badge de categoría** sobre H1: **activado por defecto**, con opción de **apagar** en el panel.
* **Tabla de contenidos (TOC)**: **activada** con opción on/off en panel (anclas desde H2/H3).
* **Relacionados por categoría en `single.php`**:

  * Ubicación: **al final del contenido**.
  * **Totalmente configurable** desde el panel: cantidad, columnas, tamaño de card, colores de fondo, layout (solo título / imagen+titulo), comportamiento si no hay imagen (solo título con fondo), **aleatorio** y **excluir post actual**.
  * **Sin valores fijos** preimpuestos (defínelos como opciones con defaults razonables).

## Estilos y componentes

* **Inspiración** en RSMeans (jerarquía, espaciados, énfasis), **no réplica** literal.
* Ancho máximo de contenido: **configurable** (opciones tipo `container`, `container-xl`, `container-xxl` o `container-fluid`).
* Idioma base: **es_MX**; fecha **d/m/Y**.

## Imágenes y medios

* **Responsive** con `srcset/sizes` y **lazy-loading nativo**.
* Preferir **WebP/AVIF** con fallback a JPEG/PNG (sin llamadas externas).
* Sin PWA ni cache de service worker; **solo favicon** y meta básicas.

## SEO

* **Rank Math** gestiona **metas, OG/Twitter Cards y schema.org** (no duplicar desde el tema).
* El tema **solo** declara `title-tag`.

## Rendimiento (Core Web Vitals)

* **Meta**: buscar **calificación perfecta** (no hay mínimos aceptables).
* **Sin** jQuery; JS nativo + `bootstrap.bundle.min.js`.
* **CSS crítico inline**: **desactivado por defecto**; dejar opción de **activarlo** con switch (sin romper estilos).
* **AdSense**: el **tema únicamente** implementará **retardo/guardado** para que **no** se cargue `adsbygoogle.js` ni auto-ads **hasta el primer scroll**; **no** gestionar contenedores de altura fija (eso quedará para un **plugin** aparte o desarrollo independiente). No mutar el layout al activarse.
* **Perfmatters** u otros plugins pueden usarse; el tema no los bloquea.

## Panel de opciones del tema

* **Página propia** en el admin (**no** Customizer): por ejemplo, menú “Apus Theme” con slug `apus-theme-options`.
* **Acceso**: **solo administradores**.
* **Vista previa en vivo** (postMessage) en un iframe sin recarga completa.
* Opciones mínimas:

  * **Ancho máximo** (contenedores Bootstrap).
  * **Tipografías** (familias/pesos autohospedados o sistema).
  * **Sticky header** (on/off).
  * **Badge de categoría** (on/off).
  * **Imagen destacada** (on/off global en single/page, sin placeholder).
  * **Desactivar búsqueda nativa** (forzar 404 en plantillas de buscador).
  * **Retardo de AdSense** hasta primer scroll (on/off).
  * **Lista de relacionados** (cantidad, columnas, layout, colores, aleatorio, excluir actual).
  * **Idioma/fecha** (confirmar es_MX y d/m/Y, editable si se requiere).

## Accesibilidad

* Seguir **reglas básicas**: contraste legible, foco visible, **skip to content**, navegación por teclado, objetivos táctiles ≥44px, roles/etiquetas ARIA donde aplique.

## Entregables

1. Tema **completo** en `\wp-content\themes\apus-theme` con archivos y rutas definidas.
2. **Panel de opciones** en admin con vista previa en vivo.
3. **Documentación breve**: cómo activar portada estática, opciones del tema, y notas de rendimiento/SEO.

## Criterios de aceptación

* Funciona en últimas versiones de **WP/PHP** sin errores.
* **Core Web Vitals**: orientado a puntaje perfecto (móvil/CrUX), sin dependencias externas de fonts/scripts (salvo AdSense bajo retardo).
* **Sin** comentarios, **sin** buscador nativo, **sin** jQuery.
* **Rank Math** gestiona SEO (sin duplicados).
* Menú hamburguesa sticky; móvil abre **hacia abajo** cargando menú WP; escritorio según referencias.
* Footer con **4** áreas de widgets y **ancho configurable por widget**.
* **Single** con TOC y **relacionados** configurables al final del contenido.

## Desglose en issues

* **Obligatorio**: descomponer en **múltiples issues atómicos** (uno por funcionalidad).
* Si una funcionalidad es amplia, dividir en **sub-issues** siguiendo la indicación general de este brief (p. ej., “Panel de opciones” → creación del menú, endpoint de previsualización, secciones de opciones, guardado, vista previa; “Header” → hamburguesa móvil, sticky, escritorio; “Rendimiento” → desactivar bloat, retardo AdSense, lazy media; etc.).

---

**INSTRUCCIÓN INICIAL (OBLIGATORIA):** Debes **crear el issue en GitHub** y **redactar** su contenido conforme al siguiente formato. Crea el issue directamente en el repositorio indicado.

Quiero que redactes un **issue de GitHub** completo y flexible con este formato:

1. **Título**: claro y accionable.
2. **Contexto**: qué se intentaba hacer y en qué entorno (repo, rama, versión, SO/navegador si aplica).
3. **Descripción del problema / solicitud**: explica el comportamiento actual o lo que se está pidiendo.
4. **Análisis y diagnóstico preliminar**:

   * causa probable,
   * áreas/módulos afectados,
   * si es reproducible,
   * issues o PR relacionados.
5. **Pasos para reproducir** (si aplica).
6. **Comportamiento esperado**.
7. **Impacto / prioridad**.
8. **Hito (Milestone/Iteración) – opcional**

   * **Nombre** (p. ej. `Sprint 2025-11` o `v1.3.0`).
   * **Objetivo** (qué pretende entregar este hito).
   * **Fecha objetivo** (AAAA-MM-DD).
   * **Alcance incluido / excluido** (breve lista).
   * **Dependencias** (otros issues/PRs).
     **Checklist del hito (si aplica)**
   * [ ] Proponer/seleccionar milestone
   * [ ] Alinear fecha objetivo con el equipo
   * [ ] Confirmar capacidad/alcance del hito
   * [ ] Revisar dependencias y riesgos
   * [ ] Criterios de salida del hito definidos
9. **Plan por fases** *(adaptar al caso; usa solo las fases necesarias)*.
   Para **cada fase**, incluye su **checklist propio**.

   * **Fase: *[nombre libre según el caso]***

     * [ ] …
     * [ ] …
   * **Fase: *[nombre libre según el caso]***

     * [ ] …
     * [ ] …
       *(Si el issue es sencillo, usa una sola fase con su checklist).*
10. **Etiquetas (labels)** según el caso: `bug`, `enhancement`, `question`, `analysis-needed`, `priority-high`.
11. **Asignación**: a qué rol/persona va.
12. **Estado**: abierto al crear.

**Recordatorio**: un issue en GitHub es un registro para **reportar bugs, pedir funciones, dejar tareas o comentar problemas**; debe tener **título, descripción, etiquetas, responsable y estado**. Es válido incluir **hito** y **plan por fases con checklists** específicos al caso.

**INSTRUCCIÓN FINAL (OBLIGATORIA):** **No debes tocar absolutamente nada del código.** Yo revisaré el issue; si hay correcciones, te las haré saber o te indicaré cómo proceder. **Limítate exclusivamente a redactar el texto y a crear el issue en GitHub.**

**Nota adicional:** Este trabajo es **grande**; **descompón** en varios **issues atómicos** (uno por cada funcionalidad). En algunos casos, para una misma funcionalidad, crea **varios issues** siguiendo la directriz anterior.