CommunityProgramación y desarrollogithub.com

responsive-web

Habilidad de codificación. Crea y verifica interfaces web que funcionan en todos los anchos de pantalla (desde teléfonos de 320px hasta monitores de 2560px) usando un enfoque mobile-first que funciona con cualquier stack: CSS plano, Tailwind, Bootstrap, SCSS, módulos CSS, CSS-in-JS, React/Vue/Svelte/Angular o plantillas renderizadas en servidor. Incluye un verificador Playwright que recorre más de 150 anchos además de teléfonos en modo horizontal y mide roturas reales del diseño: desplazamiento horizontal, texto recortado o superpuesto, objetivos táctiles cubiertos o demasiado pequeños, imágenes estiradas, meta etiqueta de viewport ausente o que bloquea el zoom.

¿Qué es responsive-web?

Esta habilidad para agentes de IA (como Claude Code, Cursor o Codex) proporciona un enfoque sistemático y verificable para construir interfaces web responsivas. Se enfoca en dos mitades que siempre van juntas: construir con un enfoque mobile-first usando `min-width` y técnicas adaptativas (como `grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr))`), y luego verificar el resultado con un script Playwright que analiza el diseño en más de 150 anchos de pantalla, midiendo errores reales como desbordamiento horizontal, texto recortado, objetivos táctiles pequeños y más. El verificador funciona con cualquier stack: React, Vue, Svelte, Angular, Tailwind, Bootstrap, SCSS, CSS plano, etc., y se ejecuta desde la línea de comandos con `python scripts/check_responsive.py <url>`. La habilidad fomenta un ciclo de depuración guiado por los resultados del chequeo, comenzando por el ancho más pequeño que falla y solucionando la causa raíz en lugar de ocultar síntomas con `overflow: hidden` o `user-scalable=no`. Incluye referencias detalladas para patrones CSS, sintaxis específica de cada stack y soluciones para cada tipo de error.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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:

  1. Construir mobile-first: escribe el diseño para que se adapte por sí solo y necesite pocos puntos de ruptura.
  2. 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 @theme en 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 .html está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 parte min(100%, …) es lo que lo evita).
  • Filas que deben ajustarse: display: flex; flex-wrap: wrap; gap: … con un flex-basis razonable.
  • Tamaños: width: 100%; max-width: 40rem en lugar de width: 640px. Tipo y espaciado fluidos con clamp(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.

RompedorPor qué rompeUsa en su lugar
width/min-width fijo en px en contenedoresmás ancho que un teléfono de 320pxmax-width + width:100%, %, fr, minmax()
hijo de flex/grid con contenido largolos hijos tienen por defecto min-width: auto y se niegan a encogersemin-width: 0 en el hijo (o minmax(0,1fr))
palabras, URLs, correos, códigos largossin oportunidad de divisiónoverflow-wrap: anywhere en contenedores de texto
white-space: nowrap en botones/etiquetas/navel texto no puede ajustarse, empuja el anchopermitir ajuste, o puntos suspensivos con min-width:0 + un title
imágenes, vídeos, iframes, embebidosancho intrínseco > pantallamax-width:100%; height:auto; aspect-ratio para embebidos
tablaslas columnas no pueden encogerse por debajo del contenidoenvolver en contenedor overflow-x:auto, o apilar filas en pantallas pequeñas
bloques pre/codeespacios en blanco preservadosoverflow-x:auto en el bloque
100vwincluye la barra de desplazamiento, por lo que es ~15px más ancho en escritorio100% (o 100dvw solo para sangrado completo con cuidado)
height fijo en cajas con textoel texto se ajusta a más líneas en teléfonos y se desborda/recortamin-height, o ninguna altura
posicionamiento absoluto del contenidono ocupa espacio; colisiona en otros anchosflujo normal/cuadrícula; absoluto solo para decoración
height: 100vh en héroeslas barras del navegador móvil y las pantallas horizontales cortas lo recortanmin-height: 100svh (con 100vh como fallback antes)

Nunca ocultes el síntoma

  • No uses overflow-x: hidden en html/body para detener el desplazamiento lateral. Oculta el error mientras el contenido sigue recortado (y rompe position: sticky). Encuentra el elemento que es demasiado ancho. El verificador reporta este enmascaramiento como clipped-offscreen.
  • No uses user-scalable=no ni maximum-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: 16px o más en teléfonos, de lo contrario Safari iOS hace zoom al enfocar. Usa type, inputmode y autocomplete adecuados.
  • 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 con viewport-fit=cover.

Tipografía, medios, navegación, contenido

  • rem para texto, clamp() para encabezados, longitud de línea limitada (max-width: 65ch aproximadamente), line-height sin unidad.
  • Imágenes: srcset/sizes para fotos, atributos width/height o aspect-ratio para evitar cambio de diseño, object-fit: cover cuando 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 con aria-expanded/aria-controls que 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-overflowla página se desplaza lateralmente; nombra el elemento que sobresale y qué lo fuerza a ser ancho
clipped-offscreencontenido recortado en el borde de la pantalla (a menudo oculto por overflow-x:hidden en body)
occluded-targetun enlace/botón está cubierto por otro elemento (o por una barra fija en cada posición de desplazamiento)
small-targetobjetivo táctil de menos de 24px y apiñado por vecinos
text-spill / text-clippedel texto se sale de su caja / está recortado por un tamaño fijo + overflow:hidden
text-overlaptexto de dos bloques no relacionados dibujado uno encima del otro
distorted-mediaimagen/video estirado (relación de caja ≠ relación natural, sin object-fit)
viewport-meta, layout-viewportmeta 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

  1. Corrige el ancho que falle más pequeño primero. El móvil es la base, y corregirlo a menudo corrige el resto.
  2. 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.md enumera causas y correcciones para cada comprobación.
  3. 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.
  4. ¿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.

Skills relacionados