Claude Code Media Queries: Mobile-First CSS Guide

A page can look fine on your laptop and still fail where money is made: the mobile article view, the pricing card inside a narrow sidebar, the dark-mode reader, or the admin screen used for hours every day. Asking Claude Code to “make it responsive” is too vague. You need to give it layout rules, accessibility preferences, and verification steps.

This guide turns media queries into a practical implementation workflow. A media query applies CSS when the browser or device environment matches a condition. A container query applies CSS based on the size of the component’s parent container. User-preference queries such as prefers-reduced-motion and prefers-color-scheme respect settings chosen by the visitor.

Keep the primary references close: MDN’s CSS media queries, Using media queries, and CSS container queries, plus CSSWG Media Queries Level 5, W3C CSS Containment Module Level 3, and Playwright emulation.

For related foundations, pair this with CSS Grid with Claude Code, Flexbox patterns, accessibility implementation, and performance optimization.

The Working Rule

Start mobile-first. Write the small-screen layout as normal CSS, then add wider layouts with queries such as @media (width >= 48rem). Do not choose breakpoints by device names. Choose them where the content starts to fail: navigation wraps awkwardly, cards become cramped, ad slots crowd the article, or forms become hard to scan.

Decision	Media queries	Container queries
What they inspect	Viewport, print, user preferences	Parent container size or state
Best for	Page layout, nav, global spacing	Cards, CTAs, pricing boxes, reusable UI
Common bug	Too many device-based breakpoints	Missing `container-type` on the parent
Prompt wording	”Change the page layout by viewport width"	"Change this card by its available width”

Real Use Cases

For a blog article, keep the body, CTA, and related posts stacked on mobile. Add a sidebar only when there is enough width. Put affiliate or product cards in container-query wrappers so the same card works in the body, sidebar, and related section.

For a SaaS pricing page, pricing cards may appear on a homepage, a campaign page, and a checkout sidebar. Viewport-only CSS can make the card assume a wide layout even when the card itself is narrow. Container queries make the component portable.

For an admin dashboard, filters, tables, export buttons, and search fields need different layouts by space. Add prefers-reduced-motion so repeated use is comfortable, and test table overflow directly.

For monetized content, use media queries for page rhythm and container queries for CTA internals. This keeps ads, newsletter blocks, and product offers visible without crushing the reading experience.

Runnable HTML and CSS

Save this as responsive-demo.html and open it in a browser. It uses mobile-first CSS, container queries, dark mode, reduced motion, and clamp() typography. Avoid font-size: 4vw; viewport-only font sizing can become too large on wide screens and too small on narrow ones.

<!doctype html>
<html lang="en">
  <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;
        --muted: #5b6472;
        --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 { padding: 1rem; }
      .sidebar { display: grid; gap: 1rem; align-content: start; }
      .sidebar-card { padding: 1rem; }

      .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;
          --muted: #b6c0ce;
          --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, container-aware cards, dark mode, and reduced motion in one runnable demo.</p>
      </section>
      <div class="layout" id="guide">
        <article class="article">
          <h2>Readable article body</h2>
          <p>The article column stays readable on phones, then 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 without breaking mobile reading.</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 checks belong in the same review.</p>
          </section>
        </aside>
      </div>
    </main>
  </body>
</html>

Claude Code Prompts

Target: responsive CSS for the article detail page
Rules:
- Use mobile-first base CSS
- Use viewport media queries only for whole-page layout
- Use container queries for reusable cards and CTAs
- Do not use viewport-only font sizing; use clamp()
- Respect prefers-color-scheme and prefers-reduced-motion

Verification:
- Check 375, 768, 1024, and 1440 px
- Check dark mode and reduced motion in Playwright
- Report duplicated or unnecessary breakpoints

Review this diff as responsive CSS.
Prioritize horizontal overflow, unreadable font sizes, crushed CTA/ad blocks,
missing container-type declarations, reduced-motion violations, and breakpoint sprawl.
Return only line-specific issues and minimal fixes.

Playwright Check

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(() => {
      return 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["Mobile-first base CSS"] --> B["Viewport media queries for page layout"]
  B --> C["Container queries for reusable cards"]
  C --> D["User preference media features"]
  D --> E["Playwright screenshots and overflow checks"]
  E --> F["Claude Code review prompt"]

Pitfalls

Do not pile up max-width overrides until nobody understands the cascade. Do not use viewport queries for a card that appears in many containers. Do not set font-size with vw alone. Do not treat reduced motion as optional decoration. And do not stop after Claude Code generates CSS; verify screenshots, overflow, dark mode, reduced motion, and real translated copy.

Monetization CTA

Responsive CSS protects revenue because it keeps offers visible without damaging reading. Use a quiet mid-article CTA for a free checklist, then a stronger end-of-article CTA for templates or consulting. The free cheat sheet is a useful starting point. For reusable assets, see products. For team rollout, review Claude Code training.

In Masa’s hands-on test, the biggest improvement came from moving the CTA card to a container query. The same card worked in the article body, sidebar, and related section without adding another viewport breakpoint. Playwright confirmed no horizontal overflow at 375px, readable dark-mode text, and reduced hover motion when prefers-reduced-motion was enabled.

Claude Code Media Queries: Mobile-First CSS Guide

The Working Rule

Real Use Cases

Runnable HTML and CSS

Claude Code Prompts

Playwright Check

Pitfalls

Monetization CTA

Free PDF: Claude Code Cheatsheet

Level up your Claude Code workflow

Related Posts

Claude Code Permission Safety Ladder: Expand Access Without Losing Control

Claude Code Small PR Proof Pack: Make Tiny Changes Reviewable

Claude Code Review Gate Before Commit: Diff, Tests, Public URL, and CTA Checks

Related Products

50 Battle-Tested Claude Code Prompt Templates

The Complete Claude Code Setup & Configuration Guide