Web Responsive: mobile-first, cualquier stack, verificado
El objetivo es un diseño que funcione en cada ancho, no en cinco anchos de dispositivos elegidos al azar.
Los errores viven en medio: 412px, 905px, el píxel exacto donde max-width: 767px y min-width: 769px dejan de aplicarse.
Por eso esta habilidad tiene dos mitades que siempre van juntas:
- Construir mobile-first: escribe el diseño para que se adapte por sí solo y necesite pocos puntos de ruptura.
- Demostrarlo: ejecuta
scripts/check_responsive.py, que renderiza la página y mide el diseño en cada ancho. "Se ve bien" con una o dos capturas de pantalla no cuenta como prueba. Hecho significa que el verificador reporta 0 errores.
El verificador solo ve la página renderizada (cajas del DOM y estilos computados), por lo que no le importa cómo se escribió el CSS. Eso es lo que lo hace funcionar con cualquier tecnología.
0. Lee el proyecto primero
Antes de escribir CSS, dedica un minuto a descubrir:
- Cómo se escriben los estilos aquí: Tailwind (
tailwind.config.*o@themeen CSS), variables Bootstrap/SCSS, módulos CSS, styled-components/emotion, estilos con ámbito de Vue/Svelte, archivos CSS planos. Escribe código nuevo en el mismo sistema con los mismos tokens. Un segundo sistema de estilos es un error de mantenimiento. - Los puntos de ruptura existentes, y reutilízalos. No inventes otros nuevos a menos que el contenido lo necesite.
- Cómo ver la página: un archivo
.htmlestático, o un servidor de desarrollo (npm run dev,php artisan serve,python manage.py runserver,rails s,dotnet watch...). Necesitas una URL o ruta de archivo para el verificador.
references/stacks.md muestra la sintaxis mobile-first y la ubicación de los puntos de ruptura para stacks comunes.
1. Construir mobile-first
Escribe los estilos base para la pantalla más pequeña, sin ninguna media query. Añade diseño a medida que el espacio crece, usando consultas min-width. Los teléfonos obtienen el CSS más simple, el contenido se apila de forma natural y cada punto de ruptura solo añade cosas. La forma desktop-first (escribir para escritorio y luego parchear con max-width) deja huecos entre los parches, y esos huecos son donde aparecen la mayoría de los errores responsivos.
Si el código base ya es desktop-first, no lo reescribas. Escribe tus partes nuevas o modificadas con mobile-first dentro de sus convenciones, y corrige lo que encuentre el verificador.
Prefiere diseños que se adapten sin puntos de ruptura
- Cuadrículas:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)). Las columnas aparecen según el espacio disponible, sin punto de ruptura y sin desbordamiento a 320px (la partemin(100%, …)es lo que lo evita). - Filas que deben ajustarse:
display: flex; flex-wrap: wrap; gap: …con unflex-basisrazonable. - Tamaños:
width: 100%; max-width: 40remen lugar dewidth: 640px. Tipo y espaciado fluidos conclamp(min, preferred, max). - Un componente que aparece en espacios de diferentes anchos (barra lateral vs. columna principal): usa container queries (
container-type: inline-size+@container), para que responda a su contenedor, no a la ventana. - Añade un punto de ruptura donde el contenido se rompe (reduce la ventana hasta que algo se vea mal), no en un ancho de dispositivo.
Rompedores de diseño conocidos. Revisa cada uno al escribirlo.
| Rompedor | Por qué rompe | Usa en su lugar |
|---|---|---|
width/min-width fijo en px en contenedores | más ancho que un teléfono de 320px | max-width + width:100%, %, fr, minmax() |
| hijo de flex/grid con contenido largo | los hijos tienen por defecto min-width: auto y se niegan a encogerse | min-width: 0 en el hijo (o minmax(0,1fr)) |
| palabras, URLs, correos, códigos largos | sin oportunidad de división | overflow-wrap: anywhere en contenedores de texto |
white-space: nowrap en botones/etiquetas/nav | el texto no puede ajustarse, empuja el ancho | permitir ajuste, o puntos suspensivos con min-width:0 + un title |
| imágenes, vídeos, iframes, embebidos | ancho intrínseco > pantalla | max-width:100%; height:auto; aspect-ratio para embebidos |
| tablas | las columnas no pueden encogerse por debajo del contenido | envolver en contenedor overflow-x:auto, o apilar filas en pantallas pequeñas |
bloques pre/code | espacios en blanco preservados | overflow-x:auto en el bloque |
100vw | incluye la barra de desplazamiento, por lo que es ~15px más ancho en escritorio | 100% (o 100dvw solo para sangrado completo con cuidado) |
height fijo en cajas con texto | el texto se ajusta a más líneas en teléfonos y se desborda/recorta | min-height, o ninguna altura |
| posicionamiento absoluto del contenido | no ocupa espacio; colisiona en otros anchos | flujo normal/cuadrícula; absoluto solo para decoración |
height: 100vh en héroes | las barras del navegador móvil y las pantallas horizontales cortas lo recortan | min-height: 100svh (con 100vh como fallback antes) |
Nunca ocultes el síntoma
- No uses
overflow-x: hiddenenhtml/bodypara detener el desplazamiento lateral. Oculta el error mientras el contenido sigue recortado (y rompeposition: sticky). Encuentra el elemento que es demasiado ancho. El verificador reporta este enmascaramiento comoclipped-offscreen. - No uses
user-scalable=nonimaximum-scale=1. Bloquear el zoom es un fallo de accesibilidad (WCAG 1.4.4). - No uses comprobaciones de ancho con JavaScript ni detección de agente de usuario para el diseño. Las media queries y container queries de CSS lo hacen sin parpadeo. JavaScript está bien para el comportamiento (
matchMedia), no para el diseño. - No modifiques la prueba para que pase (elevar
--min, añadir ignorados para que los errores desaparezcan).
Táctil, entrada, viewport
<meta name="viewport" content="width=device-width, initial-scale=1">en cada cabecera de página.- Objetivos táctiles de al menos 24x24px (WCAG 2.2 AA). Apunta a 44x44px para botones y controles de iconos en pantallas táctiles, y mantén espacio entre vecinos.
- La interfaz solo por hover (menús, tooltips que revelan contenido) necesita
@media (hover: hover)y una alternativa táctil. - Campos de formulario
font-size: 16pxo más en teléfonos, de lo contrario Safari iOS hace zoom al enfocar. Usatype,inputmodeyautocompleteadecuados. - Los teléfonos horizontales cortos (320–430px de alto) son reales. Los encabezados fijos más los banners de cookies no deberían cubrir más de un tercio de la pantalla. Colapsa o reduce su tamaño en alturas pequeñas (
@media (max-height: 500px)). - Dispositivos con muesca: usa padding
env(safe-area-inset-*)solo junto conviewport-fit=cover.
Tipografía, medios, navegación, contenido
rempara texto,clamp()para encabezados, longitud de línea limitada (max-width: 65chaproximadamente),line-heightsin unidad.- Imágenes:
srcset/sizespara fotos, atributoswidth/heightoaspect-ratiopara evitar cambio de diseño,object-fit: covercuando la relación de aspecto de la caja difiere de la de la imagen (de lo contrario se estira). - Navegación: en pantallas pequeñas usa un
<button>real conaria-expanded/aria-controlsque abra el menú. Muestra enlaces en línea desde el ancho donde realmente caben. - Mantén la paridad de contenido: no elimines contenido en móvil porque era difícil de encajar. Reordena, condensa o colapsa.
references/patterns.md tiene CSS listo para copiar para cada uno de estos (cuadrícula, nav, tabla, formulario, héroe, tarjetas, medios).
2. Verificar: ejecutar el verificador
Configuración única (Python 3.9+):
pip install playwright
python -m playwright install chromium
Ejecútalo contra la página renderizada. Inicia el servidor de desarrollo primero si lo hay.
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # archivo estático
- Varias páginas: pasa varias URLs. Verifica cada página o ruta que hayas modificado, más una que use el diseño compartido (encabezado/pie de página).
- SPA que renderiza tarde:
--wait-for "#app main". Páginas con inicio de sesión:--storage-state state.json. - Bucle interno mientras corriges:
--quick(~5–10 s). Ejecuta una ejecución completa antes de decir que has terminado (~20–40 s por página). - Código de salida: 0 = sin errores, 1 = errores encontrados (o advertencias con
--strict), 2 = no se pudo ejecutar.
Qué hace: recorre 320→1920px en pasos de 10px más los anchos de dispositivos comunes más ambos lados de cada punto de ruptura encontrado en el CSS de la página. Recarga los anchos clave con emulación móvil real (táctil, meta viewport) y verifica cuatro teléfonos horizontales cortos. En cada ancho mide:
| Error (debe corregirse) | Significado |
|---|---|
horizontal-overflow | la página se desplaza lateralmente; nombra el elemento que sobresale y qué lo fuerza a ser ancho |
clipped-offscreen | contenido recortado en el borde de la pantalla (a menudo oculto por overflow-x:hidden en body) |
occluded-target | un enlace/botón está cubierto por otro elemento (o por una barra fija en cada posición de desplazamiento) |
small-target | objetivo táctil de menos de 24px y apiñado por vecinos |
text-spill / text-clipped | el texto se sale de su caja / está recortado por un tamaño fijo + overflow:hidden |
text-overlap | texto de dos bloques no relacionados dibujado uno encima del otro |
distorted-media | imagen/video estirado (relación de caja ≠ relación natural, sin object-fit) |
viewport-meta, layout-viewport | meta viewport faltante o que bloquea el zoom; el teléfono renderiza con ancho de escritorio |
Advertencias (corrígelas o explica por qué no): touch-target (controles <44px en anchos táctiles), small-text (<12px en teléfonos), input-zoom (inputs <16px), fixed-coverage (barras fijas/sticky >35% de una pantalla corta).
El informe (report.md, report.json) agrupa los hallazgos así:
1. **horizontal-overflow** en 320-610px; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- peor: 296 px más allá del borde derecho a 320px
- pistas: se mantiene exactamente 600px de ancho en cada ancho que falla: un ancho fijo - usa max-width/%/fr/minmax en su lugar
- primer plano: responsive-report/closeups/01-horizontal-overflow-320.png
La línea de pistas es el diagnóstico. Léela antes de abrir el CSS.
3. Bucle de corrección
- Corrige el ancho que falle más pequeño primero. El móvil es la base, y corregirlo a menudo corrige el resto.
- Corrige la causa raíz a la que apuntan las pistas, en la fuente que utiliza el proyecto (la clase Tailwind, el parcial SCSS, el componente con estilo), no con una anulación puntual.
references/checks.mdenumera causas y correcciones para cada comprobación. - Vuelve a ejecutar (
--quick), repite, luego haz una ejecución completa. Detente cuando haya 0 errores y cada advertencia esté corregida o tenga una razón. - ¿Algo rompe intencionalmente una regla (una forma decorativa que se sale de la pantalla, una superposición deliberada en un collage héroe)? Marca ese elemento
data-responsive-ignore="text-overlap"(nombres de comprobación separados por espacios) y añade un comentario en el código explicando por qué. Ignorar contenido real para obtener una ejecución verde es lo mismo que no probar.
4. Míralo
El verificador encuentra lo que está mediblemente roto. Algunos problemas no son medibles: ajustes incómodos (una palabra huérfana en un botón), un último elemento de cuadrícula solitario, grandes espacios vacíos a 1920px+, un recorte de imagen que corta el sujeto, un menú técnicamente correcto pero difícil de usar. Abre las capturas de pantalla que la ejecución guardó (screens/320.png, 375, 768, 1024, 1440 y los closeups/) y míralas. Si no puedes ver imágenes, dilo en el informe en lugar de afirmar que hiciste una revisión visual.
Cuando reportes problemas visuales al usuario, describe los elementos por qué y dónde están ("la insignia de precio en la foto del producto", "la segunda tarjeta en la cuadrícula del menú"), no por nombres de clase. Los usuarios no leen selectores DOM. Guarda los selectores en tus propias notas para encontrar el código.
5. Solicitudes solo de auditoría
Si el usuario pide verificar o auditar un sitio (no corregirlo), ejecuta primero el verificador completo e informa los hallazgos agrupados por gravedad y rango de ancho, con capturas de pantalla, antes de tocar el código. Pregunta antes de corregir si el alcance es grande.
6. Informa al usuario lo que se verificó
Termina con un breve resumen fáctico:
- qué cambiaste (archivos, componentes);
- qué se probó: páginas,
N anchos 320–1920px, teléfonos horizontales; resultado del verificador (0 errores, 1 advertencia); - cada advertencia restante y por qué se queda;
- dónde están las capturas de pantalla;
- qué no se verificó. El verificador usa solo Chromium, por lo que peculiaridades de Safari/Firefox, teclados de dispositivos reales, zoom al 200% solo texto, RTL y páginas detrás de inicio de sesión sin un estado de almacenamiento no están cubiertos a menos que los hayas probado por separado.
Archivos de referencia
references/patterns.md: CSS mobile-first listo para copiar para bloques de construcción comunes. Léelo al construir un nuevo diseño o componente.references/stacks.md: cómo se ven mobile-first y los puntos de ruptura en Tailwind, Bootstrap, SCSS, módulos CSS, CSS-in-JS, MUI/Chakra, Vue/Svelte/Angular, plantillas de servidor, además de cómo servir cada uno para el verificador.references/checks.md: cada hallazgo del verificador con causas típicas, correcciones y falsos positivos conocidos. Léelo cuando la causa de un hallazgo no sea obvia.scripts/selftest/run_selftest.py: demuestra que el verificador aún detecta cada tipo de error (14 fixtures). Ejecútalo después de editar el verificador.