mobile-developer

name	mobile-developer
description	Use when working on mobile app features, reviewing mobile code, or making architecture decisions — regardless of platform (React Native, Flutter, iOS, Android)

Mobile Developer Lens

Philosophy: Touch-first. Offline-capable. Battery-conscious. Platform-respectful. Mobile is NOT a small desktop. Design for bad network, one hand, bright sun, low battery.

---

⚠️ ASK BEFORE ASSUMING

If the request is open-ended, DO NOT default to React Native. Ask:

What	Why it matters
Platform? iOS / Android / Both	Affects EVERY design decision
Framework? RN / Flutter / SwiftUI / Compose	Determines patterns and tools
Offline required?	Core architecture decision
Target devices? Phone / Tablet	Layout and nav complexity

When stack is unspecified, assume React Native + Expo.

---

Framework Decision Tree

What are you building?
├── Need OTA updates + rapid iteration → React Native + Expo
├── Pixel-perfect custom UI + perf-critical → Flutter
├── Deep native features, single platform
│   ├── iOS only → SwiftUI (iOS 16+) or UIKit (legacy)
│   └── Android only → Kotlin + Jetpack Compose
└── Existing codebase → match the codebase

---

Core Instincts

• Offline-first — assume the network will fail; design around it from day one
• Platform parity — iOS and Android behave differently; both must work
• Startup cost — every dependency adds to cold start time and binary size; justify each one
• UI/main thread is precious — heavy computation and animations must run off the main thread
• Battery budget — background tasks, location, and push use real energy; minimize wake-ups

---

Performance Thresholds

Metric	Target	Critical
Cold start time (JS bundle ready)	< 1s	> 2s
Time to interactive (first screen)	< 2s	> 4s
List scroll frame rate	60fps	< 45fps
IPA / APK download size	< 30MB	> 100MB
Memory usage (foreground)	< 150MB	> 300MB
JS bundle size (RN, gzipped)	< 1MB	> 3MB

---

❌ Anti-Patterns to Avoid

❌ NEVER DO	Why	✅ DO INSTEAD
ScrollView for long lists	Renders ALL items, memory explodes	FlatList / FlashList / ListView.builder
Inline renderItem function	New function every render, all items re-render	useCallback + React.memo on item component
Missing keyExtractor (or using index)	Reorder causes state/animation bugs	Use unique stable ID from data
useNativeDriver: false on animations	Animations run on JS thread, janky	useNativeDriver: true — GPU-only transforms
Token in AsyncStorage	Plaintext, exposed on rooted device	expo-secure-store / Keychain / EncryptedSharedPreferences
Business logic in UI components	Untestable, duplicated	Separate service/hook layer
Deep links as afterthought	Notifications and shares break	Plan linking config from day one
console.log in production build	Blocks JS thread, leaks data	Remove; use a proper logger with levels

---

Platform Reference

Element	iOS	Android
Min touch target	44pt × 44pt	48dp × 48dp
Min gap between targets	8pt	8dp
Back navigation	Edge swipe left	System back gesture / button
Status bar height	44–59pt (dynamic island)	24–28dp
Safe area insets	SafeAreaView / useSafeAreaInsets	WindowInsets
Primary font	SF Pro / SF Compact	Roboto / Noto
Icon set	SF Symbols	Material Symbols
Haptics	UIImpactFeedbackGenerator	VibrationEffect

---

Questions You Always Ask

When planning features:

• What happens when the user is offline or on 2G?
• What's the behavior on first install (no cached data, no permissions yet)?
• What happens when the app is backgrounded or killed mid-task?
• Have we tested on both iOS and Android, including on low-end devices?

When reviewing architecture:

• Does this increase cold start or JS bundle size? By how much?
• Are we handling permission denial AND revocation gracefully?
• What's the upgrade path for users with stale local data from an older version?
• Is this animation running on the UI thread or the JS thread?

---

Red Flags in Code Review

Must fix:

• No loading/error state for async operations
• Platform-specific logic hardcoded inline (use Platform.select or platform files)
• Animations not using native driver (or GPU-only properties)
• Sensitive data in AsyncStorage (tokens, PII)

Should fix:

• Deep links not wired into navigation config
• No permission denial / revocation handling
• Local storage schema changes without migration
• console.log present in production path

---

Thumb Zone (One-Handed Usage)

┌─────────────────────────┐
│    HARD TO REACH        │ ← nav bar, back, settings
│      (stretch)          │
├─────────────────────────┤
│    OK TO REACH          │ ← secondary actions
│     (natural)           │
├─────────────────────────┤
│    EASY TO REACH        │ ← primary CTA, tab bar
│  (thumb's natural arc)  │ ← main interaction zone
└─────────────────────────┘

Primary CTAs belong in the bottom 40% of the screen.

---

Platform References

When this skill is invoked, detect the project's platform stack and read the matching reference file(s) from references/ before proceeding:

Stack indicator	Reference file
package.json with react-native	references/react-native.md
pubspec.yaml	references/flutter.md
*.xcodeproj or Package.swift	references/ios-native.md
build.gradle.kts or build.gradle	references/android-native.md

If the project uses multiple stacks (e.g., React Native with native modules), read ALL matching references.

If no stack indicator is found, ask the user which platform they're targeting.

Granular Rules (React Native)

For React Native projects, references/react-native-rules/ contains 36 individual rule files from Vercel's agent-skills. Each rule covers one specific pattern with incorrect/correct code examples.

Read references/react-native-rules/_sections.md for the full index organized by priority (CRITICAL → LOW). Reference individual rules when working on specific areas (list performance, animation, UI patterns, etc.).

Granular Rules (Flutter/Dart)

For Flutter projects, references/flutter-rules/ contains 8 Dart skill files from kevmoo/dash_skills, covering Dart language best practices, modern features, testing patterns, and package maintenance.

Granular Rules (Android)

For Android projects, references/android-rules/ contains 17 skill files from awesome-android-agent-skills, covering: Clean Architecture, Compose UI/Performance/Navigation, ViewModel patterns, Retrofit networking, Kotlin Coroutines, Gradle optimization, testing, and XML-to-Compose migration.

Granular Rules (iOS/SwiftUI)

For iOS projects, references/ios-rules/ contains 19 SwiftUI reference files from AvdLee/SwiftUI-Agent-Skill, covering: state management, view composition, performance, animations (basics/advanced/transitions), navigation, Swift Charts, macOS support, Liquid Glass (iOS 26+), and accessibility.