Media queries con Claude Code: guía CSS práctica
Implementa CSS responsive con Claude Code: media queries, container queries, preferencias y pruebas Playwright.
Una página puede verse bien en tu portátil y fallar justo donde importa: el artículo en móvil, una tarjeta de afiliado dentro de una barra lateral estrecha, el modo oscuro o una pantalla de administración usada durante horas. Pedir a Claude Code “hazlo responsive” no basta. Hay que darle reglas de layout, preferencias de usuario y pruebas concretas.
Una media query aplica CSS cuando el navegador cumple una condición. Una container query aplica CSS según el tamaño del contenedor donde vive el componente. prefers-reduced-motion y prefers-color-scheme respetan ajustes del sistema del lector. Consulta las fuentes primarias: MDN CSS media queries, Using media queries, CSS container queries, CSSWG Media Queries Level 5, W3C CSS Containment Module Level 3 y Playwright emulation.
Para bases relacionadas, revisa CSS Grid con Claude Code, patrones Flexbox, accesibilidad y optimización de rendimiento.
Regla de trabajo
Empieza mobile-first. Escribe el diseño pequeño como CSS normal y expande en pantallas amplias con @media (width >= 48rem). No elijas cortes por nombres de dispositivos. Elige el punto donde el contenido empieza a sufrir: navegación rota, tarjetas comprimidas, anuncios demasiado cerca del texto o formularios difíciles de leer.
| Criterio | Media queries | Container queries |
|---|---|---|
| Qué miran | Viewport, impresión, preferencias | Tamaño o estado del contenedor padre |
| Mejor uso | Layout de página, navegación, espaciado global | Tarjetas, CTA, precios, UI reutilizable |
| Error común | Demasiados cortes por dispositivo | Olvidar container-type |
| Prompt útil | “Cambia el layout por ancho de viewport” | “Cambia la tarjeta por ancho disponible” |
Casos reales
En un blog, apila cuerpo, CTA y relacionados en móvil; añade barra lateral solo con espacio suficiente. Las tarjetas de afiliado deben usar container queries para funcionar en cuerpo, barra lateral y bloque de relacionados.
En una página de precios SaaS, la misma tarjeta puede aparecer en home, landing y checkout. Si solo mira el viewport, puede adoptar un diseño ancho dentro de una columna estrecha.
En un panel de administración, filtros, tablas, exportación y búsqueda compiten por espacio. En móvil conviene convertir tablas en tarjetas; en escritorio se mantiene la vista por columnas. prefers-reduced-motion evita animaciones molestas para usuarios intensivos.
En contenido monetizado, los CTA deben verse sin aplastar la lectura. Usa media queries para el ritmo de página y container queries para el interior de los CTA.
HTML/CSS ejecutable
Guarda esto como responsive-demo.html y ábrelo en el navegador. Incluye mobile-first, container queries, modo oscuro, reducción de movimiento y tipografía con clamp(). Evita font-size: 4vw porque crece demasiado en pantallas anchas y puede quedar pequeño en estrechas.
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Responsive media query demo</title>
<style>
:root { color-scheme: light dark; --bg: #f7f8fb; --surface: #ffffff; --text: #1f2937; --line: #d8dee8; --accent: #0f766e; --accent-strong: #115e59; --shadow: 0 12px 30px rgb(15 23 42 / 0.12); }
* { box-sizing: border-box; }
body { margin: 0; font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; font-size: clamp(1rem, 0.94rem + 0.25vw, 1.125rem); line-height: 1.7; color: var(--text); background: var(--bg); }
a { color: var(--accent-strong); }
.site-header { padding: 1rem; border-bottom: 1px solid var(--line); background: var(--surface); position: sticky; top: 0; z-index: 10; }
.nav { display: flex; flex-wrap: wrap; gap: 0.75rem 1rem; align-items: center; justify-content: space-between; max-width: 72rem; margin: 0 auto; }
.brand { font-weight: 800; }
.nav-links { display: flex; gap: 0.75rem; padding: 0; margin: 0; list-style: none; }
.page { width: min(100% - 2rem, 72rem); margin: 2rem auto; display: grid; gap: 1.5rem; }
.hero, .article, .sidebar-card, .offer { background: var(--surface); border: 1px solid var(--line); border-radius: 8px; box-shadow: var(--shadow); }
.hero { padding: clamp(1.25rem, 1rem + 1.5vw, 2.5rem); }
h1 { margin: 0 0 0.75rem; font-size: clamp(2rem, 1.65rem + 1.6vw, 3.2rem); line-height: 1.15; }
.layout { display: grid; gap: 1.5rem; }
.article, .sidebar-card { padding: 1rem; }
.sidebar { display: grid; gap: 1rem; align-content: start; }
.offer-wrap { container-type: inline-size; container-name: offer; }
.offer { display: grid; gap: 1rem; padding: 1rem; overflow: hidden; }
.offer-media { min-height: 10rem; border-radius: 6px; background: linear-gradient(135deg, rgb(15 118 110 / 0.85), rgb(37 99 235 / 0.75)), repeating-linear-gradient(45deg, rgb(255 255 255 / 0.18) 0 10px, transparent 10px 20px); }
.button { display: inline-flex; width: fit-content; min-height: 2.75rem; align-items: center; justify-content: center; padding: 0.7rem 1rem; border-radius: 6px; background: var(--accent); color: white; font-weight: 700; text-decoration: none; transition: transform 180ms ease, background-color 180ms ease; }
.button:hover { transform: translateY(-2px); background: var(--accent-strong); }
@media (width >= 48rem) { .article { padding: 1.5rem; } .layout { grid-template-columns: minmax(0, 1fr) 18rem; align-items: start; } }
@media (width >= 72rem) { .layout { grid-template-columns: minmax(0, 2fr) minmax(18rem, 0.8fr); } }
@container offer (width >= 34rem) { .offer { grid-template-columns: 14rem minmax(0, 1fr); align-items: center; padding: 1.25rem; } }
@media (prefers-color-scheme: dark) { :root { --bg: #10151f; --surface: #18202d; --text: #eef2f7; --line: #334155; --accent: #2dd4bf; --accent-strong: #5eead4; --shadow: none; } }
@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; scroll-behavior: auto !important; transition-duration: 0.01ms !important; } }
</style>
</head>
<body>
<header class="site-header"><nav class="nav" aria-label="Main navigation"><div class="brand">ClaudeCodeLab</div><ul class="nav-links"><li><a href="#guide">Guide</a></li><li><a href="#offer">Template</a></li></ul></nav></header>
<main class="page">
<section class="hero"><h1>Media queries that survive real layouts</h1><p>Mobile-first CSS, cards with container queries, dark mode and reduced motion.</p></section>
<div class="layout" id="guide">
<article class="article"><h2>Readable article body</h2><p>The article stays readable on phones and gains a sidebar only when there is enough room.</p><div class="offer-wrap" id="offer"><section class="offer"><div class="offer-media" aria-hidden="true"></div><div><h2>Responsive review checklist</h2><p>Use this area for a download, newsletter or product CTA.</p><a class="button" href="#">Get the checklist</a></div></section></div></article>
<aside class="sidebar" aria-label="Related content"><section class="sidebar-card"><h2>Related</h2><p>Grid, Flexbox, accessibility and performance belong in the same review.</p></section></aside>
</div>
</main>
</body>
</html>
Prompts para Claude Code
Objetivo: CSS responsive para la página de artículo
Reglas:
- Base mobile-first
- Media queries de viewport solo para layout global
- Container queries para tarjetas y CTA reutilizables
- No usar font-size solo con vw; usar clamp()
- Respetar prefers-color-scheme y prefers-reduced-motion
Verificación:
- Revisar 375, 768, 1024 y 1440 px
- Probar dark mode y reduced motion con Playwright
- Señalar breakpoints duplicados o innecesarios
Revisa este diff como CSS responsive.
Prioriza overflow horizontal, texto ilegible, CTA/anuncios aplastados,
falta de container-type, violaciones de reduced-motion y exceso de breakpoints.
Devuelve solo líneas concretas y arreglos mínimos.
Prueba con Playwright
import { test, expect } from "@playwright/test";
const fileUrl = "file:///absolute/path/to/responsive-demo.html";
for (const width of [375, 768, 1024, 1440]) {
test(`no horizontal overflow at ${width}px`, async ({ page }) => {
await page.setViewportSize({ width, height: 900 });
await page.goto(fileUrl);
const hasOverflow = await page.evaluate(() => document.documentElement.scrollWidth > document.documentElement.clientWidth);
await expect(hasOverflow).toBe(false);
await expect(page.locator(".offer")).toBeVisible();
});
}
test("dark mode keeps text readable", async ({ page }) => {
await page.emulateMedia({ colorScheme: "dark" });
await page.goto(fileUrl);
await expect(page.locator("body")).toHaveCSS("color", "rgb(238, 242, 247)");
});
test("reduced motion disables hover timing", async ({ page }) => {
await page.emulateMedia({ reducedMotion: "reduce" });
await page.goto(fileUrl);
const duration = await page.locator(".button").evaluate((el) => getComputedStyle(el).transitionDuration);
expect(duration).toBe("0.01ms");
});
flowchart TD
A["Base CSS mobile-first"] --> B["Media queries para layout"]
B --> C["Container queries para tarjetas"]
C --> D["Preferencias del usuario"]
D --> E["Capturas y overflow en Playwright"]
E --> F["Prompt de revisión con Claude Code"]
Errores y monetización
Evita acumular overrides con max-width, usar viewport queries para componentes reutilizables, definir texto solo con vw y tratar reduced motion como detalle decorativo. Después de generar CSS con Claude Code, prueba textos traducidos, anuncios reales, modo oscuro y anchos estrechos.
El CSS responsive protege ingresos: mantiene visibles los CTA sin destruir la lectura. Puedes usar un CTA suave a mitad del artículo para una checklist gratis y otro más claro al final para plantillas o consultoría. Empieza por la hoja gratuita, revisa productos o prepara adopción de equipo con training.
En la prueba práctica de Masa, el mayor cambio fue pasar la tarjeta CTA a container query. La misma tarjeta funcionó en cuerpo, barra lateral y relacionados sin otro breakpoint de viewport. Playwright confirmó ausencia de overflow a 375px, texto legible en modo oscuro y movimiento reducido activado.
PDF gratis: cheatsheet de Claude Code
Introduce tu email y descarga una hoja con comandos, hábitos de revisión y flujos seguros.
Cuidamos tus datos y no enviamos spam.
Sobre el autor
Masa
Ingeniero enfocado en workflows prácticos con Claude Code.
Artículos relacionados
Escalera de permisos de Claude Code para ampliar acceso sin perder control
Pasa de read-only a ediciones limitadas, comandos de prueba y checks de deploy con menos riesgo.
Claude Code Small PR Proof Pack: cambios pequeños que sí se pueden revisar
Un paquete de prueba para PRs de Claude Code: diff, checks, URL pública, CTA y rollback.
Gate de revisión antes del commit con Claude Code
Cómo revisar con Claude Code antes del commit: diff, build, URL pública, Gumroad, consultoría, tests y archivos ajenos.