lov-mobile-adapt

Mobile Fit Specialist · 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

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)

Before running, read this Skill package's skill.yaml, with the host providing the skill-runtime/v1 context. The field resolution order is: current request, project context, personal Preferences, brand Profile, general defaults.

• Use only the fields declared in the Manifest; the Profile stores public brand facts, and Preferences stores personal work preferences.
• required: true When a field is missing, ask the user one focused question according to the Manifest's question configuration; save the answer only after the user explicitly agrees.
• Errors provide a copyable context_id, field path, and source; diagnostic content avoids secrets, full private paths, and raw configuration.

General feedback loop

When the user raises revision feedback during a Skill-driven task, before continuing with the current artifact you must perform:

1. First determine whether the feedback is task-specific(this time only) or reusable(reusable across tasks).
2. task-specific Modify only the current task, not the Skill.
3. reusable First determine the scope: for domain rules, first update the corresponding canonical Skill; for rules that apply to all Skills, first update the shared specification.
4. After completing the rule update, versioning, lint, and distribution verification, then apply the changes to the current task.
5. reusable A modification invalidates previous "confirm," "continue," and "send it" responses; after completing the current artifact modification and read-back, you must stop and wait for the user's next instruction, without automatically proceeding to publishing, submission, or other external writes.