# Estándar Store Ecommerce Este documento define el lenguaje visual base para `novasis-ecommerce-store`. Aplica a home, catálogo, ficha de producto, carrito, checkout, seguimiento y pantallas públicas del ecommerce. ## Principio General La tienda debe sentirse moderna, viva y comercial, sin parecer un panel administrativo ni una plantilla genérica. - La UI debe vender: cada control debe comunicar intención y acción. - La personalización del tenant se aplica con variables CSS, no con estilos hardcodeados por cliente. - Las acciones principales deben ser visibles, táctiles y con feedback inmediato. - La experiencia debe funcionar igual de bien en mobile, tablet y desktop. ## Home Principal La organización base de la home debe funcionar como una portada comercial tipo marketplace. Estructura recomendada: - Top bar comercial para temporada, promoción o beneficio activo. - Header con identidad, buscador global y acciones de cuenta/carrito. - Navegación principal con categorías, productos, temporada, mayoristas y seguimiento. - El item `Categorías` del header debe resolver la navegación principal mediante mega menú en desktop. - Bloque principal a ancho completo con hero principal. - En tablet/mobile, la home debe apilarse sin sidebar ni columnas redundantes. Reglas: - No duplicar una sidebar de categorías en la home si ya existe mega menú en header. - Las promos superiores y columnas de navegación rápida pertenecen al mega menú, no al primer bloque de la home. - El hero debe mantener imagen real o generada relevante, texto sobre imagen y CTA con iconos. - Este layout debe ser parametrizable en `layout_config`, por ejemplo: `marketplace`, `hero_first`, `catalog_first`. - No mostrar banners vacíos ni bloques sin contenido activo. ### Hero Comercial - La variante por defecto es `immersive`: fotografía real a sangre, overlay legible y contenido superpuesto. - El hero debe ser la señal dominante del primer viewport; promociones secundarias se muestran debajo, no en una columna que reduzca su ancho. - Altura objetivo: 500px en desktop y 430px en mobile. - El título debe ser breve, tener contraste suficiente y no competir con la imagen. - El CTA principal usa cápsula con icono o texto de acción explícito. - El carrusel puede mostrar progreso, flechas y transición parametrizable. ## Ficha De Producto La ficha debe estar organizada como una página de compra completa, no como una ampliación del card. Estructura recomendada: - Breadcrumb superior: inicio, categoría y producto. - Galería con miniaturas verticales en desktop y horizontales en mobile. - Imagen principal grande con borde limpio y sin recortes agresivos. - Panel derecho con marca, SKU, nombre, rating, disponibilidad, precio y datos comerciales. - Bloque de opciones disponibles: color, variantes, presentación o atributos configurables. - Selector de cantidad compacto junto a las acciones. - Botones con iconos: agregar al carrito, favoritos y comparar. - Bloque inferior con productos relacionados compactos en lateral. - Panel de contenido con tabs visuales: descripción, reseñas, especificaciones y tags. - Sección final de upsell o productos recomendados. Reglas: - Al agregar al carrito debe mostrarse una alerta tipo toast con imagen del producto, cantidad, nombre y acción para abrir carrito. - La alerta no debe bloquear la navegación ni abrir el drawer automáticamente. - La disponibilidad debe mostrarse como `En stock`, sin exponer cantidad exacta salvo configuración explícita. - Las especificaciones deben poder venir de JSON del producto. - Las reseñas deben mostrarse dentro de la ficha y estar preparadas para integración futura. - En mobile, galería, compra, relacionados y tabs deben apilarse sin solapamientos. ## Tokens Base Todo componente visual debe consumir estos tokens: - `--store-primary` - `--store-secondary` - `--store-accent` - `--store-background` - `--store-surface` - `--store-text` - `--store-muted` - `--store-success` - `--store-danger` No se deben introducir paletas cerradas por componente. Los colores de intención pueden usar variantes derivadas con `color-mix`. ## Botones ### Botón Primario Uso: - Comprar - Agregar al carrito - Continuar al checkout - Publicar una acción comercial importante Reglas: - Forma tipo cápsula o circular. - Gradiente basado en `primary`, `secondary` o `accent`. - Icono obligatorio. - Sombra visible pero suave. - Hover con elevación y brillo. - Active con ligera compresión. - Focus visible. Ejemplo visual esperado: - Fondo con gradiente. - Texto blanco. - Icono antes o después del texto. - `border-radius: 999px`. ### Botón Secundario Uso: - Ver categoría - Armar pedido - Acciones alternativas del hero - Filtros destacados Reglas: - Fondo glass claro. - Borde suave derivado de `primary`. - Icono recomendado. - Hover con fondo blanco, elevación y borde más visible. ### Botones de Icono Uso: - Ver detalle - Favoritos - Comparar - Abrir carrito - Cuenta - Cerrar drawer - Navegación de carrusel Reglas: - Iconos `Rounded` o `Filled` cuando existan. - Evitar iconos outline genéricos para acciones comerciales principales. - Forma circular. - Tamaño mínimo táctil: 38px. - Cada intención puede tener color propio: - carrito: `accent` o `primary`; - ver detalle: teal/primary derivado; - favoritos: rojo/rose; - comparar: violeta; - checkout seguro: primary + icono de seguridad. - Usar `Tooltip` o `title` en acciones sin texto. ## Product Cards Los cards de producto son el componente comercial más importante. Reglas: - Todos los cards deben mantener el mismo tamaño dentro de la grilla. - La imagen debe tener proporción configurable. - El contenido debe limitar nombres largos a dos líneas. - Precio y badges deben tener jerarquía clara. - El stock visible debe mostrarse como estado comercial: `En stock`, `Sin stock` o `Bajo stock`. - No mostrar cantidades exactas de stock en cards, salvo configuración explícita del tenant. - Las acciones deben ir en una barra visual compacta, no como botones sueltos. - Click en el card o la imagen debe abrir la ficha completa del producto. - El icono de ojo debe abrir una vista rápida en dialog, no navegar. - Hover del card: - elevar; - reforzar sombra; - escalar imagen suavemente. El tenant puede elegir `lift`, `zoom`, `glow` o `none`. El efecto nunca debe cambiar las dimensiones del card ni desplazar la grilla. Barra de acciones: - Cápsula glass. - Carrito como acción principal. - Ver detalle, favoritos y comparar como acciones secundarias. - Iconos con microinteracción y color por intención. ## Ficha De Producto La ficha de producto debe permitir evaluar y comprar sin volver al catálogo. Reglas: - Accesible desde click en card o imagen. - Mostrar galería con miniaturas. - Mostrar imagen principal amplia. - Mostrar marca, SKU, categoría, rating, precio, stock comercial, descripción y especificaciones. - Debe permitir seleccionar cantidad antes de agregar al carrito. - Debe mostrar productos relacionados, preferentemente por categoría, marca o historial de compra. - Debe mostrar comentarios/reseñas cuando existan. - La descripción principal y las secciones extendidas deben venir desde un JSON estructurado. - Botón principal: agregar al carrito. - Acción secundaria: favorito. - Debe tener volver al catálogo. - Debe ser responsive sin solapar galería, texto ni acciones. Estructura recomendada: - `description`: resumen comercial corto. - `detailsJson.mainDescription`: descripción principal larga. - `detailsJson.sections[]`: bloques renderizables. - `detailsJson.sections[].type`: `text | specs`. - `detailsJson.sections[].rows[]`: tabla de especificaciones cuando `type = specs`. - `reviews[]`: reseñas visibles del producto. ## Vista Rápida La vista rápida se abre desde el icono de ojo del card. Reglas: - Renderizar en `Dialog`. - Mostrar resumen del producto, imagen, precio, estado de stock y especificaciones cortas. - Permitir agregar al carrito. - Permitir ir a ficha completa. - No debe reemplazar la ficha completa. ## Catálogo El modo por defecto del catálogo debe ser comercial, no una grilla infinita. Reglas: - Mostrar productos agrupados por categoría. - Cada categoría debe mostrarse como carrusel horizontal. - Cada sección de categoría debe tener cabecera con cinta/etiqueta del nombre y línea horizontal extendida. - La cabecera puede incluir filtros visuales simples como oferta, nuevo, rating o precio, más acción `Ver todo`. - El cuerpo de una categoría puede usar layout showcase: lateral con imagen/lista caliente, flyer promocional y productos en grilla. - Si la categoría tiene flyer/promo activo, mostrar 4 productos; si no tiene promo, mostrar 6 productos. - No dejar columnas vacías cuando no exista promo configurada para la categoría. - En layout showcase, las acciones del producto deben ir en un rail vertical al costado del card. - El máximo por defecto es 10 productos por categoría. - `maxProductsPerCategory` debe ser parametrizable por tenant. - El tenant puede cambiar el modo a `allWithPagination`. - En modo `allWithPagination`, mostrar todos los productos en grilla con paginación. - `pageSize` debe ser parametrizable por tenant. - Cuando existe búsqueda global activa, se prioriza la grilla de resultados filtrados con paginación. - Si el usuario selecciona una categoría, el modo por categorías puede mostrar sólo esa sección. - Los carruseles deben mantener cards de ancho estable y scroll horizontal en mobile. - La cinta de categoría debe usar `primary` o una variante parametrizable; no colores fijos por categoría salvo configuración. ## Header El header debe funcionar como punto de navegación y confianza. Reglas: - Top bar para temporada, promoción o confianza. - La top bar debe separar visualmente contacto, campaña activa y pago seguro cuando esos datos existan. - Logo visible y personalizable. - Buscador central cuando el layout lo permita, con acción explícita de búsqueda y foco visible. - Acciones con botones de icono modernos. - Delivery, cuenta, favoritos y carrito deben ser reconocibles por icono. - Header sticky con blur suave. - Al hacer scroll, el header puede compactar logo, buscador, navegación y acciones sin ocultar funcionalidades ni producir saltos de layout. - La acción comercial principal del header, normalmente carrito o checkout, debe tener mayor contraste que las acciones secundarias. - No mostrar botones sin comportamiento implementado. - El item `Categorías` puede abrir un mega menú en hover/focus en desktop. - El mega menú debe mostrar promos visuales superiores y columnas con categorías/productos existentes. - En mobile, el mega menú no debe desplegarse dentro del header; debe resolverse con navegación compacta y scroll horizontal sin barra visible. No usar botones rectangulares planos en header. ## Movimiento Y Transiciones La animación debe reforzar jerarquía y feedback, no decorar cada elemento por separado. - Presets disponibles: `dynamic`, `subtle` y `none`. - Velocidades: `fast`, `normal` y `relaxed`, convertidas a variables CSS compartidas. - Hover de botones y cards: 140–280ms según el preset. - Cambio de hero y entradas al viewport: usar `--store-motion-slow`. - Las secciones pueden revelarse al entrar al viewport una sola vez. - Siempre respetar `prefers-reduced-motion: reduce`. - Ninguna animación puede bloquear clicks, provocar saltos de layout o mantener la interfaz desenfocada. ## Configuración Visual Los controles visuales se guardan en `layout_config.layout` y deben contar con fallback: - `heroVariant`: `immersive | split`. - `motionPreset`: `none | subtle | dynamic`. - `transitionSpeed`: `fast | normal | relaxed`. - `sectionBackgroundMode`: `plain | alternating`. - `cardHoverEffect`: `none | lift | zoom | glow`. - `headerVariant`: `compact | standard`. - `stickyHeader`: boolean. - `showScrollAnimations`: boolean. - `showCarouselProgress`: boolean. - `bannerHoverEffect`: efecto seleccionado para imágenes promocionales. La tienda debe seguir funcionando con configuraciones antiguas que no tengan estas propiedades. ## Navegación Reglas: - Usar pills/cápsulas. - Estados hover con gradiente. - Scroll horizontal en mobile. - El texto debe ser corto. - No usar enlaces planos sin affordance visual en navegación principal. ## Categorías Destacadas Reglas: - Carrusel horizontal. - Cards compactas. - Imagen real o generada, nunca bloques vacíos. - Título dentro de una cápsula glass. - Hover con escala de imagen y elevación. ## Filtros Reglas: - No mostrar filtros como panel fijo inicial del catálogo. - El lateral del catálogo debe ser comercial por defecto. - Mostrar filtros cuando existe una búsqueda global activa. - El título en contexto de búsqueda debe ser `Refinar búsqueda`. - Chips redondeados. - Estado activo con gradiente. - Estado inactivo glass. - Hover con elevación mínima. - Los filtros deben ser compactos para no competir con el catálogo. - Un filtro oculto no debe seguir afectando resultados si el usuario sale del contexto donde se configuró. ## Novedades Y Anuncios La sección lateral del catálogo debe mostrar novedades cuando el usuario aún no hizo una búsqueda global. Uso: - Productos nuevos. - Anuncios comerciales. - Campañas por fecha. - Combos. - Temporadas. - Mensajes B2B o mayoristas. Reglas: - La fuente futura será un CRUD del panel Ecommerce. - El contenido debe ser parametrizable por tenant. - Cada novedad puede tener imagen, título, descripción corta, tag, CTA, prioridad y vínculo. - Los vínculos permitidos son producto, categoría, marca, oferta o búsqueda predefinida. - Debe soportar fecha desde/hasta, estado y segmentación B2C/B2B. - Las cards deben ser compactas para no competir con el catálogo. - Cada card debe tener microinteracción y color lateral por tipo. - No usar esta sección para filtros permanentes. ## Promoción De Ingreso Una oferta o campaña puede destacarse mediante un diálogo al cargar la tienda, siempre bajo control del tenant. Reglas: - Debe activarse explícitamente desde el panel Ecommerce; nunca se habilita automáticamente para tiendas existentes. - Debe usar imagen, etiqueta, título, descripción y CTA configurables desde `promotions`. - Debe permitir vigencia opcional con fecha desde/hasta. - Frecuencias permitidas: una vez por sesión, una vez por día o en cada carga. - La identidad de la campaña debe derivarse de su contenido y tenant; al publicar una campaña nueva puede mostrarse nuevamente sin limpiar storage manualmente. - No debe abrirse sobre enlaces profundos de producto, carrito o checkout. - Debe aparecer después del loader inicial, nunca antes de que la tienda sea reconocible. - Debe ofrecer cierre visible, cierre con `Escape`, cierre por backdrop y una acción primaria `Comprar ahora`. - El CTA debe llevar a la categoría configurada y cerrar cualquier vista incompatible. - En mobile debe apilar imagen y contenido sin exceder el viewport ni ocultar el botón de cierre. - Debe respetar `prefers-reduced-motion` y las variables de color/movimiento del tenant. ## Catálogo Acotado - `catalog.maxCategoriesOnHome` define cuántas secciones de categorías aparecen en la portada. - El valor por defecto es `6`; el panel permite configurarlo entre `1` y `20`. - El límite afecta únicamente la portada en modo catálogo por categorías. No elimina categorías ni altera búsquedas, filtros, mega menú o catálogo paginado. - Cada sección continúa respetando `catalog.maxProductsPerCategory`. ## Acciones Flotantes - `StoreFloatingActions` concentra utilidades globales para evitar repetir listeners y estilos. - “Volver arriba” aparece después de un desplazamiento significativo y usa scroll suave, salvo cuando el sistema solicita movimiento reducido. - WhatsApp se muestra solamente cuando el tenant tiene un número configurado en `footer.contact.whatsapp`. - El acceso flotante se oculta cuando el footer entra al viewport, porque allí ya existe el canal directo y así no cubre métodos de pago o enlaces legales. - El enlace normaliza el número, abre una pestaña segura y precarga un mensaje contextual con el nombre de la tienda. - En móvil se muestra únicamente el icono de WhatsApp para no cubrir productos, checkout ni navegación. ## Carrito Reglas: - Drawer lateral. - Botón de cierre circular con hover diferenciado. - Control de cantidad tipo cápsula. - Botón de checkout primario con icono de seguridad y avance. - El checkout no debe parecer un formulario administrativo. ## Checkout El checkout debe sentirse como una compra guiada, no como una carga interna del ERP. Reglas: - Debe ser parametrizable por tenant desde `checkout`. - Si no existe sesión, antes del checkout debe aparecer una pantalla de acceso con iniciar sesión, crear cuenta y compra invitada si está habilitada. - El registro/login no debe vivir mezclado con los campos del checkout. - Debe permitir compra invitada B2C cuando `allowGuestB2C` esté activo. - Debe organizarse en paneles: datos personales, dirección, facturación, método de entrega, método de pago, carrito y comentarios. - El carrito dentro del checkout debe verse como tabla/resumen operativo, con imagen, producto, cantidad, unitario y total. - El proveedor de pago visible debe salir de `paymentProviderLabel`. - El pago obligatorio debe usar un botón primario con icono de seguridad. - Entrega y retiro deben poder activarse o desactivarse con `allowDelivery` y `allowPickup`. - El costo de delivery debe salir de `deliveryCost`. - La aceptación de términos debe depender de `requireTermsAcceptance`. - No mostrar cupones ni vouchers en el MVP. - Después del pago aprobado debe mostrarse confirmación clara, código de pedido y acceso a seguimiento. - Los textos legales deben venir de páginas configurables del footer/contenido, no hardcodeados por desarrollador. ## Footer El footer debe cerrar la experiencia pública con confianza, contacto y navegación operativa. Reglas: - Debe ser parametrizable por tenant. - Abrir con un bloque de marca que combine logo, slogan y descripción corta, sin convertirlo en una tarjeta flotante. - Mostrar una franja de confianza con pago protegido, modalidad de entrega disponible y canal de atención; sus valores deben derivarse de `checkout` y `footer.contact`. - Mostrar datos de contacto: dirección, email, teléfono, WhatsApp y horario. - Incluir grupos de enlaces: comprar, soporte y legal. - Los enlaces de soporte/legal deben apuntar a páginas de contenido configurables, no a texto hardcodeado. - Incluir métodos de pago y señal de confianza de Novasis Pay. - Incluir redes sociales configurables. - Usar acciones directas con iconos para WhatsApp, email o teléfono cuando esos datos estén configurados. - Incluir una acción accesible para volver al inicio de la página. - Mantener una jerarquía de cuatro niveles: apertura de marca, confianza, navegación/contacto y cierre legal. - Las transiciones deben limitarse a elevación breve, énfasis de color y foco visible; no deben mover el layout. - Debe aparecer tanto en catálogo como en ficha de producto. - En mobile debe apilar confianza y acciones, conservar dos columnas de enlaces cuando haya espacio y llevar contacto a todo el ancho, sin solapamientos. Contenido editable: - `footer.description`, `footer.contact` y `footer.labels` deben editarse desde el panel; ningún texto comercial visible del footer debe depender de cambios de código. - `footer.linkGroups[]` admite alta, edición, eliminación y visibilidad por grupo y enlace. Cada enlace puede dirigir a una página interna o a una URL/ancla. - `footer.paymentMethods[]` y `footer.socialLinks[]` deben aceptar altas y bajas; las redes también admiten visibilidad individual. - El WhatsApp mostrado y el usado por header/widget/footer provienen de `footer.contact.whatsapp`; los enlaces deben normalizar el número antes de construir `wa.me`. - `contentPages[]` debe ser administrable desde el panel Ecommerce. - Cada página debe tener `key`, `title`, `subtitle` y bloques de contenido. - Ejemplos: contacto, términos y condiciones, privacidad, preguntas frecuentes, cambios/devoluciones, facturación y seguimiento. - El desarrollador no debe modificar código para personalizaciones de textos legales, soporte o contacto. ## Animación Permitido: - Elevación `translateY(-2px)` a `translateY(-6px)`. - Escala leve `1.03` a `1.06`. - Transiciones entre 160ms y 220ms. - Glow sutil en acciones primarias. No permitido: - Animaciones largas que bloqueen la compra. - Rebotes exagerados. - Cambios de layout en hover. - Texto que aparezca y mueva el card. ## Accesibilidad Obligatorio: - `aria-label` en botones de icono. - `title` o `Tooltip` en acciones sin texto. - `focus-visible` claro. - Tamaño táctil mínimo 38px. - Contraste suficiente entre fondo e icono/texto. - No depender solo del color para comunicar estado crítico. ## Temporadas Las temporadas pueden modificar: - Promociones. - Hero. - Top bar. - Decoración. - Variantes de color derivadas. Reglas: - Las cuatro estaciones deben existir como configuración disponible: verano, otoño, invierno y primavera. - Cada temporada puede activarse o desactivarse. - La decoración nunca debe tapar botones, precios ni productos. - Las partículas o efectos deben desactivarse con `prefers-reduced-motion`. ## Reglas de Implementación - No crear un estilo nuevo por pantalla si existe un patrón equivalente. - Usar componentes MUI existentes antes de introducir una librería nueva. - Preferir iconos de `@mui/icons-material` en variante rounded/filled. - Los estilos comerciales deben vivir en componentes reutilizables o styled components claros. - La configuración visual debe seguir siendo parametrizable por tenant. - No hardcodear identidad de cliente fuera del mock/config por defecto. ## Estándar De Código Nomenclatura: - Usar `store` para rutas, carpetas y componentes públicos de la tienda. - No crear nuevos archivos, rutas o imports con nombres heredados de plantilla. - La ruta pública oficial debe vivir en `src/app/(public)/store/page.tsx`. - La ruta raíz `src/app/page.tsx` puede importar la tienda solo como acceso directo temporal o landing pública. Organización: - `src/app/**/page.tsx` debe ser delgado: solo importa y renderiza el componente principal. - `src/components/store/StorePage.tsx` debe orquestar estado global y componer secciones. - `src/components/store/config/defaultStoreConfig.ts` contiene la configuración fallback del tenant demo. - `src/components/store/sections/novedades` contiene anuncios, campañas y productos nuevos. - `src/components/store/sections/catalogo` contiene categorías, grillas, carruseles, cards, filtros y acciones. - `src/components/store/sections/producto` contiene ficha, vista rápida, galería, especificaciones, reviews y relacionados. - `src/components/store/sections/checkout` contiene carrito, login previo, entrega, pago y resumen. - `src/components/store/sections/footer` contiene contacto, legal, soporte, redes y páginas parametrizables. - Cada carpeta de sección puede tener su propio `styles.ts`; no concentrar estilos nuevos en `StorePage`. Reglas: - Cada sección debe recibir datos por props desde configuración o API. - No consultar APIs ni mutar configuración dentro de un card visual. - No duplicar estilos de botones/cards; extraer un componente común cuando el patrón se repite. - No duplicar feedback de carrito: usar `CartAddedSnackbar` para catálogo, búsqueda, ficha y vista rápida. - No redeclarar tipos de carrito: usar `CartItem` y `CartNotice` desde `checkout/cartTypes.ts`. - No mezclar panel ERP con tienda pública dentro de la misma carpeta de componentes. - `StorePage` debe mantenerse como orquestador; si crece por encima de 2.000 líneas, la tarea incluye extraer una sección. - Cada nueva sección debe actualizar este estándar si introduce un patrón reutilizable. ## Checklist Para Nuevos Componentes - ¿Usa tokens `--store-*`? - ¿Tiene hover, active y focus visible? - ¿Tiene icono si es acción? - ¿Funciona en mobile? - ¿El texto cabe sin solaparse? - ¿Respeta el tamaño táctil mínimo? - ¿No rompe la grilla ni cambia layout al pasar el mouse? - ¿Se ve comercial y no administrativo?