mobile-responsive

移动端响应式设计

此技能涉及的每一处 Web UI 都必须：（1）从 320px 到大型桌面屏幕均能完美运行；（2）绝不产生水平溢出；（3）外观经过精心设计；（4）与项目现有及未来的其他部分保持视觉一致。

采用移动端优先的方式：基础的无前缀样式针对最小屏幕，然后再逐步增加更大屏幕的样式。绝不要从桌面端开始再缩小适配。

步骤 0：先了解项目约定（不要跳过）

编写或修改任何 UI 前，先阅读已有内容，确保新工作融入其中，而非格格不入。美观且一致，胜过新奇但孤立。

1. 查找同级组件，包括相同目录或功能区中的组件。阅读其中两三个。
2. 总结已有约定：
   • 样式系统（Tailwind、CSS Modules、styled-components、纯 CSS、Bootstrap 等）。与项目保持一致，绝不要引入第二套系统。
   • 实际使用的间距刻度（例如只使用 4 / 8 / 16 / 24 / 32，或 Tailwind 的 gap-2 gap-4 gap-6）。沿用相同步长。
   • 字号刻度（标题与正文使用的具体字号和字重）。
   • 已选用的断点（sm md lg 或自定义值）。使用同一组断点，不要另设断点。
   • 颜色／间距设计令牌或主题变量。使用令牌，绝不要硬编码与令牌重复的十六进制颜色值或像素值。
   • 周围区块使用的容器／最大宽度和水平内边距模式。
   • 组件结构约定（属性／变体／插槽的命名方式）。
3. 保持一致。新卡片应让人感觉与旧卡片是在同一版本中推出的。如果项目尚无约定，则建立一套清晰的约定（参见 references/design-consistency.md），并保持一致地应用，让后续组件有章可循。

如果存在 tailwind.config、主题文件或设计令牌文件，请先阅读。这些文件是间距、断点和颜色的权威来源。

步骤 1：采用移动端优先的方式构建并修复

1. 为最小屏幕编写基础样式，不带任何断点前缀，也不使用媒体查询。
2. 只使用最小宽度断点，逐层叠加更大屏幕的样式（Tailwind 的 sm: md: lg: 都是最小宽度断点；在 CSS 中使用 @media (min-width: ...)）。
3. 所有间距、尺寸和断点值均遵循步骤 0 中总结的约定。

步骤 2：确保绝不溢出（硬性要求）

移动端出现水平滚动就是缺陷，绝不可接受。应从源头防止。最常见的原因及修复方法：

• 固定宽度改用 w-full max-w-[Npx]（Tailwind）或 width:100%; max-width:Npx。
• 无法收缩的弹性子元素添加 min-w-0（对于需要显示省略号的文本，还要添加 truncate）。
• 宽幅媒体：所有 img/video/iframe/svg 都添加 max-w-full h-auto。
• 不含空格的长字符串／URL使用 break-words / overflow-wrap: anywhere。
• 固定宽度表格：用 overflow-x-auto 包裹，让表格滚动，而不是整个页面滚动。
• 负边距／100vw：100vw 包含滚动条宽度，会导致溢出，因此优先使用 w-full。
• 超出边缘的绝对定位／位移元素：在有尺寸的父元素上使用 overflow-hidden 将其裁切。

构建完成后，请自行检查（或使用 scripts/check-overflow.js），确认下方设备矩阵中的每种屏幕宽度都没有水平滚动。完整详解见 references/overflow-prevention.md。

步骤 3：让界面不止能用，还要美观

响应式布局不等于把内容挤在一起。应确保布局在各种尺寸下都协调美观。

• 重新排布，而不是一味缩小。 多列网格在移动设备上应减少列数或改为单列堆叠（grid-cols-1 sm:grid-cols-2 lg:grid-cols-3），而不是继续保留拥挤的列。
• 灵活调整字号。 使用 clamp() 或响应式工具类缩放标题，避免标题在小屏幕上显得过大（text-2xl md:text-4xl）。
• 保留留白。 添加响应式水平内边距（px-4 md:px-8），避免内容紧贴边缘；在移动设备上缩小间距（gap-4 md:gap-8）。
• 交互元素的触控区域应约为 44px 或更大（min-h-11，并设置合适的内边距）。
• 控制阅读宽度。 限制正文每行的长度（max-w-prose / 约 65ch）。
• 隐藏或转换。 在 md 以下将桌面导航折叠为切换按钮；不要任由导航换行成一团。
• 顺序很重要。 使用 order-* / flex-col-reverse，让最重要的内容（通常是标题或主要 CTA）在移动设备上排在最前面。

步骤 4：在完整的设备尺寸范围内验证

布局能在某一种手机宽度下正常显示，并不代表它就“适配移动设备”。请按以下矩阵逐一检查：

宽度	对应设备
320px	最小尺寸的手机，用于压力测试
375px	标准手机
414px	大屏手机
768px	竖屏平板
1024px	横屏平板 / 小型笔记本电脑
1280px	桌面设备
1440px+	大屏桌面设备

在每种尺寸下检查：没有水平滚动，没有内容被裁切或重叠，文字清晰易读，控件可点击，与相邻区块的对齐关系保持完整。然后用一两句话说明修改了什么以及原因。不要改动无关代码。

规则

• 移动优先，仅使用 min-width。 除非确实需要仅适用于桌面设备的行为，否则避免使用 max-width 查询。
• 遵循现有系统。 切勿添加新的 CSS 框架或并行的间距／字号体系。复用现有令牌和惯例（步骤 0）。
• 使用相对单位。 优先使用 rem / % / fr / vw / minmax / clamp，而不是固定的 px；不要为内容长度不固定的容器设置固定像素高度。
• 绝不允许溢出。 应从根本上修复水平滚动问题。
• 默认追求美观。 如果快速修复不够美观，就采用稍复杂一些、但看起来更妥当的修复方案。
• 限定修改范围。 不要重新设计用户未要求修改的组件，但要确保新组件与现有组件保持一致。

参考文件（按需阅读）

• references/breakpoints.md：断点值、设备矩阵、容器查询和流体字号。
• references/overflow-prevention.md：各种溢出原因、修复方法和调试技巧。
• references/design-consistency.md：提取并匹配项目的设计语言；在没有现成设计语言时构建令牌系统。
• references/frameworks.md：各技术栈的语法（Tailwind、纯 CSS、CSS Modules、styled-components、Bootstrap、Flutter web）。

快速示例

之前（固定宽度，仅适用于桌面设备，在手机上会溢出）：

<div className="flex w-[960px] gap-8 p-10">
  <img src="/hero.png" width="600" />
  <div>
    <h1 className="text-5xl">Welcome</h1>
    <p>Some long description...</p>
  </div>
</div>

之后（流式布局，在移动设备上堆叠、不发生溢出、可平滑缩放，并复用项目现有的间距尺度）：

<div className="flex flex-col md:flex-row w-full max-w-[960px] gap-4 md:gap-8 px-4 py-6 md:p-10">
  <img src="/hero.png" className="w-full md:max-w-[600px] h-auto rounded-lg" />
  <div className="min-w-0">
    <h1 className="text-3xl md:text-5xl">Welcome</h1>
    <p className="max-w-prose break-words">Some long description...</p>
  </div>
</div>