# AGENTS.md ## Objetivo del proyecto Este proyecto realizará una migración visual incremental del frontend de `evangelizacion.org.mx`. El backend existente en `CodeIgniter 4`, sus rutas, controladores, modelos, consultas, integraciones y reglas de negocio deben conservarse como base de trabajo. El nuevo frontend se implementará con `TailwindCSS`, utilizando Figma como fuente visual principal. La meta no es reconstruir el sistema desde cero, sino reemplazar progresivamente las vistas y estilos actuales sin afectar el funcionamiento existente. ## Alcance actual La primera pantalla que se migrará es `Home`. Diseño de referencia: - [Página Web EVA V2 — Home](https://www.figma.com/design/qwoZ4QHdid015IcEFS3giu/P%C3%A1gina-Web-EVA-V2.?node-id=1-1300&t=3vR5rIzqxecOg5fh-0) El alcance de esta etapa comprende: - Maquetación de vistas con TailwindCSS. - Integración del nuevo markup con las vistas PHP existentes. - Creación de componentes y parciales reutilizables. - Adaptación responsive. - Comparación visual contra Figma. - Conservación de rutas, variables y comportamiento actuales. No incluye cambios amplios de backend, APIs, autenticación, consultas, correos, RSS o lógica de pagos, salvo que una tarea lo autorice explícitamente. ## Stack del proyecto - Framework: `CodeIgniter 4` - Runtime objetivo: `PHP 8.4+` - Estado actual del repo: la configuración declarada todavía puede reflejar una base anterior y deberá alinearse con el runtime objetivo durante la migración técnica - Vistas: `app/Views/**/*.php` - Controladores: `app/Controllers/*.php` - Rutas: `app/Config/Routes.php` - Layout actual: `app/Views/layout/template.php` - Vista actual de Home: `app/Views/home.php` - Controlador actual de Home: `app/Controllers/HomeController.php` - Estilos legacy: - `assets/css/index.css` - estilos inline dentro de vistas y parciales ## Principio principal Tratar el proyecto como una migración visual incremental. Antes de modificar una pantalla: 1. Identificar su ruta. 2. Identificar el controlador y método correspondiente. 3. Identificar la vista principal. 4. Identificar el layout y los parciales utilizados. 5. Identificar las variables PHP recibidas. 6. Identificar scripts, formularios e integraciones relacionadas. 7. Consultar el frame correspondiente en Figma. 8. Revisar el mapeo registrado en `docs/FIGMA_ROUTE_MAPPING.md`. No se debe asumir que una vista puede reemplazarse sin revisar previamente sus dependencias. ## Archivos que pueden modificarse Salvo que la tarea indique algo diferente, se permite modificar: - `app/Views/**` - parciales y componentes relacionados con la pantalla - archivos frontend dentro de `assets/**` o la ubicación definida para TailwindCSS - configuración de TailwindCSS - JavaScript exclusivamente visual relacionado con la pantalla - documentación dentro de `docs/**` ## Tracking e instrumentación Este proyecto deberá convivir con herramientas de medición y marketing como: - Google Tag Manager - Google Analytics 4 - Mautic - Meta Pixel - Hotjar - y otras herramientas que el negocio incorpore después Por lo tanto, el frontend nuevo no debe implementarse como si fuera solo una capa visual. ### Regla general Los elementos importantes para medición deben tener identificadores estables. No depender del texto visible para tracking, porque: - el copy puede cambiar - el diseño puede cambiar - el contenido puede venir desde base de datos ### Cuándo usar `id` Usar `id` cuando el elemento sea único y relevante para: - formularios - CTA principales - navegación principal - secciones clave de la página - elementos objetivo de tracking o scroll - asociaciones de accesibilidad cuando aplique ### Cuándo usar `data-*` Usar atributos `data-*` cuando se requiera una capa de instrumentación más flexible o semántica. Preferir: - `data-track` - `data-section` - `data-component` - `data-form` ### Convención de nombres Para `id`, usar formato: - `pagina-seccion-elemento` Ejemplos: - `home-hero` - `home-primary-cta` - `home-donativos-form` - `layout-main-nav` - `layout-footer-newsletter` Para `data-*`, nombrar por función de negocio y no por apariencia visual. Evitar nombres como: - `box-azul` - `boton-1` - `div-principal` Preferir nombres como: - `data-track="cta-donativos"` - `data-section="hero"` - `data-component="newsletter-form"` ### Reglas mínimas de tracking - Todo formulario importante debe tener `id` único. - Todo CTA principal debe tener `id` único. - Toda sección clave puede tener `id` único si ayuda a tracking, navegación o QA. - Componentes repetibles deben apoyarse más en `data-*` que en `id`. - El tracking no debe depender del contenido textual visible. ## Separación de lógica y responsabilidades El rediseño frontend no debe convertirse en excusa para seguir acumulando lógica en lugares incorrectos. ### Controladores y base de datos Si un controlador contiene lógica de acceso a base de datos, consultas, filtros persistentes o responsabilidad propia de capa de datos, esa lógica debe evaluarse para vivir en modelo, servicio o capa adecuada. Regla preferida: - acceso a datos -> modelo o servicio - coordinación del flujo HTTP -> controlador - render y presentación -> vista No dejar consultas o lógica de datos incrustada en controladores nuevos si puede abstraerse correctamente. Si una tarea frontend obliga a tocar un controlador y ahí se detecta lógica de base de datos impropia: - señalarlo en el resumen técnico - proponer moverlo a modelo o servicio - ejecutar el ajuste si es puntual, seguro y aporta claridad - pedir confirmación si el cambio crece más allá de una refactorización acotada ### Vistas y JavaScript Las vistas no deben acumular scripts innecesarios. Si un script no necesita estar inline por una razón estricta, debe moverse a `public/assets/js` o a la ubicación frontend definida por el proyecto. Mover fuera de la vista cuando el script: - sea reutilizable - tenga más que unas pocas líneas triviales - maneje interacción de componentes - registre eventos - controle formularios - implemente tracking - necesite mantenimiento o pruebas futuras Se tolera script inline solo cuando: - el contexto PHP lo vuelve estrictamente necesario - el fragmento es mínimo - moverlo fuera complicaría más de lo que ayuda Incluso en esos casos, mantener el inline lo más pequeño y claro posible. ## Archivos que no deben modificarse sin autorización No modificar por iniciativa propia: - `app/Config/Routes.php` - controladores - modelos - entidades - servicios - migraciones - seeders - consultas SQL - configuración de autenticación - integraciones de pago - integraciones de correo - variables de entorno - `composer.json` - dependencias de npm Si una modificación fuera indispensable, detenerse y explicar: - qué archivo necesita cambiar - por qué es necesario - qué riesgo presenta - qué alternativa existe para evitarlo ## Contratos de datos Las variables proporcionadas por controladores deben conservarse. Para Home se han identificado inicialmente: - `datosSEO` - `datosSlide` - `secciones` - `mostrarSlider` - `estamos_campana` - `porcentaje_campana` No eliminar, renombrar o cambiar estas variables sin confirmar primero dónde se utilizan. Se deben conservar: - condiciones PHP existentes - iteraciones - URLs dinámicas - slugs - identificadores - estados vacíos - formularios - tokens - atributos requeridos por JavaScript - eventos de analítica Si durante la migración a `PHP 8.4+` aparece una incompatibilidad real en backend, se permite proponer un ajuste técnico puntual, pero no rehacer backend sin justificación explícita. ## Estrategia de estilos TailwindCSS será la base para todo componente nuevo. Reglas: - No usar Bootstrap para componentes nuevos. - No eliminar CSS legacy o dependencias visuales de pantallas que todavía no hayan sido migradas, salvo que exista una sustitución comprobada. - Evitar agregar CSS inline. - Evitar duplicar estilos que puedan expresarse con TailwindCSS. - Utilizar las convenciones definidas en `docs/TAILWIND_CONVENTIONS.md`. - Reutilizar componentes cuando exista una repetición real. - No crear abstracciones prematuras para elementos utilizados una sola vez. - Limitar los valores arbitrarios de Tailwind a casos necesarios para igualar Figma. - No usar `!important` salvo que exista una justificación documentada. La migración debe permitir que las pantallas nuevas y legacy convivan temporalmente. ## Componentes y parciales Antes de crear un componente nuevo, revisar: - componentes existentes - parciales utilizados por otras pantallas - inventario de componentes documentado en `docs/FRONTEND_ARCHITECTURE.md` Crear un parcial o componente cuando: - aparezca en varias pantallas - tenga variantes claramente identificables - contenga estructura o comportamiento que deba mantenerse consistente - su extracción mejore la legibilidad de la vista principal No fragmentar una vista en archivos pequeños sin una ventaja clara de reutilización o mantenimiento. ## Figma Figma es la fuente visual principal para: - jerarquía - distribución - colores - tipografía - espaciado - tamaños - bordes - sombras - estados visuales - comportamiento responsive representado Figma no sustituye la revisión del sistema actual. Cuando Figma no muestre un estado dinámico, se debe revisar el comportamiento existente antes de proponer una solución. No inventar silenciosamente: - estados de error - estados vacíos - comportamientos móviles - interacciones - contenido - variantes de componentes Los supuestos deben declararse en el resumen de la tarea o merge request. ## Accesibilidad Toda pantalla nueva debe considerar: - HTML semántico - un encabezado principal coherente - orden lógico de encabezados - navegación mediante teclado - estados de foco visibles - labels asociados a formularios - texto alternativo en imágenes relevantes - contraste suficiente - botones y enlaces identificables - respeto por contenido extenso y tamaños de texto No sacrificar accesibilidad únicamente para reproducir una apariencia visual. ## Seguridad y PHP - Conservar los mecanismos actuales de escape de contenido. - No reemplazar salida escapada por contenido sin escapar. - No mostrar datos internos o sensibles en HTML. - No modificar tokens, campos ocultos o protecciones CSRF. - No mover lógica de negocio a las vistas. - Mantener las condiciones PHP necesarias para representar datos dinámicos. - No dejar lógica de acceso a base de datos en vistas. ## Proceso de implementación Para cada pantalla: 1. Leer `AGENTS.md`. 2. Consultar los documentos relacionados dentro de `docs/`. 3. Revisar ruta, controlador, vista y variables. 4. Revisar el frame exacto de Figma. 5. Identificar componentes reutilizables. 6. Implementar con TailwindCSS. 7. Integrar los datos PHP existentes. 8. Validar desktop, tablet y móvil. 9. Comparar visualmente contra Figma. 10. Probar los estados dinámicos disponibles. 11. Revisar errores de PHP, JavaScript y consola. 12. Documentar archivos modificados, supuestos y riesgos. ## Validaciones obligatorias Antes de declarar terminada una tarea: - la vista debe cargar sin errores PHP - no deben existir errores nuevos en la consola - las rutas y enlaces deben conservarse - los datos dinámicos deben seguir mostrándose - los formularios existentes deben conservar su comportamiento - la pantalla debe revisarse en desktop y móvil - debe realizarse QA visual contra Figma - no deben existir cambios de backend no autorizados - no deben agregarse dependencias sin autorización - si TailwindCSS ya está configurado en el proyecto, su flujo de build o compilación no debe romperse - debe incluirse un resumen de los archivos modificados Los comandos exactos de instalación, desarrollo, build y validación deben registrarse en `docs/FRONTEND_ARCHITECTURE.md` cuando la configuración real de TailwindCSS quede definida. ## Definition of Done Una pantalla se considera terminada cuando: - reproduce el diseño aprobado de Figma - conserva la funcionalidad y los datos existentes - funciona correctamente en desktop, tablet y móvil - utiliza las convenciones TailwindCSS del proyecto - reutiliza componentes donde corresponde - no introduce errores de PHP o JavaScript - conserva accesibilidad básica - cuenta con evidencia visual para revisión - está integrada correctamente en la rama correspondiente La revisión por otra persona puede formar parte del proceso del equipo, pero no debe asumirse como único criterio para cerrar trabajo técnico del agente. ## Documentación del proyecto - `docs/FRONTEND_ARCHITECTURE.md` - `docs/FIGMA_ROUTE_MAPPING.md` - `docs/SEO_STRATEGY.md` - `docs/TAILWIND_CONVENTIONS.md` - `docs/VISUAL_QA_CHECKLIST.md` `AGENTS.md` contiene las reglas generales del proyecto. Los detalles de cada pantalla, incluyendo ruta, controlador, vista, variables y frame de Figma, deben mantenerse en `docs/FIGMA_ROUTE_MAPPING.md`. El inventario inicial de componentes y decisiones estructurales de integración frontend deben mantenerse en `docs/FRONTEND_ARCHITECTURE.md`. ## Evolución de esta documentación La documentación comienza con Home, pero debe poder extenderse a las demás pantallas sin reescribir las reglas generales. Cuando se agregue una pantalla: - actualizar `docs/FIGMA_ROUTE_MAPPING.md` - registrar componentes nuevos o reutilizados - actualizar las convenciones solo cuando aparezca una regla general - evitar agregar excepciones específicas de una pantalla dentro de `AGENTS.md`