--- name: mobile-hybrid-audit description: Audit and fix web projects for pixel-perfect mobile experience as PWA, Capacitor app, or hybrid. Use this skill whenever the user mentions mobile audit, mobile-ready, mobile responsive, PWA, Progressive Web App, Capacitor, hybrid app, mobile app from web, iOS WebView, Android WebView, safe areas, notch handling, edge-to-edge, mobile keyboard issues, splash screen, status bar, mobile viewport, app store readiness, or asks to "make this work on mobile", "prepare for iOS/Android", "ship as a mobile app", "fix mobile bugs", "audit my PWA", or any request involving turning a web app into a mobile-grade experience. Also trigger when the user shows symptoms like content under the notch, footer hidden by keyboard, splash screen stuck, status bar overlap, 100vh issues, or input zoom on iOS. --- # Mobile Hybrid Pixel-Perfect Audit & Fix This skill audits and fixes web projects to deliver a production-grade mobile experience as PWA, Capacitor app, or both. The goal is a native-feeling app that is stable, responsive, safe-area aware, keyboard-friendly, with a clean splash and status bar, and installable as a PWA — without breaking existing styling or features. ## When to use Trigger this skill when the user wants to: - Audit an existing web app for mobile readiness - Fix specific mobile bugs (notch overlap, keyboard, scroll, viewport) - Add or improve PWA support (manifest, service worker, install) - Add or improve Capacitor wrapping (iOS/Android) - Prepare a project for App Store / Play Store submission - Migrate from web-only to hybrid mobile ## When NOT to use - Building a brand new app from scratch with a full visual redesign — this skill preserves existing design, it doesn't reinvent it - Pure native development (Swift, Kotlin) — Capacitor only - Pure CI/CD pipelines — use a dedicated Capacitor CI/CD skill - Backend / API work - React Native or Flutter projects — this skill is web-based hybrid only ## Working principles 1. **Read before editing.** Always inspect the current state of a file before modifying it. Preserve existing styles and conventions. 2. **Minimal but robust changes.** Improve what exists; don't duplicate or rewrite wholesale. 3. **Justify every change.** The final report must list each modification with reasoning. 4. **Detect, then act.** Framework, Capacitor version, and PWA state determine which references to load. 5. **Never refactor visuals without explicit consent.** Mobile fixes shouldn't change the look unless the user asks. ## Workflow ### Step 1 — Detect the environment Run the detection script first: ```bash bash scripts/detect.sh ``` This outputs a JSON-ish summary of: - Framework (Vite/React, Next.js, Vue, Nuxt, Svelte, Angular, plain) - Build output directory (`dist`, `build`, `out`, `.next`) - Package manager (npm, pnpm, yarn, bun) - PWA state (manifest, service worker, `vite-plugin-pwa`) - Capacitor state (installed, version, `android/`, `ios/`, `capacitor.config.*`) - Capacitor plugins installed - CSS entry file - HTML entry file (`index.html`, `_document.tsx`, `app/layout.tsx`) If the script can't be run, perform the same checks manually by reading `package.json`, listing the root directory, and grepping for `@capacitor/` imports. ### Step 2 — Decide the target mode Confirm with the user (or infer from project state): | Mode | Trigger | |---|---| | Web + PWA only | No `@capacitor/` deps, user wants installable web app | | Capacitor only | `android/` or `ios/` exists, no manifest needed for distribution | | PWA + Capacitor | User wants both (recommended for max reach) | If Capacitor is in scope, also decide **how the shell loads web content** — embedded (`webDir`, offline-first, re-build per change) vs remote (`server.url`, OTA instant updates, App Review 4.2 risk). This is architectural and hard to reverse. See `references/hybrid-architecture.md` before choosing. If unsure, ask the user one question with `ask_user_input_v0` style options. ### Step 3 — Load the relevant references Read **only** the references needed for the detected mode. Each reference is self-contained. - **`references/audit-checklist.md`** — The full audit checklist. Load this first when running a complete audit. It covers HTML head, CSS globals, safe areas, responsive, accessibility, performance, build verification. - **`references/pwa.md`** — Load if PWA is in scope. Covers manifest, service worker, install prompt, offline strategies, `vite-plugin-pwa` configuration. - **`references/capacitor.md`** — Load if Capacitor is in scope. Covers `capacitor.config`, plugin selection, `npx cap sync` workflow, version-specific behavior (Capacitor 6/7/8). - **`references/hybrid-architecture.md`** — Load when deciding how the shell loads web content (embedded vs remote `server.url` / OTA) and for cross-cutting production pitfalls: chunk-reload net for hash-based builds, auth-listener deadlock (Supabase), Sign in with Apple requirement, WebView storage durability. - **`references/ios.md`** — Load when working on iOS specifics: Dynamic Island, notch, status bar styles, splash screen, Universal Links, ATT, Privacy Manifest, font sizing to prevent input zoom. - **`references/android.md`** — Load when working on Android specifics: edge-to-edge (mandatory on SDK 36+), status bar, navigation bar, back button, adaptive icons, App Links, splash screen API. - **`references/safe-areas.md`** — Load for any safe-area issue (notch overlap, footer under home indicator, edge-to-edge handling, Chromium <140 bug on Android). - **`references/keyboard.md`** — Load for keyboard issues (footer jump, input zoom, focus scroll, viewport resize behavior). - **`references/responsive.md`** — Load for responsive/pixel-perfect audit (test widths, touch targets, overflow, table-to-card patterns). - **`references/performance.md`** — Load for mobile performance work (lazy loading, virtualization, bundle, Web Vitals targets). - **`references/accessibility.md`** — Load for a11y audit (contrast, focus, labels, reduced motion, dark mode, system fonts). For a **full audit** request, the typical reading order is: `audit-checklist.md` → then the platform-specific files matching detected state. ### Step 4 — Apply fixes For each issue found: 1. Read the target file 2. Make the minimum change needed 3. If a template fits exactly (e.g. CSS globals, init mobile script, manifest), copy from `assets/` and adapt — don't retype from scratch 4. Track every modified file for the final report Available templates in `assets/`: - `mobile-base.css` — Safe-area variables, body resets, input rules, touch targets - `initMobileApp.ts` — Capacitor runtime init (StatusBar, SplashScreen, Keyboard, lifecycle) - `manifest.template.json` — PWA manifest skeleton with all required fields - `capacitor.config.template.ts` — Capacitor config with recommended plugin settings - `viewport-meta.html` — Correct viewport + Apple meta tags - `haptics.ts` — Safe wrappers for haptic feedback (no-op on web) Each template has comments marking what to customize (brand color, app ID, app name). ### Step 5 — Verify the build After fixes, run in order: ```bash # Lint (if available) npm run lint 2>/dev/null || echo "no lint script" # Build npm run build # Capacitor sync (if applicable) npx cap sync 2>/dev/null || echo "no capacitor" ``` If any step fails, fix and re-run before producing the report. ### Step 6 — Produce the audit report Use the report template structure (see `references/audit-checklist.md` section "Final report format"). The report must include: - Detected framework & mode - Capacitor version (if applicable) - All checks passed - All issues found and how they were fixed - All files modified with one-line justification each - Items the user must verify manually on a real device - A short follow-up checklist for App Store / Play Store submission if Capacitor is in scope ## Critical version-aware behaviors These cause the most regressions. Always check before applying. ### Capacitor version detection ```bash npx cap --version 2>/dev/null # Also check: cat package.json | grep '"@capacitor/core"' ``` - **Capacitor 6** — Android edge-to-edge optional, `adjustMarginsForEdgeToEdge` available - **Capacitor 7** — `adjustMarginsForEdgeToEdge: "auto"` recommended, becomes default in 8 - **Capacitor 8 (2026+)** — Edge-to-edge **mandatory** on Android, `adjustMarginsForEdgeToEdge` removed, all safe-area handling via `env(safe-area-inset-*)` CSS. iOS defaults to SPM (Swift Package Manager) for new projects. See `references/capacitor.md` for full version migration notes. ### Android targetSdkVersion 36+ When `android/variables.gradle` has `targetSdkVersion = 36` or higher and the device runs Android 16+, **edge-to-edge is forced** by the OS regardless of Capacitor config. Safe-area CSS is mandatory or content will render under the status bar and gesture nav. ### Chromium < 140 bug on Android Older Chromium WebViews return `0px` for `env(safe-area-inset-*)` even in edge-to-edge mode. If the project targets older Android devices, install `@capacitor-community/safe-area` which patches this. See `references/safe-areas.md`. ### iOS Privacy Manifest (PrivacyInfo.xcprivacy) Required by Apple since May 2024 for App Store submission. The Capacitor iOS template includes a starter, but any added native plugin may require declaring API usage reasons. See `references/ios.md`. ### iOS input zoom If any `input`, `textarea`, or `select` has `font-size < 16px`, iOS Safari/WKWebView **zooms in on focus** and doesn't zoom back out reliably. Always enforce `font-size: 16px` minimum on form fields. This is the single most common mobile bug in web-to-hybrid migrations. ## Report format Always end with a structured report. Keep it scannable. See `references/audit-checklist.md` for the full template. The short form: ``` # Mobile Hybrid Audit Report ## Detected - Framework: … - Mode: … - PWA: … - Capacitor: vX.Y on iOS/Android ## Fixed - [critical] … - [important] … - [nice-to-have] … ## Files modified - path/to/file.css — added safe-area variables and dvh fallback - … ## Verified ✅ Viewport ✅ Safe areas ✅ Manifest ✅ Build ✅ cap sync ## Manual checks needed - Test on real iPhone (notch + keyboard) - Test on real Android (edge-to-edge + back button) - Test cold start splash - Test offline shell - Test add-to-home-screen on iOS Safari ## Submission readiness (if Capacitor) - [ ] App icon all sizes - [ ] Privacy policy URL - [ ] App Store screenshots 6.7" + 6.1" - [ ] Play Store feature graphic ``` ## Boundaries - **Do not** redesign UI. Mobile fixes are structural (padding, viewport, focus, scroll), not aesthetic. - **Do not** install plugins the project doesn't need. Camera, Push, Geolocation are only added when the user explicitly requires them. - **Do not** add a service worker to a project that doesn't need offline. Propose minimal config. - **Do not** disable zoom (`user-scalable=no`) unless the user explicitly asks — it's an accessibility violation. - **Do not** set `user-select: none` globally. Inputs and content must stay selectable. - **Do not** silently downgrade Capacitor or framework versions.