karibeo_backend_admin/docs/RESPONSIVE.md

Responsive Design Documentation

Overview

Karibeo está completamente optimizado para funcionar en dispositivos móviles, tablets y escritorio. Esta documentación detalla las estrategias de diseño responsivo implementadas.

Breakpoints

El proyecto utiliza breakpoints estándar de Tailwind CSS:

const BREAKPOINTS = {
  mobile: 768,    // < 768px
  tablet: 1024,   // 768px - 1023px
  desktop: 1280,  // 1024px - 1279px
  largeDesktop: 1280+ // >= 1280px
}

Hooks Personalizados

useResponsive

Hook para detectar el breakpoint actual:

import { useResponsive } from '@/hooks/useResponsive';

const { isMobile, isTablet, isDesktop, width } = useResponsive();

useOrientation

Hook para detectar orientación del dispositivo:

import { useOrientation } from '@/hooks/useResponsive';

const orientation = useOrientation(); // 'portrait' | 'landscape'

Frontend Responsive

Dashboard Layout

• Sidebar: Oculto en móvil, colapsable en desktop
• Top Navigation: Componentes adaptados según tamaño de pantalla
• Content Area: Padding responsive (3 en móvil, 6 en desktop)

// Ejemplo de uso
<div className="p-3 md:p-6">
  {/* Content adapts padding based on screen size */}
</div>

Grid Layouts

Todos los grids utilizan configuración responsive:

// ExploreSection
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6">
  {/* Cards automatically adjust */}
</div>

// PlacesSection
<div className="grid grid-cols-1 md:grid-cols-12 gap-0">
  {/* Stacks vertically on mobile, side-by-side on desktop */}
</div>

Typography

Tamaños de texto adaptados:

<h1 className="text-lg md:text-2xl font-bold">
  {/* Smaller on mobile, larger on desktop */}
</h1>

Images

Alturas responsive en tarjetas:

<div className="h-[350px] sm:h-[400px] lg:h-[458px]">
  {/* Image height scales with screen size */}
</div>

Backend Responsive

Middleware API

El archivo src/middleware/responsiveAPI.ts proporciona funciones para optimizar las respuestas del backend:

detectDevice

Detecta tipo de dispositivo desde User-Agent:

import { detectDevice } from '@/middleware/responsiveAPI';

const deviceType = detectDevice(userAgent, width);
// Returns: 'mobile' | 'tablet' | 'desktop'

optimizePayload

Optimiza payload para dispositivos móviles:

import { optimizePayload } from '@/middleware/responsiveAPI';

const optimized = optimizePayload(data, deviceType);
// Reduces image quality, limits array sizes for mobile

addDeviceHeaders

Añade headers de dispositivo a requests:

import { addDeviceHeaders } from '@/middleware/responsiveAPI';

const headers = addDeviceHeaders();
// Adds: X-Device-Type, X-Screen-Width, X-User-Agent

getAdaptivePagination

Paginación adaptativa según dispositivo:

import { getAdaptivePagination } from '@/middleware/responsiveAPI';

const { limit, offset } = getAdaptivePagination(deviceType);
// mobile: 10, tablet: 20, desktop: 50

Utilities

responsive.ts

Funciones útiles para comportamiento responsive:

import { 
  responsiveClass,
  getResponsiveValue,
  isTouchDevice,
  formatTextForMobile 
} from '@/utils/responsive';

// Clases responsive
const classes = responsiveClass('base', 'mobile-class', 'tablet-class', 'desktop-class');

// Valores responsive
const value = getResponsiveValue(10, 20, 50, width);

// Detectar touch
const isTouch = isTouchDevice();

// Formatear texto
const text = formatTextForMobile(longText, 100, isMobile);

Mejores Prácticas

1. Mobile-First

Siempre diseñar primero para móvil:

// ✅ Correcto
<div className="p-3 md:p-6">

// ❌ Incorrecto
<div className="p-6 md:p-3">

2. Ocultar Elementos

Usar clases de Tailwind para ocultar:

// Oculto en móvil
<div className="hidden md:block">

// Solo visible en móvil
<div className="block md:hidden">

3. Espaciado Responsive

Adaptar gaps, padding y margin:

<div className="gap-2 md:gap-4 lg:gap-6">
  {/* Spacing increases with screen size */}
</div>

4. Touch Targets

Asegurar áreas táctiles suficientes en móvil (mínimo 44x44px):

<button className="w-10 h-10 md:w-12 md:h-12">
  {/* Adequate touch area on mobile */}
</button>

5. Overflow Handling

Prevenir overflow horizontal:

<div className="overflow-x-auto">
  <div className="min-w-max">
    {/* Wide content scrolls horizontally */}
  </div>
</div>

Testing

Breakpoints de Prueba

Probar en estos anchos mínimos:

• Mobile: 320px, 375px, 414px
• Tablet: 768px, 834px
• Desktop: 1024px, 1280px, 1920px

Orientación

Probar tanto portrait como landscape en móvil/tablet.

Touch Events

Verificar que todos los elementos interactivos funcionen con touch.

Rendimiento

Lazy Loading

Implementar lazy loading para imágenes:

<img loading="lazy" src={image} alt={alt} />

Code Splitting

React.lazy para componentes pesados:

const HeavyComponent = lazy(() => import('./HeavyComponent'));

Responsive Images

Usar srcset para diferentes resoluciones:

<img 
  src="image-mobile.jpg"
  srcSet="image-mobile.jpg 375w, image-tablet.jpg 768w, image-desktop.jpg 1920w"
  sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
/>

Accesibilidad

Viewport Meta Tag

Ya incluido en index.html:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Focus States

Asegurar estados de focus visibles:

<button className="focus:ring-2 focus:ring-primary focus:outline-none">

ARIA Labels

Usar labels descriptivos para lectores de pantalla:

<button aria-label="Open menu">
  <Menu />
</button>

Mantenimiento

Auditorías Regulares

• Ejecutar Lighthouse para móvil y desktop
• Verificar responsive en DevTools
• Probar en dispositivos reales

Actualización de Breakpoints

Si se necesitan breakpoints custom, actualizar en:

1. tailwind.config.ts
2. src/hooks/useResponsive.tsx
3. Documentación

Recursos

• Tailwind Responsive Design
• MDN Media Queries
• Web.dev Responsive Images