用 Claude Code 实现 CSS 媒体查询的实战指南
用 Claude Code 编写响应式 CSS：媒体查询、容器查询、用户偏好和 Playwright 验证。
页面在你的笔记本上看起来正常，并不代表它在真正的使用场景里可靠。手机文章页可能出现横向滚动，侧边栏里的商品卡片可能被压扁，深色模式下文字可能不够清楚，后台管理页的动画也可能让长期使用者疲劳。只对 Claude Code 说“帮我做成响应式”太模糊了。
这篇指南把媒体查询当作可验证的实现流程来讲。媒体查询会根据浏览器或设备环境应用 CSS；容器查询会根据组件所在容器的宽度应用 CSS；prefers-reduced-motion 和 prefers-color-scheme 这类用户偏好查询，则用于尊重访问者的系统设置。
建议同时参考官方资料：MDN 的 CSS media queries、Using media queries、CSS container queries，CSSWG 的 Media Queries Level 5，W3C 的 CSS Containment Module Level 3，以及 Playwright 的 emulation 文档。
相关基础可以继续看：Claude Code CSS Grid、Flexbox 模式、无障碍实现 和 性能优化。
先定规则
推荐从移动优先开始。先把小屏幕作为默认 CSS，再用 @media (width >= 48rem) 这类查询为更宽的屏幕增加布局。不要按设备名称写断点，例如“iPhone 断点”或“iPad 断点”。应该在内容开始变差的位置设置断点：导航换行难看、卡片太挤、广告贴正文太近、表单难以阅读。
| 判断点 | 媒体查询 | 容器查询 |
|---|---|---|
| 检查对象 | 视口、打印、用户偏好 | 父容器尺寸或状态 |
| 适合场景 | 页面布局、导航、全局留白 | 卡片、CTA、价格模块、复用组件 |
| 常见错误 | 按设备堆很多断点 | 忘记在父元素加 container-type |
| 给 Claude Code 的说法 | “按视口宽度改变页面布局” | “按卡片可用宽度改变内部布局” |
三个以上真实用例
博客文章页：手机上正文、CTA、相关文章纵向排列；宽屏时再加侧边栏。联盟营销卡片或产品 CTA 应包在容器查询里，这样同一张卡片放在正文、侧边栏、相关文章区都不会崩。
SaaS 价格页：价格卡片经常同时出现在首页、活动页和结账侧栏。只用视口媒体查询时，卡片可能误以为自己有很宽的空间。容器查询能让组件按实际可用宽度变化。
后台管理页：过滤器、表格、导出按钮和搜索框会占用大量水平空间。窄屏可以改成卡片列表，宽屏再恢复表格；同时用 prefers-reduced-motion 降低动画负担。
内容变现页：广告、资料下载和商品 CTA 要可见，但不能压坏阅读体验。用媒体查询控制整页节奏，用容器查询控制 CTA 内部布局，通常更稳。
可直接运行的 HTML/CSS
把下面代码保存为 responsive-demo.html 后直接用浏览器打开。它包含移动优先、容器查询、深色模式、减少动态效果和 clamp() 字体。不要只写 font-size: 4vw，因为极宽屏会过大，窄屏又可能过小。
<!doctype html>
<html lang="zh">
<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, container-aware cards, dark mode, and reduced motion.</p></section>
<div class="layout" id="guide">
<article class="article">
<h2>Readable article body</h2>
<p>The article column 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>
Claude Code 提示词
目标：重构文章详情页的响应式 CSS
规则：
- 默认 CSS 使用移动优先
- 页面整体布局使用 viewport media queries
- 可复用卡片和 CTA 使用 container queries
- 字体不要只用 vw，使用 clamp()
- 支持 prefers-color-scheme 和 prefers-reduced-motion
验证：
- 检查 375、768、1024、1440 px
- 用 Playwright 检查 dark mode 和 reduced motion
- 指出重复或不必要的断点
请从响应式 CSS 角度审查这个 diff。
优先找横向滚动、字号不可读、CTA/广告被压坏、缺少 container-type、
违反 reduced-motion、断点过多的问题。只返回具体行和最小修复方案。
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["移动优先默认 CSS"] --> B["整页布局使用媒体查询"]
B --> C["复用卡片使用容器查询"]
C --> D["尊重用户偏好"]
D --> E["Playwright 截图和溢出检查"]
E --> F["Claude Code 审查提示词"]
常见坑
不要不断追加 max-width 覆盖，最后会没人看得懂级联关系。不要让到处复用的卡片只依赖 viewport。不要只用 vw 设置字号。不要把 reduced motion 当成装饰性细节。也不要在 Claude Code 生成 CSS 后就结束，必须用真实文案、翻译长度、深色模式和窄屏宽度验证。
在团队协作时，建议把截图宽度、深色模式、减少动态效果、长标题、广告位和 CTA 点击区域写进 PR 检查清单。这样 Claude Code 生成的 CSS 不只是“看起来能用”，而是可以被设计、编辑和开发一起复核。
变现 CTA
响应式 CSS 会直接影响收入，因为它决定 CTA 是否清楚、广告是否压迫正文、下载入口是否能被读者自然看到。中段可以放较轻的免费清单 CTA，文末再放模板或咨询入口。可先使用免费清单，需要可复用资源时查看产品，团队落地则参考Claude Code 培训。
Masa 的实测结果是：把 CTA 卡片改成容器查询后，同一组件可以放在正文、侧栏和相关文章中，不再需要新增 viewport 断点。Playwright 检查确认了 375px 无横向滚动、深色模式文字可读、启用 reduced motion 时按钮位移动画被压低。
免费 PDF: Claude Code 速查表
输入邮箱即可获取一页 PDF，整理常用命令、审查习惯和安全工作流。
我们会妥善保护你的信息，不发送垃圾邮件。
把 Claude Code 变成真正能带来结果的工作流
先领取中文说明的免费 PDF，再进入英文商品页选择合适的教材。如果你需要团队落地、流程设计或内容变现支持，也可以直接咨询。
关于作者
Masa
专注 Claude Code 实务流程、团队导入和内容转化的工程师。
相关文章
Claude Code权限安全阶梯：逐步放开访问而不失控
从只读到有限编辑、验证命令和部署检查的 Claude Code 权限升级流程。
Claude Code 小PR证据包：让小改动真正可审查
用差异、验证命令、公开URL、CTA路径和回滚说明，把Claude Code的小PR变得可审查。
Claude Code 提交前 Review Gate：同时检查差异、测试、公开 URL 和 CTA
提交前用 Claude Code 审查差异范围、build、公开 URL、Gumroad 链接、咨询 CTA、缺少测试和无关文件。