## Contexto

**Proyecto:** Análisis de Precios Unitarios (analisisdepreciosunitarios.com)
**Repositorio:** https://github.com/prime-leads-app/analisisdepreciosunitarios.com
**Tema WordPress:** apus-theme v1.0.0
**Template de Referencia:** `D:\_Desarrollo\02AnalisisDePreciosUnitarios\analisisdepreciosunitarios.com\_planeacion\theme-template\index.html`

El proyecto consiste en un sitio WordPress especializado en Análisis de Precios Unitarios (APUs) para la industria de construcción mexicana. Se ha desarrollado un tema personalizado "apus-theme" que debe replicar al 100% el diseño visual del template de referencia RDash proporcionado por el cliente.

**Ambiente de Desarrollo:**
- **Local:** D:\_Desarrollo\02AnalisisDePreciosUnitarios\analisisdepreciosunitarios.com
- **WordPress:** Última versión
- **PHP:** 7.4+
- **Bootstrap:** 5.3.8 (local, no CDN)
- **Sistema de Fuentes:** System fonts (optimizado para performance)

**Estado Actual:**
- 29 issues completados (#1-#40, excluyendo algunos cerrados)
- Funcionalidades core implementadas: 88%
- Coincidencia visual con template: 70%
- 9 componentes requieren ajustes visuales para match 100%

---

## Descripción del Problema

El tema WordPress "apus-theme" actualmente **NO se ve 100% idéntico** al template de referencia ubicado en `D:\_Desarrollo\02AnalisisDePreciosUnitarios\analisisdepreciosunitarios.com\_planeacion\theme-template\index.html`, a pesar de tener la mayoría de los componentes implementados funcionalmente.

**Síntomas Específicos:**
- Componentes funcionales pero sin estilos visuales exactos (colores, sombras, animaciones)
- Efectos hover diferentes o ausentes
- Gradientes y transiciones no coinciden con template
- Micro-interacciones (underlines animados, pulse effects) faltantes
- Espaciados y border-radius inconsistentes

**Impacto:**
- El sitio no cumple con el diseño aprobado por el cliente
- Inconsistencia visual vs especificaciones del template RDash
- Experiencia de usuario por debajo del estándar esperado
- Identidad visual de marca no alineada con diseño original

---

## Análisis y Diagnóstico Preliminar

**Causa Principal:**
Los componentes fueron implementados con funcionalidad correcta, pero los estilos CSS y animaciones JavaScript no replican exactamente las especificaciones visuales del template RDash. Existen diferencias en:
- Paleta de colores exacta (#0E2337, #61c7cd, #FF6B35, etc.)
- Efectos CSS avanzados (pseudo-elementos ::after, keyframe animations)
- Valores específicos (border-radius 16px vs 8px, box-shadow profundidades)
- Transiciones y timing functions (cubic-bezier vs ease)

**Áreas Afectadas:**
1. **TOC (Tabla de Contenidos)** - Implementado pero no sticky con scrollspy
2. **Navbar** - Sin underline animado turquesa en hover
3. **Top Notification Bar** - Colores no verificados contra RDash
4. **Header** - Falta botón CTA "Let's Talk" con gradiente naranja
5. **Related Posts** - Background blanco en lugar de gris, sin borde lateral
6. **Paginación** - Estilos básicos, sin gradientes ni animaciones avanzadas
7. **Modal Contacto** - Border-radius y sombras no coinciden
8. **CTA Box Sidebar** - Sin animación pulse
9. **Hero Section** - Padding no verificado

**Reproducible:** Sí, 100% reproducible en todos los ambientes (local, staging si existe)

**Issues Relacionados:**
- #1-#40 (issues previos completados o en progreso)

---

## Pasos para Reproducir

1. **Abrir sitio actual:**
   - Local: http://localhost/analisisdepreciosunitarios.com
   - Navegar a cualquier single post

2. **Abrir template de referencia:**
   - Abrir en navegador: `D:\_Desarrollo\02AnalisisDePreciosUnitarios\analisisdepreciosunitarios.com\_planeacion\theme-template\index.html`

3. **Comparar visualmente:**
   - Navbar: Verificar color de fondo (#0E2337), hover effects turquesa
   - TOC: Verificar sticky behavior y scrollspy activo
   - Hero Section: Verificar gradiente azul (#1e3a5f → #2c5282)
   - Related Posts: Verificar background gris (#f7fafc), borde lateral en hover
   - Paginación: Verificar gradientes, transforms, sombras
   - Hover effects: Verificar animaciones en todos los links/botones

4. **Verificar colores exactos:**
   - Usar eyedropper extension
   - Comparar códigos hex contra paleta RDash en documentación

---

## Comportamiento Esperado

El tema WordPress debe verse **100% idéntico** al template index.html de referencia en todos los aspectos visuales:

### Layout y Estructura
- ✅ Grid y contenedores exactos (ya implementado)
- ✅ Jerarquía de elementos correcta (ya implementado)
- ⚠️ Espaciados específicos (verificar padding/margin exactos)

### Colores Exactos
- **Navbar:** Background #0E2337, hover links #61c7cd
- **Hero Section:** Gradiente #1e3a5f → #2c5282
- **Botón "Let's Talk":** Gradiente #FF6B35 → #FF8C42
- **CTA Box Sidebar:** Gradiente #FF8600 → #FFB800
- **Related Posts Cards:** Background #f7fafc, border #e2e8f0
- **Top Notification Bar:** Background #4C5C6B, links #61c7cd

### Animaciones y Efectos Hover
- Navbar links: Underline animado con ::after, color #61c7cd
- Related Posts cards: translateY(-8px) en hover, borde lateral gradiente
- Paginación: Transform + shadow en hover, gradiente en current
- CTA Box: Animación pulse sutil (3s infinite)
- Botones: Transform translateY(-2px) + shadow en hover

---

## Impacto / Prioridad

**Prioridad:** 🔴 **ALTA** - El tema no cumple con el diseño aprobado por el cliente

**Impacto en Negocio:**
- **Experiencia de Usuario:** Diferencias visuales afectan percepción de profesionalismo
- **Conversión:** Falta de botón CTA "Let's Talk" visible reduce oportunidades de contacto
- **Branding:** Colores no alineados con identidad visual RDash
- **SEO/UX:** TOC sin scrollspy dificulta navegación de contenido largo

---

## Hito (Milestone)

**Nombre:** v1.2.0 - Implementación Visual Completa
**Objetivo:** Replicar 100% el diseño visual del template de referencia RDash
**Fecha objetivo:** 2025-11-22

**Alcance incluido:**
- Todos los componentes visuales del template RDash
- Colores exactos según paleta RDash
- Animaciones y efectos hover completos
- Micro-interacciones (underlines, pulses, transforms)
- TOC sticky con scrollspy funcional
- Botón CTA "Let's Talk" en navbar
- Refinamiento de componentes existentes

**Alcance excluido:**
- Funcionalidades backend (ya implementadas en issues previos)
- Plugins externos (no son parte del tema)
- Contenido del sitio (solo estructura visual)
- Nuevas funcionalidades no presentes en template

**Checklist del hito:**
- [x] Proponer milestone v1.2.0
- [x] Definir fecha objetivo (2025-11-22)
- [x] Confirmar capacidad y recursos
- [x] Revisar dependencias (ninguna)
- [x] Definir criterios de salida

---

## Issues Atómicos Creados

A continuación se listan todos los issues atómicos que se crearán para este milestone:

### Sprint 1: Issues Críticos

- **Issue #41:** Implementar TOC Sticky con ScrollSpy - 🔴 CRÍTICA - 1 día
- **Issue #42:** Agregar Underline Animado Turquesa en Navbar Links - 🔴 CRÍTICA - 0.5 días
- **Issue #43:** Verificar y Corregir Colores Exactos Notification Bar - 🔴 CRÍTICA - 0.25 días

### Sprint 2: Issues Altos

- **Issue #44:** Agregar Botón CTA "Let's Talk" con Gradiente Naranja - 🔶 ALTA - 0.5 días
- **Issue #45:** Actualizar Diseño Related Posts con Background Gris - 🔶 ALTA - 0.5 días

### Sprint 3: Issues Medios

- **Issue #46:** Mejorar Estilos de Paginación con Gradientes y Animaciones - 🟡 MEDIA - 0.5 días
- **Issue #47:** Refinar Modal de Contacto con Border-Radius y Sombras - 🟡 MEDIA - 0.25 días

### Sprint 4: Issues Bajos (Opcionales)

- **Issue #48:** Agregar Animación Pulse Sutil al CTA Box Sidebar - 🟢 BAJA - 0.25 días
- **Issue #49:** Ajustar Padding Hero Section para Match Exacto - 🟢 BAJA - 0.1 días

**Tiempo total estimado:** 3.85 días trabajo efectivo (~18 días calendario incluyendo testing y QA)

---

## Etiquetas

`enhancement`, `design`, `priority-high`, `milestone-v1.2.0`, `visual-implementation`

---

## Estado

**Status:** 🟡 Abierto - En planificación

**Próximos Pasos:**
1. Crear los 9 issues atómicos en GitHub (#41-#49)
2. Asignar desarrollador frontend
3. Setup milestone v1.2.0 en GitHub
4. Crear branch `gap-implementation`
5. Inicio de Sprint 1 (issues críticos)

---

**Fecha de Creación:** 2025-11-04