responsive-craft

响应式设计

实现适用于所有视口的响应式设计——由于缺少可视化画布，需要提前审慎决策，以弥补这一不足。

快速开始

改造现有网站： /responsive-craft audit 或“让这个网站适配响应式”或“修复移动端布局” 从零构建响应式页面： /responsive-craft build 或“以移动优先的方式构建”或“创建响应式布局” 预览所有断点： /responsive-craft preview 或“给我看看响应式预览”或“打开断点预览”

---

核心原则

1. 逐层升级策略 — 优先使用内在 CSS（auto-fit、flex-wrap、clamp()）→ 然后使用容器查询（组件级）→ 最后使用媒体查询（仅限页面级）。如果较简单的层级已能解决问题，就到此为止。

2. 先描述，再编码 — 没有画布时，应在编写 CSS 前明确描述响应式行为。在自适应模式下，使用行内行为说明（CSS 注释）。在引导模式下，编写正式的行为规范（按组件列出表格）。这两种方式都能提前发现画布会直观呈现的设计决策。

3. 默认流式布局，例外时才用断点 — 使用 clamp() 设置排版、间距和尺寸。仅在结构发生变化时使用固定断点，例如导航栏变换、列数调整和侧边栏显示状态变化。

4. 组件根据容器适配 — 组件应根据其容器而非视口进行响应。使用容器查询。侧边栏中的卡片和全宽区域中的卡片应使用相同的 CSS。

5. 拖动测试，不要跳着检查 — 在 DevTools 中缓慢调整宽度，从 280px 到 2560px。不要只检查命名断点。这样可以发现不同断点之间的问题。

6. 粘滞定位和滚动需要明确的模式 — 粘滞元素的协调、z-index 层叠上下文、溢出祖先元素、安全区域、虚拟键盘都会导致问题，且不易察觉。请使用 references/sticky-scroll-patterns.md 中的模式，不要自行 improvisation。

7. 识别设计分歧，不要默默默认 — 响应式转换存在多种有效方案时，应提供 2-3 个选项，说明各自的权衡，并请用户选择。参见 references/responsive-design-forks.md。

---

三层响应式系统

层级	工具	适用场景
连续	clamp()、流式令牌、cqi 单位	平滑缩放——字号、内边距、间距
组件	容器查询（@container）	根据上下文调整——卡片布局、导航项
结构	媒体查询（@media）	页面级变化——网格列数、导航栏变换、侧边栏

逐层升级决策树

Does this need to change layout?
  No  → clamp() for sizing. Done.
  Yes → Does it depend on CONTAINER size?
    Yes → Container query
    No  → Does it depend on VIEWPORT?
      Yes → Media query (page-level only)
      No  → :has() or intrinsic sizing (auto-fit, flex-wrap)

---

模式选择

此技能有三种模式。根据 $ARGUMENTS 判断，或向用户询问。

判断方式

• $ARGUMENTS 包含 "preview"、"show breakpoints"、"live preview" → 预览
• $ARGUMENTS 包含 "audit"、"transform"、"fix"、"improve"、"retrofit" → 改造现有网站
• $ARGUMENTS 包含 "build"、"create"、"new"、"from scratch" → 构建响应式页面
• 用户正在处理存在响应式问题的代码库 → 改造现有网站
• 用户正在开始制作新页面/组件 → 构建响应式页面
• 无法明确判断 → 询问

如果可用 AskUserQuestion：

• 改造现有网站 — 检查并改进当前代码的响应式行为
• 从零构建 — 从一开始就设计响应式布局
• 预览 — 在浏览器中启动实时多断点预览

否则：“你是要改造现有网站的响应式设计、构建新内容，还是仅预览？”

交互程度

预览模式下跳过——直接进入路由选择。

选择模式后，确定交互方式：

如果 AskUserQuestion 可用：

• 自适应——快速推进。先问 1–2 个探索性问题，然后开始工作。遇到设计分歧时，及时提出并讨论。不编写正式规格——当场做出决策。
• 引导式——产出可交付成果。进行完整的需求探索，在编码前为每个组件编写行为规格，并在每个阶段开始前征求明确批准。最适合复杂布局，或用户需要一份可供日后参考的规格说明。

否则：“你想选择（1）自适应——快速推进，我会边做边问；还是（2）引导式——我会为每个组件编写行为规格，并在编码前征求你的批准？”

如果用户没有表达偏好，默认选择自适应。

**建议选择引导式的情况：**如果布局包含 5 个或更多不同的响应式组件、多个粘性元素，或采用仪表板式布局，建议选择引导式——行为规格可以避免后续代价高昂的返工。

---

路由选择

选择模式和交互方式后：

模式	读取工作流	立即加载
预览	workflows/preview.md	无
转换现有内容	workflows/transform-existing.md	references/ai-failure-patterns.md
构建响应式布局	workflows/build-responsive.md	references/modern-css-patterns.md、references/ai-failure-patterns.md

按需加载其他参考资料：

• references/sticky-scroll-patterns.md——涉及粘性元素、滚动捕捉或独立滚动区域时
• references/responsive-design-forks.md——检测到响应式适配方式存在歧义时
• references/testing-checklist.md——验证阶段
• references/modern-css-patterns.md——在转换模式下实施修复时

---

易错点——Claude 在响应式设计中常犯的错误

以下是最常见的错误。请根据此列表检查每个响应式输出。

1. 在移动设备上使用 100vh——使用 svh/dvh，并以 vh 作为回退。100vh 会导致内容延伸到移动浏览器界面后方。

2. 优先考虑桌面端的媒体查询——始终使用 min-width（移动端优先），而不是 max-width。移动端需要加载的覆盖样式更少。

3. Flex 子元素缺少 min-width: 0——Flex 的 min-width 默认值为 auto（内容尺寸）。长文本或图片会溢出。内容动态变化时，请添加 min-width: 0。

4. overflow: hidden 会破坏粘性定位——任何带有 overflow: hidden/scroll/auto 的祖先元素都会破坏 position: sticky。如需视觉裁剪，请使用 overflow: clip。

5. transform 会破坏 position: fixed——祖先元素上的任何变换都会使固定定位的子元素相对于该祖先定位，而不是相对于视口定位。

6. iOS 上输入框字号小于 16px 会触发缩放——输入框的 font-size 小于 16px 时，Safari 会缩放视口。请使用 font-size: max(16px, 1rem)。

7. 缺少安全区域内边距——带刘海的设备需要 env(safe-area-inset-*)。这要求在 meta 标签中设置 viewport-fit=cover。别忘了适配横屏方向。

8. 不断增加 z-index——9999 之类的值表明你可能不了解堆叠上下文。请使用 isolation: isolate 和分层的 z-index 数值体系。

9. Flex/Grid 中的粘性元素缺少 align-self: start——如果没有这个属性，元素会拉伸至全高，导致粘性定位没有可用空间。这是最常见却不易察觉的粘性定位失效原因。

10. 只针对一种视口进行优化——在 1440px 下看起来完美的代码，可能在 320px、768px 竖屏和超宽屏下出问题。务必测试整个范围。

完整列表和代码示例请参阅 references/ai-failure-patterns.md。

---

工具

此技能在 scripts/ 中包含两个 CLI 工具，用于直观验证响应式布局。

多视口实时预览

在浏览器中同时查看所有断点，并支持热重载：

node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000
node ${CLAUDE_SKILL_DIR}/scripts/preview.js ./index.html
node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000 --breakpoints 375,768,1024,1440,1920

响应式截图

在每个断点截取屏幕截图。支持前后对比：

# Capture current state
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000

# Capture baseline, make changes, then capture again for comparison
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000 --before
# ... make responsive changes ...
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
# → generates comparison.html with before/after at each breakpoint

这两个工具均无需安装依赖，只需 Node.js。截取屏幕截图需要使用 dev-browser 进行无头截图。

---

参考索引

文件	内容	何时加载
modern-css-patterns.md	容器查询、clamp()、subgrid、:has()、视口单位、滚动驱动动画、嵌套、@layer、逻辑属性	编写或审查响应式 CSS 时
sticky-scroll-patterns.md	粘性元素协调、scroll-snap、独立滚动区域、响应式数据表、模态框/抽屉、IntersectionObserver	处理粘性元素、滚动或复杂布局模式时
responsive-design-forks.md	8 种模棱两可的桌面端→移动端转换方案及其选项和权衡	响应式转换没有唯一正确答案时
ai-failure-patterns.md	13 类 AI 响应式故障，包含错误/正确的代码示例和输出前检查清单	输出响应式代码前进行检查
testing-checklist.md	优先测试的视口、10 项检查、边缘情况、三级测试策略、Playwright 模式	实现后的验证步骤

工作流索引

工作流	目的
transform-existing.md	审查 → 找出分支情况 → 按优先级修复响应式问题
build-responsive.md	描述行为 → 奠定基础 → 移动端优先构建 → 验证
preview.md	在浏览器中启动实时多断点预览