Responsive web UI

Responsive web UI 指界面把不同视口下的可用性当成正式交付契约，而不是“桌面版做好后再缩一缩”。它关注的是布局、信息层级、交互方式和状态可读性如何在手机、平板和桌面之间持续成立，尤其适用于密集控制台、嵌入式运维界面和需要长期使用的工具型 Web UI（projects/dockrev.md）。

它与 React app、Embedded admin UI、Floating UI tooltip 常同时出现，但边界不同。React app 讲前端运行时，Embedded admin UI 讲前后端一体交付，Floating UI tooltip 讲局部浮层；Responsive web UI 讲的是“跨视口后这个产品还能不能被正确理解和操作”。

当项目需要在多个视口上长期可用，且改动会影响页面骨架、栅格、导航切换、表格/卡片降级、抽屉/对话框、触控操作、动态高度或窄屏信息密度时使用。只要维护者需要明确回答“手机上怎么用”“平板上怎样读”“桌面端是否还能高效操作”，就该命中本 Topic。

如果页面只是普通 marketing site、几乎没有状态密度，或者响应式只体现在几条 CSS 断点上，而不影响信息架构与交互契约，则不需要专门上升到这里。Responsive web UI 更适合那些一旦处理不好就会严重损害可操作性的界面。

在 style playbook 里，Responsive web UI 的默认做法不是只记录“用了什么技术”，而是记录维护者真正需要反复执行的约束、验证和组合方式。现有样本反复出现以下习惯：

• 采用 mobile-first：先把默认样式视为手机基线，再用 Tailwind 断点向上增强；页面骨架优先使用官方断点 sm=40rem、md=48rem、lg=64rem、xl=80rem、2xl=96rem，不要在每个页面随意发明一套 breakpoints。证据：tailwindcss.com/docs/responsive-design
• 页面级变化看 viewport，组件级变化看 container。导航壳、主内容区、全局栅格用 viewport breakpoints；可复用卡片、统计块、过滤器条、信息面板优先用 @container 和 container query，避免组件只能依赖整页宽度。证据：tailwindcss.com/docs/hover-focus-and-other-states#media-and-feature-queries
• 移动端全高界面不要默认写死 100vh；优先用 dvh / svh / lvh 对应的 Tailwind utilities（如 min-h-dvh），并对贴边底栏、顶部标题栏、全屏面板补 env(safe-area-inset-*) 安全区内边距。证据：tailwindcss.com/docs/height、developer.mozilla.org/en-US/docs/Web/CSS/CSS_values_and_units、developer.mozilla.org/en-US/docs/Web/CSS/env
• 所有面向真实手机浏览器的页面必须声明 width=device-width, initial-scale=1；只有在软键盘顶起布局确实影响主流程时，才追加 interactive-widget=resizes-content 这类精细控制。证据：developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/viewport
• 默认先确定每个视口的主任务，再决定布局。窄屏首先保证“能完成关键操作”，大屏再追求“能同时看见更多状态”；不要为了在桌面端塞下所有信息，逼手机用户横向滚动或在多个区域之间迷路。
• 对密集控制台来说，响应式不只是栅格换行，还包括术语压缩、状态摘要、折叠策略和操作优先级。若一个按钮、标签或 tooltip 只有在桌面宽度下才看得懂，那它就还没有完成真正的 responsive 设计。
• 优先把页面级响应式和组件级响应式拆开思考：导航壳、主栏/侧栏、面板编排看 viewport；卡片、统计块、局部过滤器和表单分组看 container。这样组件才能在不同嵌入场景下继续复用。
• 验收时至少覆盖一个窄屏断点、一个中等断点和一个桌面断点，并检查滚动方向、触控点击区、抽屉/对话框是否遮挡关键信息、状态说明是否仍然清楚。没有这类验证，响应式往往只是“看起来会缩放”。

• projects/dockrev.md：核心样本。它是密集状态型运维控制台，不是展示性页面，因此非常适合说明响应式为什么必须同时处理布局、状态解释和窄屏操作路径，而不能只靠 Tailwind 断点堆叠。
• skills/style-responsive-web-ui/SKILL.md：分发层的 group Skill 也强调同一件事：后续 Agent 读取它时，应该被引导去回答视口与操作路径，而不是泛泛讲“这个项目用了响应式 CSS”。

• 只在桌面宽度下设计，再靠 CSS 被动压缩到手机，会把复杂控制台做成“理论上可访问，实际上不可操作”的假响应式。
• 把响应式等同于隐藏内容，会导致窄屏用户失去关键状态来源，只剩下一堆图标和截断文本。
• 只验宽度，不验触控、软键盘、动态视口和安全区，移动端问题会在真实设备上集中爆发。
• 把所有局部浮层、抽屉和 tooltip 问题都塞给本 Topic，而不回到 Floating UI tooltip、Embedded admin UI 等相邻 Topic 收边界，会让回答越来越空。

• projects/dockrev.md
• skills/style-responsive-web-ui/SKILL.md
• skills/style-playbook/references/data/topics/responsive-web-ui.json