s0up4200/mobile-adapt

Mobile Adapt

Objetivo

Adaptar interfaces existentes para que funcionen bien en teléfonos sin eliminar funcionalidades principales. Priorizar la web móvil de clase iPhone a menos que el usuario nombre otro destino.

Destino predeterminado

Si el usuario no especifica un dispositivo o navegador, optimizar primero para:

• iPhone Pro Max en orientación vertical y horizontal
• iOS Safari
• Pantallas táctiles compactas de aproximadamente 375-440 CSS px de ancho
• Uso con teclado abierto, texto grande, áreas seguras y movimiento reducido

Cuándo investigar

Esta habilidad depende del comportamiento actual de la plataforma.

• Consultar fuentes oficiales cuando el usuario solicite la guía más reciente/actual, comportamiento específico de iPhone, peculiaridades de Safari/WebKit, comportamiento de safe-area, comportamiento de PWA/pantalla de inicio o citas directas.
• Preferir Apple Developer, WebKit, W3C/WCAG, MDN, Android Developers y web.dev.
• Usar fechas absolutas al citar cambios recientes de plataforma.

Para las reglas y fuentes actuales de alta señal, leer references/mobile-ui-2026.md.

Reglas principales

• Mantener los teléfonos compactos en un solo panel. No cambiar a la IA de escritorio solo porque un teléfono en horizontal cruza un breakpoint genérico. Un teléfono girado lateralmente sigue sosteniéndose con dos manos a la altura del brazo: el modelo mental del usuario es "teléfono", no "tableta". Dividir en un diseño de varios paneles crea una experiencia desorientadora donde nada es lo suficientemente grande para usarse cómodamente.

• Usar navegación móvil inferior (bottom navigation) solo para secciones verdaderamente de primer nivel. Mantenerlo en 3-5 destinos principales; mover el desbordamiento a Más, una hoja (sheet) o flujos secundarios. La parte inferior de la pantalla es la zona de descanso natural del pulgar: poner la navegación principal allí significa que las acciones más comunes requieren el menor esfuerzo. Más de 5 elementos reducen los objetivos táctiles por debajo del tamaño utilizable y abruman el escaneo.

• Cada objetivo interactivo debe tener al menos 44x44 CSS px en ambas dimensiones. Esto incluye elementos secundarios que son fáciles de pasar por alto: botones de acción en línea (editar, eliminar, ver), alternadores de expandir/contraer, chips de filtro, botones de icono en barras de herramientas, botones de cierre en hojas y filas de casillas de verificación/botones de radio (usar la <label> como el objetivo táctil completo, no solo la entrada). Las pantallas táctiles capacitivas registran el centro del área de contacto del dedo en aproximadamente 44pt: los objetivos más pequeños causan frustración por pulsaciones incorrectas, especialmente en movimiento. Clases comunes de Tailwind que no alcanzan: h-8 (32px), h-9 (36px), p-1 en un icono (~24px), p-1.5 (~28px), p-2 (~32px). Usar h-11 (44px), min-h-[44px] o equivalente como base para cada elemento táctil. Esto se alinea con Apple HIG y supera el mínimo de 24px de WCAG 2.2.

• No depender de hover, toques en iconos pequeños o acciones de fila ocultas. No hay estado hover en táctil: cualquier cosa que requiera hover para ser descubierta es invisible. Usar controles visibles, acciones de deslizamiento con una pista visual, o una hoja/menú contextual.

• Evitar el desplazamiento horizontal de página. El uso del teléfono con una sola mano implica desplazamiento vertical con el pulgar. El desplazamiento horizontal rompe el modelo espacial del usuario y oculta contenido fuera de la pantalla sin una indicación visible. Refluir, apilar, paginar o desplazar localmente tablas y gráficos en lugar de toda la página.

• Usar viewport-fit=cover, env(safe-area-inset-*) y min-height: 100dvh. Los iPhones modernos tienen esquinas redondeadas, el Dynamic Island y el indicador de inicio, todo lo cual reduce el viewport rectangular. Sin un manejo explícito de áreas seguras, el contenido se recorta detrás del hardware del teléfono. dvh tiene en cuenta la barra de herramientas de Safari que se colapsa, cosa que el antiguo vh no hace.

• Mantener las acciones principales alejadas de las barras del navegador, el indicador de inicio, las esquinas redondeadas y el teclado en pantalla. Un botón "Enviar" oculto detrás del teclado o superpuesto al indicador de inicio está funcionalmente roto: el usuario no puede verlo ni tocarlo sin activar un gesto del sistema.

• Preferir un contenedor de desplazamiento principal para flujos con muchos formularios o teclado. Las regiones de desplazamiento anidadas en iOS Safari crean atrapamiento de desplazamiento: el pulgar del usuario desplaza el contenedor interno cuando pretendía desplazar la página, o viceversa. WebKit ha tenido errores persistentes aquí (ver archivo de referencia). Usar desplazamiento anidado solo cuando no haya alternativa.

• Usar entradas móviles semánticas. Etiquetas encima de los campos (no al lado, no hay espacio horizontal), type, inputmode, autocomplete y enterkeyhint correctos. Estos atributos controlan qué teclado aparece: inputmode="decimal" muestra el teclado numérico para moneda, enterkeyhint="next" permite a los usuarios navegar por un formulario sin cerrar el teclado.

• Tratar el texto grande como una entrada de diseño real. Los usuarios de iOS pueden configurar texto más grande a nivel de sistema, y muchos lo hacen. Ajustar y refluir: no ocultar el significado clave detrás de truncamiento. Si una etiqueta truncada hace que el usuario adivine si está viendo "Cuenta de Ahorros" o "Cuenta de Salario", el diseño ha fallado.

• En teléfonos, los gráficos apoyan la historia; no son toda la historia. Una pantalla de teléfono puede mostrar quizás 5-6 barras legibles o un donut. Eso no es suficiente densidad de datos para que el gráfico sea autoexplicativo. Liderar con el número clave y un resumen de texto; usar el gráfico como refuerzo visual.

• Preservar la marca y el sistema de diseño existentes del producto a menos que el usuario solicite un rediseño más amplio. La adaptación móvil se trata de diseño e interacción, no de cambiar la apariencia.

Ejemplos

Antes de cambiar un shell de navegación, una tabla de datos o un formulario con un botón de envío, leer references/mobile-examples.md. Contiene código antes/después para una barra lateral que se convierte en una barra de pestañas inferior, una tabla que se convierte en una lista de tarjetas en teléfonos, y un formulario cuyo botón de envío permanece sobre el teclado.

Flujo de trabajo

1. Bloquear el contexto objetivo.
   • dispositivo, navegador, orientación, contexto de uso
   • por defecto, iPhone Pro Max + iOS Safari si no se especifica
2. Auditar primero el shell.
   • modo de navegación
   • áreas seguras
   • barras fijas/sticky
   • comportamiento en horizontal
   • comportamiento del teclado
3. Auditar cada pantalla o componente.
   • listas y filas
   • formularios
   • tablas
   • gráficos
   • estados vacío/error/carga
4. Elegir el corte duro.
   • qué se convierte en una sola columna
   • qué se convierte en tarjetas
   • qué se mueve a una hoja/drawer
   • qué se vuelve secundario bajo Más
5. Implementar adaptaciones mobile-first.
   • preferir container queries para componentes internos
   • preferir viewport queries para cambios de shell/layout
   • no mantener el comportamiento antiguo mitad-escritorio/mitad-móvil a menos que se requiera explícitamente
6. Verificar en vertical compacto y horizontal compacto.
   • Safari/WebKit primero
   • luego Chromium
7. Reportar primero los problemas de mayor riesgo, luego los cambios concretos y cualquier brecha restante.

Lista de verificación de pantalla

Shell y navegación

• Mantener los teléfonos en horizontal en el shell de teléfono.
• Evitar cambios bruscos md => barra lateral de escritorio para dispositivos que siguen siendo teléfonos.
• Acolchonar la UI inferior con env(safe-area-inset-bottom).
• Hacer que las acciones sticky se sitúen sobre la navegación inferior.
• Mantener las etiquetas móviles cortas.

Listas y filas

• Permitir que títulos, metadatos y cantidades se envuelvan en dos filas cuando sea necesario.
• Reservar espacio estable para precios, saldos y totales.
• Preferir metadatos apilados sobre metadatos en línea comprimidos.
• Exponer acciones con controles visibles o una hoja/menú, no hover.
• Dimensionar los botones de acción de fila (editar, eliminar, ver, expandir) al menos a 44x44 CSS px, no solo la navegación principal y los botones de barra de herramientas.

Formularios

• Usar una columna en teléfonos compactos.
• Mantener el botón de envío visible sobre el teclado.
• Usar un CTA principal claro y de ancho completo.
• Dividir flujos largos en pasos o divulgación progresiva.
• Evitar type="number" para moneda si el formato o la precisión importan.

Tablas y flujos de importación/revisión

• Convertir tablas editables densas en tarjetas/listas en teléfonos.
• Si debe permanecer una tabla real, aislar el desplazamiento horizontal solo a la tabla.
• Mantener encabezados fijos y barras de herramientas para que no oculten las entradas enfocadas.

Gráficos y estadísticas

• Liderar con el número clave y una narrativa breve.
• Añadir leyendas compactas y respaldo de texto.
• Preferir desplazamiento horizontal o comparaciones paginadas sobre barras densas ilegibles.
• Evitar pasteles/donuts pequeños en pantallas compactas.

Verificación

Para cada verificación a continuación, confirmar la condición de aprobación específica y usar las herramientas sugeridas. Las pruebas en dispositivos reales son el estándar de oro: los simuladores son útiles para iteraciones, pero no pueden reproducir completamente la sincronización del teclado, la inercia de desplazamiento o la precisión táctil.

• Vertical y horizontal — El teléfono permanece en el shell móvil en ambas orientaciones. Sin roturas de diseño, sin desbordamiento de contenido, sin cambio repentino a una barra lateral de escritorio o vista de varios paneles. Probar a 375px (clase iPhone SE/mini), 390px (iPhone Pro) y 430px (iPhone Pro Max) en vertical, y sus equivalentes en horizontal. Usar la barra de herramientas de dispositivos de Chrome DevTools o el simulador de Xcode.

• Áreas seguras de iOS Safari — El contenido no se recorta por el Dynamic Island, las esquinas redondeadas o el indicador de inicio. Los elementos fijos en la parte inferior tienen un relleno visible de env(safe-area-inset-bottom) (~34px en iPhones con Face ID). Verificar que viewport-fit=cover esté establecido en la etiqueta meta viewport; sin él, todos los valores de env(safe-area-inset-*) devuelven 0. Mejor probado en el simulador de Xcode (inserciones precisas por dispositivo) o Polypane 26+ (navegador de escritorio con presets reales de safe-area). Chrome DevTools 135+ admite Emulation.setSafeAreaInsetsOverride, pero requiere configuración manual.

• Flujo de formulario con teclado abierto — Enfocar cada entrada en secuencia y verificar: (1) el campo enfocado se desplaza a la vista, (2) la acción de envío es visible y táctil, (3) los encabezados fijos no ocultan el campo enfocado. Tener en cuenta que los elementos position: fixed; bottom: 0 se ocultan detrás del teclado de iOS (el Layout Viewport no se reduce), y position: sticky; bottom: 0 también falla al fijarse durante la visualización del teclado (error de WebKit #202120). Playwright y Cypress no pueden activar teclados en pantalla reales; esto requiere pruebas en dispositivos reales o el simulador de Xcode con Safari Web Inspector.

• Texto grande / zoom de pantalla — WCAG 1.4.4 (AA) requiere que el texto sea redimensionable al 200% sin pérdida de contenido. WCAG 1.4.10 (AA) requiere reflujo al 400% de zoom (equivalente a un viewport de 320px de ancho) sin desplazamiento horizontal. Probar: (1) ajustando el zoom del navegador al 200% y verificando que no haya truncamiento ni superposición, (2) ajustando el viewport a 1280px y haciendo zoom al 400% para simular el requisito de reflujo a 320px, (3) activando iOS > Configuración > Accesibilidad > Pantalla y tamaño de texto > Texto más grande al máximo. Verificar que la etiqueta meta viewport no establezca user-scalable=no o maximum-scale por debajo de 2.0.

• Movimiento reducido — Las animaciones respetan prefers-reduced-motion: reduce. Las transiciones aún comunican cambios de estado, pero utilizan fundidos o opacidad en lugar de movimiento. iOS Safari no suprime automáticamente las animaciones web cuando el Movimiento Reducido está activado: el desarrollador debe manejarlo. Probar a través de: la pestaña Rendering de Chrome DevTools > "Emulate prefers-reduced-motion", las anulaciones de preferencias de Safari Web Inspector (disponibles desde finales de 2022), o page.emulateMedia({ reducedMotion: 'reduce' }) de Playwright.

• Estados vacío/error/carga — Estos estados se renderizan correctamente en la pantalla compacta. Los esqueletos de carga coinciden con el diseño móvil, no con el de escritorio. Los mensajes de error son legibles sin necesidad de desplazarse.

• Modo autónomo/PWA (cuando sea relevante) — Si la aplicación admite display: standalone, verificar que el área de la barra de estado, el indicador de inicio y las regiones de gestos estén manejados. svh y dvh se resuelven al mismo valor en modo autónomo, ya que no hay barra de herramientas plegable (error de WebKit #261185). El error de WebKit #254868 puede causar valores de altura incorrectos. El error de WebKit #265578 provoca que la altura del viewport visual se actualice tarde cuando la UI de Safari vuelve a la vista mediante animación.

• Sin desplazamiento horizontal del documento — Deslizar hacia la izquierda/derecha en el cuerpo de la página no produce movimiento. Cualquier desplazamiento horizontal está aislado en un contenedor específico (tabla, carrusel) con un indicador de desbordamiento visible y overscroll-behavior: contain para evitar que se activen cambios en la UI de Safari (error de WebKit #240861). Para verificación automatizada en Playwright:

  const hasOverflow = await page.evaluate(() =>
    document.documentElement.scrollWidth > document.documentElement.clientWidth
  );
  expect(hasOverflow).toBe(false);
  

Entregable

Al usar esta habilidad, producir:

• un breve plan de adaptación móvil
• los problemas de mayor riesgo primero
• cambios concretos por pantalla
• verificación realizada
• cualquier incertidumbre restante sobre dispositivo/navegador