Lov Mobile Adapt

移动适配师 · Mobile Fit

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

Key Patterns (quick reference)

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 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。