Mobile Vite + Capacitor Skill

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />

Use CSS environment variables for insets:

padding-top: env(safe-area-inset-top);
padding-bottom: env(safe-area-inset-bottom);
padding-left: env(safe-area-inset-left);
padding-right: env(safe-area-inset-right);

Prefer 100dvh over 100vh — 100vh ignores the browser chrome on mobile:

min-height: 100dvh; /* dynamic viewport height */

Define CSS custom properties once on :root and reuse everywhere (see references/css-mobile-patterns.md).

2. Touch Targets

• Apple HIG minimum: 44×44 pt
• Material Design minimum: 48×48 dp
• Never use touch targets smaller than min-h-[44px] min-w-[44px]
• Use p-3 (12px) padding on icon buttons to expand hit area without changing visual size
• Apply touch-manipulation to interactive elements to eliminate 300ms tap delay:

  touch-action: touch-manipulation;
  

• Tailwind shorthand: min-h-[44px] min-w-[44px] flex items-center justify-center

3. Typography Rules

• Set minimum font-size: 16px on all <input>, <textarea>, <select> — iOS zooms in on anything smaller
• Use system font stack for native feel and zero font-loading cost:

  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  

• Apply user-select: none to non-text UI elements (buttons, nav, icons) to prevent accidental text selection on long-press
• Avoid text-size-adjust: none — it breaks accessibility

4. Capacitor-Specific

Status Bar

Use @capacitor/status-bar to control color and style:

import { StatusBar, Style } from '@capacitor/status-bar';
await StatusBar.setStyle({ style: Style.Dark });
await StatusBar.setBackgroundColor({ color: '#ffffff' });

Call on app resume and after navigation to dark/light screens.

Keyboard Avoidance

Use @capacitor/keyboard with resizeOnFullScreen: true in capacitor.config.ts. Listen to keyboard events to adjust scroll position:

import { Keyboard } from '@capacitor/keyboard';
Keyboard.addListener('keyboardWillShow', ({ keyboardHeight }) => {
  // shift focused input into view
});

Never rely on CSS position: fixed for inputs — it breaks on iOS when keyboard opens.

Hardware Back Button (Android)

Register a listener to prevent accidental app exit and handle modal/sheet dismissal:

import { App } from '@capacitor/app';
App.addListener('backButton', ({ canGoBack }) => {
  if (!canGoBack) App.exitApp();
  else window.history.back();
});

See docs/ANDROID_BACK_BUTTON.md for the full pattern used in this project.

Splash Screen

Configure @capacitor/splash-screen in capacitor.config.ts. Hide programmatically after app is ready:

import { SplashScreen } from '@capacitor/splash-screen';
await SplashScreen.hide({ fadeOutDuration: 300 });

Never auto-hide — wait for data/auth to load first to avoid flash of unauthenticated content.

WebView Differences

• iOS WKWebView: no IndexedDB persistence across app restarts without entitlement; use Capacitor Preferences for small data
• Android WebView: enable hardware acceleration in AndroidManifest.xml
• Both: position: fixed elements can flicker during scroll — use transform: translateZ(0) to promote to GPU layer

5. CSS Performance

Use transform instead of top/left/margin for animations — avoids layout reflow:

/* ✅ GPU-composited */