lov-mobile-adapt

name	lov-mobile-adapt
description	Adapt an existing web project for mobile devices: fix overflow, add responsive layouts, convert to multi-level page navigation with back support, handle notch/Dynamic Island safe areas, fix 100vh browser chrome issues, and optimize touch targets. Trigger when user says "mobile adapt", "移动端适配", "responsive optimization", "手机适配", "fix mobile overflow", "add safe area", "多级页面", "移动端布局", or mentions adapting a site for phones/tablets.
license	MIT
compatibility	Requires Python 3.8+ (no external dependencies). Works with any web project: React, Vue, Next.js, Nuxt, Svelte, plain HTML/CSS.
metadata	{"author":"contributors","version":"0.2.0","tags":"mobile, responsive, safe-area, overflow, navigation"}

mobile-adapt — Mobile-First Adaptation for Web Projects

Scan and fix mobile adaptation issues in an existing web project: viewport configuration, overflow prevention, safe area handling, responsive breakpoints, 100vh pitfalls, touch targets, and multi-level page navigation.

When to Use

• Converting a desktop-first site to work well on mobile
• User reports overflow, cut-off content, or notch overlap on phones
• Adding mobile navigation (back button, page stack) to a sidebar-based layout
• Fixing 100vh issues on iOS/Android browsers
• General "make it mobile friendly" requests

Workflow (MANDATORY)

You MUST follow these steps in order.

Resolve SKILL_DIR from the installed skill context before running the helper. For manual execution, set it to the directory containing this SKILL.md.

Step 1: Scan the Project

Run the scanner to identify issues:

python3 "$SKILL_DIR/scripts/scan_mobile_issues.py" <project-path>

For JSON output (easier to process programmatically):

python3 "$SKILL_DIR/scripts/scan_mobile_issues.py" <project-path> --format json

Review the output. The scanner checks:

• viewport meta tag presence and viewport-fit=cover
• CSS overflow risks (fixed widths, min-width)
• 100vh usage (should be 100dvh)
• safe-area-inset usage on fixed/sticky elements
• Touch target sizes (< 44px)
• Responsive breakpoint coverage
• Tailwind-specific issues (h-screen → h-dvh)
• Text overflow without ellipsis handling

Step 2: Ask the User

IMPORTANT: Use AskUserQuestion to collect scope BEFORE making changes.

Present the scan results summary, then ask:

Question: "扫描发现 X 个问题。要修哪些类别?"
Options:
  1. 全部修复 (Recommended) — fix all categories found
  2. 只修布局和溢出 — overflow + responsive only
  3. 只修导航 — convert to mobile stack navigation
  4. 让我选具体类别 — pick specific categories

If the project has sidebar/tab navigation on desktop, also ask:

Question: "桌面端的侧边栏/tab 导航要改成移动端多级页面吗?"
Options:
  1. 是,改成 push/pop 页面栈 (Recommended)
  2. 改成底部 tab bar
  3. 不改导航结构

Step 3: Fix Issues

Apply fixes in this priority order:

1. Viewport meta — add or fix <meta name="viewport"> with viewport-fit=cover
2. Global overflow guard — add overflow-x: hidden to html/body
3. 100vh → 100dvh — replace all 100vh usages, add fallback
4. Safe area padding — add env(safe-area-inset-*) to fixed/sticky elements
5. Image/media overflow — add max-width: 100%; height: auto
6. Text overflow — add ellipsis/line-clamp where white-space: nowrap exists
7. Touch targets — increase size of interactive elements below 44px
8. Responsive breakpoints — add mobile-first media queries or Tailwind responsive
9. Navigation restructure — convert to mobile page stack if requested

For each fix, refer to references/mobile-patterns.md for the correct pattern.

Step 4: Navigation Restructure (if applicable)

When converting sidebar/panel navigation to mobile stack:

1. Identify the navigation structure (sidebar, tabs, nested panels)
2. Create a responsive layout wrapper that switches between desktop and mobile
3. On mobile: render as a full-screen page stack with back button
4. Use CSS slide transitions for page push/pop
5. Preserve desktop layout unchanged at md: breakpoint and above

See references/mobile-patterns.md → "Multi-Level Page Navigation" for implementation patterns per framework.

Step 5: Verify

After all fixes:

1. Re-run the scanner — confirm issues resolved
2. Check the site in a mobile viewport (375px width)
3. Verify:
   • No horizontal scroll
   • Content not cut off by notch or home indicator
   • All interactive elements are tappable (44px+)
   • Navigation back button works
   • Full-height layouts don't overflow behind browser chrome

CLI Reference

Argument	Default	Description
project	(required)	Path to web project root
--format	text	Output format: text or json

Key Patterns (quick reference)

Problem	Fix
Missing viewport meta	<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
100vh overflow	height: 100dvh (with 100vh fallback)
Notch overlap	padding: env(safe-area-inset-top) on fixed elements
Horizontal overflow	overflow-x: hidden on body + max-width: 100% on media
iOS input zoom	font-size: 16px on inputs
Small touch targets	min-height: 44px; min-width: 44px
Pull-to-refresh conflict	overscroll-behavior-y: contain

For detailed patterns see references/mobile-patterns.md.

Runtime context (shared)

运行前读取本 Skill 包的 skill.yaml，由宿主提供 skill-runtime/v1 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。

• 只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。
• required: true 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。
• 报错提供可复制的 context_id、字段路径与来源，诊断内容避开秘密、完整私人路径和原始配置。

通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 task-specific（仅本次）还是 reusable（可跨任务复用）。
2. task-specific 只修改当前任务，不改 Skill。
3. reusable 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. reusable 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。