Community编程与开发github.com

响应式网页:移动优先、任意技术栈、自动验证

构建并验证能够适配从 320px 手机到 2560px 显示器的所有屏幕宽度的网页 UI。采用移动优先的方法,支持任意技术栈:纯 CSS、Tailwind、Bootstrap、SCSS、CSS Modules、CSS-in-JS、React/Vue/Svelte/Angular 或服务端渲染模板。附带一个 Playwright 检查器,扫描超过 150 种宽度以及横屏手机,并测量真实布局故障:水平滚动、内容截断或覆盖、微小的触摸目标、拉伸的图像、遗漏或阻止缩放的视口设置。

响应式网页:移动优先、任意技术栈、自动验证 是什么?

该技能提供了一个严格的、自动化的方法,用于构建和验证真正响应式的网页 UI,适用于任何技术栈或框架。其核心是一个 Playwright 驱动的检查器,它会系统性地扫描从 320px 到 1920px 的数百种宽度(包括横屏手机和关键断点两侧),以捕获常见故障,例如水平溢出、文本重叠、触摸目标过小以及图像失真。该技能强制采用移动优先的 CSS 设计模式,偏爱使用无需断点的布局(如 `auto-fit`/`minmax` 网格),并提供了一份详细的“布局破坏者”清单,包含禁止使用的模式(如固定像素宽度、`100vh` 和 `overflow-x: hidden`)及其替代方案。修复工作按宽度从小到大进行,引导用户解决根源问题,而不是掩盖症状,最终生成一份零错误的验证报告以及一组合成截图,供人工审查。此技能适用于 Claude Code、Cursor 或 Codex 等编码代理,可在浏览器中(静态文件或开发服务器)针对给定页面执行,并提供对 SPA、慢加载内容或 localStorage 登录状态的选项。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

响应式 Web:移动优先、任意技术栈、自动验证

目标是布局能够在每种宽度下正常工作,而不是在有人挑选的五种设备宽度下工作。 Bug 往往存在于中间:412px、905px,以及 max-width: 767px 和 min-width: 769px 都停止生效的那一个像素。因此,本技能包含两个始终必须同时进行的内容:

  1. 构建移动优先:编写布局使其自适应并且只需少量断点。
  2. 验证它:运行 scripts/check_responsive.py,该脚本会渲染页面并在每种宽度下测量布局。仅凭一两个截图说“看起来没问题”不算验证。完成意味着检查器报告 0 个错误。

检查器仅查看渲染后的页面(DOM 框和计算后的样式),因此它不关心 CSS 是如何编写的。这正是它适用于任何技术的原因。

0. 首先阅读项目

在编写 CSS 之前,花一分钟找到:

  • 这里的样式是如何编写的:Tailwind(tailwind.config.* 或 CSS 中的 @theme)、Bootstrap/SCSS 变量、CSS Modules、styled-components/emotion、Vue/Svelte 作用域样式、纯 CSS 文件。用同样的系统和相同的 token 编写新代码。第二个样式系统是一个维护 bug。
  • 现有的断点,并重用它们。除非内容需要,否则不要发明新的断点。
  • 如何查看页面:一个静态的 .html 文件,或者一个开发服务器(npm run dev、php artisan serve、python manage.py runserver、rails s、dotnet watch...)。你需要一个 URL 或文件路径供检查器使用。

references/stacks.md 展示了常见技术栈的移动优先语法和断点位置。

1. 构建移动优先

为最小屏幕编写基础样式,不使用媒体查询。随着空间增大添加布局,使用 min-width 查询。 手机上获得最简单的 CSS,内容自然堆叠,每个断点只添加内容。桌面优先的方式(先写桌面,然后用 max-width 打补丁)会在补丁之间留下空隙,这些空隙正是大多数响应式 Bug 的来源。

如果代码库已经是桌面优先,不要重写它。在其约定内以移动优先的方式编写你新增或修改的部分,并修复检查器发现的问题。

优先使用无需断点即可自适应的布局

  • 网格:grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr))。列会根据空间自动出现,无需断点,且在 320px 下不会溢出(min(100%, …) 部分正是为了防止溢出)。
  • 应该换行的行:使用 display: flex; flex-wrap: wrap; gap: … 和合理的 flex-basis。
  • 尺寸:使用 width: 100%; max-width: 40rem 而不是 width: 640px。使用 clamp(min, preferred, max) 实现流体的字体和间距。
  • 出现在不同宽度插槽(侧边栏 vs 主列)中的组件:使用容器查询(container-type: inline-size + @container),使其响应其插槽而非窗口。
  • 在内容破坏处添加断点(缩小窗口直到某些内容看起来有问题),而不是在设备宽度处添加。

已知布局破坏者。编写时逐一检查。

破坏者为什么破坏改用
容器上固定的 width/min-width(单位 px)宽于 320px 的手机max-width + width:100%、%、fr、minmax()
包含长内容的 flex/grid 子项子项默认 min-width: auto 且拒绝收缩在子项上设置 min-width: 0(或 minmax(0,1fr))
长单词、URL、电子邮件、代码没有断词机会在文本容器上设置 overflow-wrap: anywhere
按钮/标签/导航上的 white-space: nowrap文本无法换行,撑开宽度允许换行,或使用省略号 + min-width:0 + title 属性
图片、视频、iframe、嵌入内容固有宽度大于屏幕max-width:100%; height:auto;对嵌入内容使用 aspect-ratio
表格列无法收缩到内容以下包裹在 overflow-x:auto 容器中,或在小屏上将行堆叠
pre/code 块保留空白在块上设置 overflow-x:auto
100vw包含滚动条,因此在桌面上大约宽 15px100%(或仅在真正全宽血统且谨慎处理时使用 100dvw)
带文本的盒子上固定 height文本在手机上换行更多,导致溢出/裁剪min-height,或不设置高度
内容的绝对定位不占据空间;在其他宽度下会碰撞使用正常流/网格;仅装饰用绝对定位
用于英雄区的 height: 100vh移动端浏览器工具栏和短横屏会裁剪它min-height: 100svh(在此之前使用 100vh 作为回退)

切勿掩盖症状

  • 不要在 html/body 上使用 overflow-x: hidden 来阻止侧向滚动。它隐藏了 bug,而内容仍然被裁剪(并且会破坏 position: sticky)。找到那个太宽的元素。检查器会将这种掩盖上报为 clipped-offscreen。
  • 不要使用 user-scalable=no 或 maximum-scale=1。阻止缩放是无障碍访问失败(WCAG 1.4.4)。
  • 不要使用 JavaScript 宽度检查或用户代理嗅探进行布局。CSS 媒体/容器查询可以无闪烁地完成。JS 可以用于行为(matchMedia),但不能用于布局。
  • 不要修改测试来让它通过(提高 --min、添加忽略项来使错误消失)。

触摸、输入、视口

  • 每个页面的 <head> 中都有 <meta name="viewport" content="width=device-width, initial-scale=1">。
  • 触摸目标至少 24x24px(WCAG 2.2 AA)。对于触摸屏上的按钮和图标控件,目标应达到 44x44px,并保持相邻元素间的间距。
  • 仅悬停的 UI(菜单、显示内容的工具提示)需要 @media (hover: hover) 和一个触摸替代方案。
  • 表单字段在手机上 font-size 应为 16px 或更大,否则 iOS Safari 会在聚焦时放大。使用适当的 type、inputmode 和 autocomplete。
  • 短横屏手机(高 320–430px)是真实存在的。固定的页眉加上 Cookie 横幅不应该覆盖超过屏幕的大约三分之一。在短高度下折叠或缩小它们(@media (max-height: 500px))。
  • 异形屏设备:仅在使用 viewport-fit=cover 时,结合 env(safe-area-inset-*) 内边距使用。

排版、媒体、导航、内容

  • 字体使用 rem,标题使用 clamp(),行长度有上限(max-width: 65ch 左右),无单位行高。
  • 图片:照片使用 srcset/sizes,使用 width/height 属性或 aspect-ratio 避免布局偏移,当盒子比例与图片不同时使用 object-fit: cover(否则图片会被拉伸)。
  • 导航:在小屏幕上使用一个真实的 <button>,配合 aria-expanded/aria-controls 打开菜单。在内容实际能容纳的宽度下才显示内联链接。
  • 保持内容一致:不要因为难以容纳而在移动端丢弃内容。可以重新排序、精简或折叠它。

references/patterns.md 为以上每一项(网格、导航、表格、表单、英雄区、卡片、媒体)都提供了可直接复制的 CSS。

2. 验证:运行检查器

一次性设置(Python 3.9+):

pip install playwright
python -m playwright install chromium

针对渲染后的页面运行它。如果存在开发服务器,请先启动它。

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   # 静态文件
  • 多个页面:传入多个 URL。检查你更改的每个页面或路由,再加上一个使用共享布局(页眉/页脚)的页面。
  • 渲染较晚的 SPA:使用 --wait-for "#app main"。需要登录的页面:使用 --storage-state state.json。
  • 修复时的内循环:使用 --quick(大约 5–10 秒)。在你说完成之前,请运行一次完整运行(每个页面大约 20–40 秒)。
  • 退出代码:0 = 无错误,1 = 发现错误(或使用 --strict 时发现警告),2 = 无法运行。

它所做的工作:以 10px 为步长扫描 320→1920px,加上常见设备宽度,以及页面自身 CSS 中发现的每个断点的两侧。它会使用真实的移动端模拟(触摸、元视口)重新加载关键宽度,并检查四个短横屏手机。在每个宽度下,它测量:

错误(必须修复)含义
horizontal-overflow页面侧向滚动;指出是哪个元素突出以及是什么强制它变宽
clipped-offscreen内容在屏幕边缘被裁剪(通常被 body 上的 overflow-x:hidden 隐藏)
occluded-target链接/按钮被另一个元素覆盖(或被每个滚动位置都存在的固定栏覆盖)
small-target触摸目标小于 24px 且被邻居挤占
text-spill / text-clipped文本溢出其盒子 / 被固定尺寸 + overflow:hidden 裁剪
text-overlap两个不相关块的文本绘制在彼此之上
distorted-media图片/视频被拉伸(盒子比例 ≠ 自然比例,没有 object-fit)
viewport-meta、layout-viewport缺少/阻止缩放的视口元标签;手机以桌面宽度渲染

警告(修复它们或说明为什么不修复):touch-target(触摸宽度下 <44px 的控件)、small-text(手机上 <12px)、input-zoom(<16px 的输入框)、fixed-coverage(固定/粘性栏超过短屏的 35%)。

报告(report.md、report.json)会像这样对发现结果进行分组:

1. **horizontal-overflow** 发生在 320-610px;568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
   - 最严重:在 320px 时超出右边缘 296 px
   - 线索:在每个失败的宽度下都保持精确的 600px 宽度:这是一个固定宽度 - 请改用 max-width/%/fr/minmax
   - 特写:responsive-report/closeups/01-horizontal-overflow-320.png

线索行就是诊断结果。在打开 CSS 之前先阅读它。

3. 修复循环

  1. 首先修复最小的失败宽度。移动端是基础,修复它通常也能修复其他问题。
  2. 修复线索指向的根本原因,在项目使用的源代码中(Tailwind 类、SCSS 部分、styled component)修复,而不是用一次性的覆盖。references/checks.md 列出了每个检查的原因和修复方法。
  3. 重新运行(--quick),重复,然后进行一次完整运行。当错误为 0 且每个警告要么已修复要么有理由时停止。
  4. 有某些内容故意违反规则(一个装饰性形状溢出屏幕、英雄区拼贴中的故意重叠)?将该元素标记为 data-responsive-ignore="text-overlap"(以空格分隔的检查名称),并在代码中添加注释说明原因。忽略真实内容以通过检查等同于不测试。

4. 查看它

检查器能找到可测量的损坏问题。有些问题是不可测量的:尴尬的换行(按钮上一个孤立的词)、孤独的最后一个网格项、1920px+ 时巨大的空白 gutter、裁剪掉主体的图像、一个技术上没问题但难以使用的菜单。打开运行保存的截图(screens/320.png、375、768、1024、1440 和 closeups/)并查看它们。如果你无法查看图片,请在报告中说明,而不是声称进行了视觉审查。

当向用户报告视觉问题时,通过元素的内容和位置来描述它们("产品照片上的价格标签"、"菜单网格中的第二张卡片"),而不是通过类名。用户不阅读 DOM 选择器。将选择器保留在你自己的笔记中以便查找代码。

5. 仅审计请求

如果用户要求检查或审计一个网站(而不是修复),先运行完整的检查器,并按照严重性和宽度范围分组报告发现结果,附上截图,然后再触碰代码。如果范围很大,请在修复前询问。

6. 告知用户已验证的内容

最后以一个简短、事实性的总结结束:

  • 你更改了什么(文件、组件);
  • 测试了什么:页面、N widths 320–1920px、横屏手机;检查器结果(0 errors, 1 warning);
  • 每个剩余的警告以及它们为何保留;
  • 截图在哪里;
  • 什么没有被验证。检查器仅使用 Chromium,因此 Safari/Firefox 怪异行为、真实设备键盘、纯文本 200% 缩放、RTL 以及未提供存储状态的登录后页面不在覆盖范围内,除非你单独测试了它们。

参考文件

  • references/patterns.md:常见构建块的可直接复制使用的移动优先 CSS。在构建新布局或组件时阅读它。
  • references/stacks.md:移动优先和断点在 Tailwind、Bootstrap、SCSS、CSS Modules、CSS-in-JS、MUI/Chakra、Vue/Svelte/Angular、服务端模板中是什么样子的,以及如何为检查器提供每个服务。
  • references/checks.md:每个检查器发现结果,附带典型原因、修复方法和已知的误报。当发现结果的原因不明显时阅读它。
  • scripts/selftest/run_selftest.py:证明检查器仍然能捕获每种 Bug 类型(14 个测试用例)。在编辑检查器后运行它。

相关技能