Mobile Design

Mobile Design System

(Mobile-First · Touch-First · Platform-Respectful)

Philosophy: Touch-first. Battery-conscious. Platform-respectful. Offline-capable.

Core Law: Mobile is NOT a small desktop.

Operating Rule: Think constraints first, aesthetics second.

This skill exists to prevent desktop-thinking, AI-defaults, and unsafe assumptions when designing or building mobile applications.

---

1. Mobile Feasibility & Risk Index (MFRI)

Before designing or implementing any mobile feature or screen, assess feasibility.

MFRI Dimensions (1–5)

Score Formula

MFRI = (Platform Clarity + Accessibility Readiness)
       − (Interaction Complexity + Performance Risk + Offline Dependence)

Range: -10 → +10

Interpretation

---

2. Mandatory Thinking Before Any Work

⛔ STOP: Ask Before Assuming (Required)

If any of the following are not explicitly stated, you MUST ask before proceeding:

🚫 Never default to your favorite stack or pattern.

---

3. Mandatory Reference Reading (Enforced)

Universal (Always Read First)

Platform-Specific (Conditional)

❌ If you haven’t read the platform file, you are not allowed to design UI.

---

4. AI Mobile Anti-Patterns (Hard Bans)

🚫 Performance Sins (Non-Negotiable)

---

🚫 Touch & UX Sins

---

🚫 Security Sins

---

5. Platform Unification vs Divergence Matrix

UNIFY                          DIVERGE
──────────────────────────     ─────────────────────────
Business logic                Navigation behavior
Data models                    Gestures
API contracts                  Icons
Validation                     Typography
Error semantics                Pickers / dialogs

Platform Defaults

---

6. Mobile UX Psychology (Non-Optional)

Fitts’ Law (Touch Reality)

• Finger ≠ cursor
• Accuracy is low
• Reach matters more than precision

Rules:

• Primary CTAs live in thumb zone
• Destructive actions pushed away
• No hover assumptions

---

7. Performance Doctrine

React Native (Required Pattern)

const Row = React.memo(({ item }) => (
  <View><Text>{item.title}</Text></View>
));

const renderItem = useCallback(
  ({ item }) => <Row item={item} />,
  []
);

<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={(i) => i.id}
  getItemLayout={(_, i) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * i,
    index: i,
  })}
/>

Flutter (Required Pattern)

class Item extends StatelessWidget {
  const Item({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text('Static');
  }
}

• const everywhere possible
• Targeted rebuilds only

---

8. Mandatory Mobile Checkpoint

Before writing any code, you must complete this:

🧠 MOBILE CHECKPOINT

Platform:     ___________
Framework:    ___________
Files Read:   ___________

3 Principles I Will Apply:
1.
2.
3.

Anti-Patterns I Will Avoid:
1.
2.

❌ Cannot complete → go back and read.

---

9. Framework Decision Tree (Canonical)

Need OTA + web team → React Native + Expo
High-perf UI → Flutter
iOS only → SwiftUI
Android only → Compose

No debate without justification.

---

10. Release Readiness Checklist

Before Shipping

• [ ] Touch targets ≥ 44–48px
• [ ] Offline handled
• [ ] Secure storage used
• [ ] Lists optimized
• [ ] Logs stripped
• [ ] Tested on low-end devices
• [ ] Accessibility labels present
• [ ] MFRI ≥ 3

---

11. Related Skills

• frontend-design – Visual systems & components
• frontend-dev-guidelines – RN/TS architecture
• backend-dev-guidelines – Mobile-safe APIs
• error-tracking – Crash & performance telemetry

---

Final Law:

Mobile users are distracted, interrupted, and impatient—often using one hand on a bad network with low battery.

Design for that reality, or your app will fail quietly.

---

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Mobile Decision Trees

Framework selection, state management, storage strategy, and context-based decisions.

These are THINKING guides, not copy-paste answers.

---

1. Framework Selection

Master Decision Tree

WHAT ARE YOU BUILDING?
        │
        ├── Need OTA updates without app store review?
        │   │
        │   ├── Yes → React Native + Expo
        │   │         ├── Expo Go for development
        │   │         ├── EAS Update for production OTA
        │   │         └── Best for: rapid iteration, web teams
        │   │
        │   └── No → Continue ▼
        │
        ├── Need pixel-perfect custom UI across platforms?
        │   │
        │   ├── Yes → Flutter
        │   │         ├── Custom rendering engine
        │   │         ├── Single UI for iOS + Android
        │   │         └── Best for: branded, visual apps
        │   │
        │   └── No → Continue ▼
        │
        ├── Heavy native features (ARKit, HealthKit, specific sensors)?
        │   │
        │   ├── iOS only → SwiftUI / UIKit
        │   │              └── Maximum native capability
        │   │
        │   ├── Android only → Kotlin + Jetpack Compose
        │   │                  └── Maximum native capability
        │   │
        │   └── Both → Consider native with shared logic
        │              └── Kotlin Multiplatform for shared
        │
        ├── Existing web team + TypeScript codebase?
        │   │
        │   └── Yes → React Native
        │             ├── Familiar paradigm for React devs
        │             ├── Share code with web (limited)
        │             └── Large ecosystem
        │
        └── Enterprise with existing Flutter team?
            │
            └── Yes → Flutter
                      └── Leverage existing expertise

Framework Comparison

When to Choose Native

CHOOSE NATIVE WHEN:
├── Maximum performance required (games, 3D)
├── Deep OS integration needed
├── Platform-specific features are core
├── Team has native expertise
├── App store presence is primary
└── Long-term maintenance priority

AVOID NATIVE WHEN:
├── Limited budget/time
├── Need rapid iteration
├── Identical UI on both platforms
├── Team is web-focused
└── Cross-platform is priority

---

2. State Management Selection

React Native State Decision

WHAT'S YOUR STATE COMPLEXITY?
        │
        ├── Simple app, few screens, minimal shared state
        │   │
        │   └── Zustand (or just useState/Context)
        │       ├── Minimal boilerplate
        │       ├── Easy to understand
        │       └── Scales OK to medium
        │
        ├── Primarily server data (API-driven)
        │   │
        │   └── TanStack Query (React Query) + Zustand
        │       ├── Query for server state
        │       ├── Zustand for UI state
        │       └── Excellent caching, refetching
        │
        ├── Complex app with many features
        │   │
        │   └── Redux Toolkit + RTK Query
        │       ├── Predicable, debuggable
        │       ├── RTK Query for API
        │       └── Good for large teams
        │
        └── Atomic, granular state needs
            │
            └── Jotai
                ├── Atom-based (like Recoil)
                ├── Minimizes re-renders
                └── Good for derived state

Flutter State Decision

WHAT'S YOUR STATE COMPLEXITY?
        │
        ├── Simple app, learning Flutter
        │   │
        │   └── Provider (or setState)
        │       ├── Official, simple
        │       ├── Built into Flutter
        │       └── Good for small apps
        │
        ├── Modern, type-safe, testable
        │   │
        │   └── Riverpod 2.0
        │       ├── Compile-time safety
        │       ├── Code generation
        │       ├── Excellent for medium-large apps
        │       └── Recommended for new projects
        │
        ├── Enterprise, strict patterns needed
        │   │
        │   └── BLoC
        │       ├── Event → State pattern
        │       ├── Very testable
        │       ├── More boilerplate
        │       └── Good for large teams
        │
        └── Quick prototyping
            │
            └── GetX (with caution)
                ├── Fast to implement
                ├── Less strict patterns
                └── Can become messy at scale

State Management Anti-Patterns

❌ DON'T:
├── Use global state for everything
├── Mix state management approaches
├── Store server state in local state
├── Skip state normalization
├── Overuse Context (re-render heavy)
└── Put navigation state in app state

✅ DO:
├── Server state → Query library
├── UI state → Minimal, local first
├── Lift state only when needed
├── Choose ONE approach per project
└── Keep state close to where it's used

---

3. Navigation Pattern Selection

HOW MANY TOP-LEVEL DESTINATIONS?
        │
        ├── 2 destinations
        │   └── Consider: Top tabs or simple stack
        │
        ├── 3-5 destinations (equal importance)
        │   └── ✅ Tab Bar / Bottom Navigation
        │       ├── Most common pattern
        │       └── Easy discovery
        │
        ├── 5+ destinations
        │   │
        │   ├── All important → Drawer Navigation
        │   │                   └── Hidden but many options
        │   │
        │   └── Some less important → Tab bar + drawer hybrid
        │
        └── Single linear flow?
            └── Stack Navigation only
                └── Onboarding, checkout, etc.

Navigation by App Type

---

4. Storage Strategy Selection

WHAT TYPE OF DATA?
        │
        ├── Sensitive (tokens, passwords, keys)
        │   │
        │   └── ✅ Secure Storage
        │       ├── iOS: Keychain
        │       ├── Android: EncryptedSharedPreferences
        │       └── RN: expo-secure-store / react-native-keychain
        │
        ├── User preferences (settings, theme)
        │   │
        │   └── ✅ Key-Value Storage
        │       ├── iOS: UserDefaults
        │       ├── Android: SharedPreferences
        │       └── RN: AsyncStorage / MMKV
        │
        ├── Structured data (entities, relationships)
        │   │
        │   └── ✅ Database
        │       ├── SQLite (expo-sqlite, sqflite)
        │       ├── Realm (NoSQL, reactive)
        │       └── WatermelonDB (large datasets)
        │
        ├── Large files (images, documents)
        │   │
        │   └── ✅ File System
        │       ├── iOS: Documents / Caches directory
        │       ├── Android: Internal/External storage
        │       └── RN: react-native-fs / expo-file-system
        │
        └── Cached API data
            │
            └── ✅ Query Library Cache
                ├── TanStack Query (RN)
                ├── Riverpod async (Flutter)
                └── Automatic invalidation

Storage Comparison

---

5. Offline Strategy Selection

HOW CRITICAL IS OFFLINE?
        │
        ├── Nice to have (works when possible)
        │   │
        │   └── Cache last data + show stale
        │       ├── Simple implementation
        │       ├── TanStack Query with staleTime
        │       └── Show "last updated" timestamp
        │
        ├── Essential (core functionality offline)
        │   │
        │   └── Offline-first architecture
        │       ├── Local database as source of truth
        │       ├── Sync to server when online
        │       ├── Conflict resolution strategy
        │       └── Queue actions for later sync
        │
        └── Real-time critical (collaboration, chat)
            │
            └── WebSocket + local queue
                ├── Optimistic updates
                ├── Eventual consistency
                └── Complex conflict handling

Offline Implementation Patterns

1. CACHE-FIRST (Simple)
   Request → Check cache → If stale, fetch → Update cache
   
2. STALE-WHILE-REVALIDATE
   Request → Return cached → Fetch update → Update UI
   
3. OFFLINE-FIRST (Complex)
   Action → Write to local DB → Queue sync → Sync when online
   
4. SYNC ENGINE
   Use: Firebase, Realm Sync, Supabase realtime
   Handles conflict resolution automatically

---

6. Authentication Pattern Selection

WHAT AUTH TYPE NEEDED?
        │
        ├── Simple email/password
        │   │
        │   └── Token-based (JWT)
        │       ├── Store refresh token securely
        │       ├── Access token in memory
        │       └── Silent refresh flow
        │
        ├── Social login (Google, Apple, etc.)
        │   │
        │   └── OAuth 2.0 + PKCE
        │       ├── Use platform SDKs
        │       ├── Deep link callback
        │       └── Apple Sign-In required for iOS
        │
        ├── Enterprise/SSO
        │   │
        │   └── OIDC / SAML
        │       ├── Web view or system browser
        │       └── Handle redirect properly
        │
        └── Biometric (FaceID, fingerprint)
            │
            └── Local auth + secure token
                ├── Biometrics unlock stored token
                ├── Not a replacement for server auth
                └── Fallback to PIN/password

Auth Token Storage

❌ NEVER store tokens in:
├── AsyncStorage (plain text)
├── Redux/state (not persisted correctly)
├── Local storage equivalent
└── Logs or debug output

✅ ALWAYS store tokens in:
├── iOS: Keychain
├── Android: EncryptedSharedPreferences
├── Expo: SecureStore
├── Biometric-protected if available

---

7. Project Type Templates

E-Commerce App

RECOMMENDED STACK:
├── Framework: React Native + Expo (OTA for pricing)
├── Navigation: Tab bar (Home, Search, Cart, Account)
├── State: TanStack Query (products) + Zustand (cart)
├── Storage: SecureStore (auth) + SQLite (cart cache)
├── Offline: Cache products, queue cart actions
└── Auth: Email/password + Social + Apple Pay

KEY DECISIONS:
├── Product images: Lazy load, cache aggressively
├── Cart: Sync across devices via API
├── Checkout: Secure, minimal steps
└── Deep links: Product shares, marketing

Social/Content App

RECOMMENDED STACK:
├── Framework: React Native or Flutter
├── Navigation: Tab bar (Feed, Search, Create, Notifications, Profile)
├── State: TanStack Query (feed) + Zustand (UI)
├── Storage: SQLite (feed cache, drafts)
├── Offline: Cache feed, queue posts
└── Auth: Social login primary, Apple required

KEY DECISIONS:
├── Feed: Infinite scroll, memoized items
├── Media: Upload queuing, background upload
├── Push: Deep link to content
└── Real-time: WebSocket for notifications

Productivity/SaaS App

RECOMMENDED STACK:
├── Framework: Flutter (consistent UI) or RN
├── Navigation: Drawer or Tab bar
├── State: Riverpod/BLoC or Redux Toolkit
├── Storage: SQLite (offline), SecureStore (auth)
├── Offline: Full offline editing, sync
└── Auth: SSO/OIDC for enterprise

KEY DECISIONS:
├── Data sync: Conflict resolution strategy
├── Collaborative: Real-time or eventual?
├── Files: Large file handling
└── Enterprise: MDM, compliance

---

8. Decision Checklist

Before Starting ANY Project

• [ ] Target platforms defined (iOS/Android/both)?
• [ ] Framework selected based on criteria?
• [ ] State management approach chosen?
• [ ] Navigation pattern selected?
• [ ] Storage strategy for each data type?
• [ ] Offline requirements defined?
• [ ] Auth flow designed?
• [ ] Deep linking planned from start?

Questions to Ask User

If project details are vague, ASK:

1. "Will this need OTA updates without app store review?"
   → Affects framework choice (Expo = yes)

2. "Do iOS and Android need identical UI?"
   → Affects framework (Flutter = identical)

3. "What's the offline requirement?"
   → Affects architecture complexity

4. "Is there an existing backend/auth system?"
   → Affects auth and API approach

5. "What devices? Phone only, or tablet?"
   → Affects navigation and layout

6. "Enterprise or consumer?"
   → Affects auth (SSO), security, compliance

---

9. Anti-Pattern Decisions

❌ Decision Anti-Patterns

---

10. Quick Reference

Framework Quick Pick

OTA needed?           → React Native + Expo
Identical UI?         → Flutter
Maximum performance?  → Native
Web team?            → React Native
Quick prototype?     → Expo

State Quick Pick

Simple app?          → Zustand / Provider
Server-heavy?        → TanStack Query / Riverpod
Enterprise?          → Redux / BLoC
Atomic state?        → Jotai

Storage Quick Pick

Secrets?             → SecureStore / Keychain
Settings?            → AsyncStorage / UserDefaults
Structured data?     → SQLite
API cache?           → Query library

---

Remember: These trees are guides for THINKING, not rules to follow blindly. Every project has unique constraints. ASK clarifying questions when requirements are vague, and choose based on actual needs, not defaults.

Mobile Backend Patterns

This file covers backend/API patterns SPECIFIC to mobile clients.

Generic backend patterns are in nodejs-best-practices and api-patterns.

Mobile backend is NOT the same as web backend. Different constraints, different patterns.

---

🧠 MOBILE BACKEND MINDSET

Mobile clients are DIFFERENT from web clients:
├── Unreliable network (2G, subway, elevator)
├── Battery constraints (minimize wake-ups)
├── Limited storage (can't cache everything)
├── Interrupted sessions (calls, notifications)
├── Diverse devices (old phones to flagships)
└── Binary updates are slow (App Store review)

Your backend must compensate for ALL of these.

---

🚫 AI MOBILE BACKEND ANTI-PATTERNS

These are common AI mistakes when building mobile backends:

---

1. Push Notifications

Platform Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    YOUR BACKEND                                  │
├─────────────────────────────────────────────────────────────────┤
│                         │                                        │
│              ┌──────────┴──────────┐                            │
│              ▼                     ▼                            │
│    ┌─────────────────┐   ┌─────────────────┐                    │
│    │   FCM (Google)  │   │  APNs (Apple)   │                    │
│    │   Firebase      │   │  Direct or FCM  │                    │
│    └────────┬────────┘   └────────┬────────┘                    │
│             │                     │                              │
│             ▼                     ▼                              │
│    ┌─────────────────┐   ┌─────────────────┐                    │
│    │ Android Device  │   │   iOS Device    │                    │
│    └─────────────────┘   └─────────────────┘                    │
└─────────────────────────────────────────────────────────────────┘

Push Types

Anti-Patterns

Token Management

TOKEN LIFECYCLE:
├── App registers → Get token → Send to backend
├── Token can change → App must re-register on start
├── Token expires → Clean from database
├── User uninstalls → Token becomes invalid (detect via error)
└── Multiple devices → Store multiple tokens per user

---

2. Offline Sync & Conflict Resolution

Sync Strategy Selection

WHAT TYPE OF DATA?
        │
        ├── Read-only (news, catalog)
        │   └── Simple cache + TTL
        │       └── ETag/Last-Modified for invalidation
        │
        ├── User-owned (notes, todos)
        │   └── Last-write-wins (simple)
        │       └── Or timestamp-based merge
        │
        ├── Collaborative (shared docs)
        │   └── CRDT or OT required
        │       └── Consider Firebase/Supabase
        │
        └── Critical (payments, inventory)
            └── Server is source of truth
                └── Optimistic UI + server confirmation

Conflict Resolution Strategies

Sync Queue Pattern

CLIENT SIDE:
├── User makes change → Write to local DB
├── Add to sync queue → { action, data, timestamp, retries }
├── Network available → Process queue FIFO
├── Success → Remove from queue
├── Failure → Retry with backoff (max 5 retries)
└── Conflict → Apply resolution strategy

SERVER SIDE:
├── Accept change with client timestamp
├── Compare with server version
├── Apply conflict resolution
├── Return merged state
└── Client updates local with server response

---

3. Mobile API Optimization

Response Size Reduction

Pagination: Cursor vs Offset

OFFSET (Bad for mobile):
├── Page 1: OFFSET 0 LIMIT 20
├── Page 2: OFFSET 20 LIMIT 20
├── Problem: New item added → duplicates!
└── Problem: Large offset = slow query

CURSOR (Good for mobile):
├── First: ?limit=20
├── Next: ?limit=20&after=cursor_abc123
├── Cursor = encoded (id + sort values)
├── No duplicates on data changes
└── Consistent performance

Batch Requests

Instead of:
GET /users/1
GET /users/2  
GET /users/3
(3 round trips, 3x latency)

Use:
POST /batch
{ requests: [
    { method: "GET", path: "/users/1" },
    { method: "GET", path: "/users/2" },
    { method: "GET", path: "/users/3" }
]}
(1 round trip)

---

4. App Versioning

Version Check Endpoint

GET /api/app-config
Headers:
  X-App-Version: 2.1.0
  X-Platform: ios
  X-Device-ID: abc123

Response:
{
  "minimum_version": "2.0.0",
  "latest_version": "2.3.0",
  "force_update": false,
  "update_url": "https://apps.apple.com/...",
  "feature_flags": {
    "new_player": true,
    "dark_mode": true
  },
  "maintenance": false,
  "maintenance_message": null
}

Version Comparison Logic

CLIENT VERSION vs MINIMUM VERSION:
├── client >= minimum → Continue normally
├── client < minimum → Show force update screen
│   └── Block app usage until updated
└── client < latest → Show optional update prompt

FEATURE FLAGS:
├── Enable/disable features without app update
├── A/B testing by version/device
└── Gradual rollout (10% → 50% → 100%)

---

5. Authentication for Mobile

Token Strategy

ACCESS TOKEN:
├── Short-lived (15 min - 1 hour)
├── Stored in memory (not persistent)
├── Used for API requests
└── Refresh when expired

REFRESH TOKEN:
├── Long-lived (30-90 days)
├── Stored in SecureStore/Keychain
├── Used only to get new access token
└── Rotate on each use (security)

DEVICE TOKEN:
├── Identifies this device
├── Allows "log out all devices"
├── Stored alongside refresh token
└── Server tracks active devices

Silent Re-authentication

REQUEST FLOW:
├── Make request with access token
├── 401 Unauthorized?
│   ├── Have refresh token?
│   │   ├── Yes → Call /auth/refresh
│   │   │   ├── Success → Retry original request
│   │   │   └── Failure → Force logout
│   │   └── No → Force logout
│   └── Token just expired (not invalid)
│       └── Auto-refresh, user doesn't notice
└── Success → Continue

---

6. Error Handling for Mobile

Mobile-Specific Error Format

{
  "error": {
    "code": "PAYMENT_DECLINED",
    "message": "Your payment was declined",
    "user_message": "Please check your card details or try another payment method",
    "action": {
      "type": "navigate",
      "destination": "payment_methods"
    },
    "retry": {
      "allowed": true,
      "after_seconds": 5
    }
  }
}

Error Categories

---

7. Media & Binary Handling

Image Optimization

CLIENT REQUEST:
GET /images/{id}?w=400&h=300&q=80&format=webp

SERVER RESPONSE:
├── Resize on-the-fly OR use CDN
├── WebP for Android (smaller)
├── HEIC for iOS 14+ (if supported)
├── JPEG fallback
└── Cache-Control: max-age=31536000

Chunked Upload (Large Files)

UPLOAD FLOW:
1. POST /uploads/init
   { filename, size, mime_type }
   → { upload_id, chunk_size }

2. PUT /uploads/{upload_id}/chunks/{n}
   → Upload each chunk (1-5 MB)
   → Can resume if interrupted

3. POST /uploads/{upload_id}/complete
   → Server assembles chunks
   → Return final file URL

Streaming Audio/Video

REQUIREMENTS:
├── HLS (HTTP Live Streaming) for iOS
├── DASH or HLS for Android
├── Multiple quality levels (adaptive bitrate)
├── Range request support (seeking)
└── Offline download chunks

ENDPOINTS:
GET /media/{id}/manifest.m3u8  → HLS manifest
GET /media/{id}/segment_{n}.ts → Video segment
GET /media/{id}/download       → Full file for offline

---

8. Security for Mobile

Device Attestation

VERIFY REAL DEVICE (not emulator/bot):
├── iOS: DeviceCheck API
│   └── Server verifies with Apple
├── Android: Play Integrity API (replaces SafetyNet)
│   └── Server verifies with Google
└── Fail closed: Reject if attestation fails

Request Signing

CLIENT:
├── Create signature = HMAC(timestamp + path + body, secret)
├── Send: X-Signature: {signature}
├── Send: X-Timestamp: {timestamp}
└── Send: X-Device-ID: {device_id}

SERVER:
├── Validate timestamp (within 5 minutes)
├── Recreate signature with same inputs
├── Compare signatures
└── Reject if mismatch (tampering detected)

Rate Limiting

MOBILE-SPECIFIC LIMITS:
├── Per device (X-Device-ID)
├── Per user (after auth)
├── Per endpoint (stricter for sensitive)
└── Sliding window preferred

HEADERS:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
Retry-After: 60 (when 429)

---

9. Monitoring & Analytics

Required Headers from Mobile

Every mobile request should include:
├── X-App-Version: 2.1.0
├── X-Platform: ios | android
├── X-OS-Version: 17.0
├── X-Device-Model: iPhone15,2
├── X-Device-ID: uuid (persistent)
├── X-Request-ID: uuid (per request, for tracing)
├── Accept-Language: tr-TR
└── X-Timezone: Europe/Istanbul

What to Log

FOR EACH REQUEST:
├── All headers above
├── Endpoint, method, status
├── Response time
├── Error details (if any)
└── User ID (if authenticated)

ALERTS:
├── Error rate > 5% per version
├── P95 latency > 2 seconds
├── Specific version crash spike
├── Auth failure spike (attack?)
└── Push delivery failure spike

---

📝 MOBILE BACKEND CHECKLIST

Before API Design

• [ ] Identified mobile-specific requirements?
• [ ] Planned offline behavior?
• [ ] Designed sync strategy?
• [ ] Considered bandwidth constraints?

For Every Endpoint

• [ ] Response as small as possible?
• [ ] Pagination cursor-based?
• [ ] Proper caching headers?
• [ ] Mobile error format with actions?

Authentication

• [ ] Token refresh implemented?
• [ ] Silent re-auth flow?
• [ ] Multi-device logout?
• [ ] Secure token storage guidance?

Push Notifications

• [ ] FCM + APNs configured?
• [ ] Token lifecycle managed?
• [ ] Silent vs display push defined?
• [ ] Sensitive data NOT in push payload?

Release

• [ ] Version check endpoint ready?
• [ ] Feature flags configured?
• [ ] Force update mechanism?
• [ ] Monitoring headers required?

---

Remember: Mobile backend must be resilient to bad networks, respect battery life, and handle interrupted sessions gracefully. The client cannot be trusted, but it also cannot be hung up—provide offline capabilities and clear error recovery paths.

Mobile Color System Reference

OLED optimization, dark mode, battery-aware colors, and outdoor visibility.

Color on mobile isn't just aesthetics—it's battery life and usability.

---

1. Mobile Color Fundamentals

Why Mobile Color is Different

DESKTOP:                           MOBILE:
├── LCD screens (backlit)          ├── OLED common (self-emissive)
├── Controlled lighting            ├── Outdoor, bright sun
├── Stable power                   ├── Battery matters
├── Personal preference            ├── System-wide dark mode
└── Static viewing                 └── Variable angles, motion

Mobile Color Priorities

---

2. OLED Considerations

How OLED Differs

LCD (Liquid Crystal Display):
├── Backlight always on
├── Black = backlight through dark filter
├── Energy use = constant
└── Dark mode = no battery savings

OLED (Organic LED):
├── Each pixel emits own light
├── Black = pixel OFF (zero power)
├── Energy use = brighter pixels use more
└── Dark mode = significant battery savings

Battery Savings with OLED

Color energy consumption (relative):

#000000 (True Black)  ████░░░░░░  0%
#1A1A1A (Near Black)  █████░░░░░  ~15%
#333333 (Dark Gray)   ██████░░░░  ~30%
#666666 (Medium Gray) ███████░░░  ~50%
#FFFFFF (White)       ██████████  100%

Saturated colors also use significant power:
├── Blue pixels: Most efficient
├── Green pixels: Medium
├── Red pixels: Least efficient
└── Desaturated colors save more

True Black vs Near Black

#000000 (True Black):
├── Maximum battery savings
├── Can cause "black smear" on scroll
├── Sharp contrast (may be harsh)
└── Used by Apple in pure dark mode

#121212 or #1A1A1A (Near Black):
├── Still good battery savings
├── Smoother scrolling (no smear)
├── Slightly softer on eyes
└── Material Design recommendation

RECOMMENDATION: #000000 for backgrounds, #0D0D0D-#1A1A1A for surfaces

---

3. Dark Mode Design

Dark Mode Benefits

Users enable dark mode for:
├── Battery savings (OLED)
├── Reduced eye strain (low light)
├── Personal preference
├── AMOLED aesthetic
└── Accessibility (light sensitivity)

Dark Mode Color Strategy

LIGHT MODE                      DARK MODE
──────────                      ─────────
Background: #FFFFFF      →      #000000 or #121212
Surface:    #F5F5F5      →      #1E1E1E
Surface 2:  #EEEEEE      →      #2C2C2C

Primary:    #1976D2      →      #90CAF9 (lighter)
Text:       #212121      →      #E0E0E0 (not pure white)
Secondary:  #757575      →      #9E9E9E

Elevation in dark mode:
├── Higher = slightly lighter surface
├── 0dp →  0% overlay
├── 4dp →  9% overlay
├── 8dp →  12% overlay
└── Creates depth without shadows

Text Colors in Dark Mode

Color Inversion Rules

DON'T just invert colors:
├── Saturated colors become eye-burning
├── Semantic colors lose meaning
├── Brand colors may break
└── Contrast ratios change unpredictably

DO create intentional dark palette:
├── Desaturate primary colors
├── Use lighter tints for emphasis
├── Maintain semantic color meanings
├── Check contrast ratios independently

---

4. Outdoor Visibility

The Sunlight Problem

Screen visibility outdoors:
├── Bright sun washes out low contrast
├── Glare reduces readability
├── Polarized sunglasses affect
└── Users shield screen with hand

Affected elements:
├── Light gray text on white
├── Subtle color differences
├── Low opacity overlays
└── Pastel colors

High Contrast Strategies

For outdoor visibility:

MINIMUM CONTRAST RATIOS:
├── Normal text: 4.5:1 (WCAG AA)
├── Large text: 3:1 (WCAG AA)
├── Recommended: 7:1+ (AAA)

AVOID:
├── #999 on #FFF (fails AA)
├── #BBB on #FFF (fails)
├── Pale colors on light backgrounds
└── Subtle gradients for critical info

DO:
├── Use system semantic colors
├── Test in bright environment
├── Provide high contrast mode
└── Use solid colors for critical UI

---

5. Semantic Colors

Consistent Meaning

Semantic Color Rules

NEVER use semantic colors for:
├── Branding (confuses meaning)
├── Decoration (reduces impact)
├── Arbitrary styling
└── Status indicators (use icons too)

ALWAYS:
├── Pair with icons (colorblind users)
├── Maintain across light/dark modes
├── Keep consistent throughout app
└── Follow platform conventions

Error State Colors

Error states need:
├── Red-ish color (semantic)
├── High contrast against background
├── Icon reinforcement
├── Clear text explanation

iOS:
├── Light: #FF3B30
├── Dark: #FF453A

Android:
├── Light: #B3261E
├── Dark: #F2B8B5 (on error container)

---

6. Dynamic Color (Android)

Material You

Android 12+ Dynamic Color:

User's wallpaper → Color extraction → App theme

Your app automatically gets:
├── Primary (from wallpaper dominant)
├── Secondary (complementary)
├── Tertiary (accent)
├── Surface colors (neutral, derived)
├── On-colors (text on each)

Supporting Dynamic Color

// Jetpack Compose
MaterialTheme(
    colorScheme = dynamicColorScheme()
        ?: staticColorScheme() // Fallback for older Android
)

// React Native
// Limited support - consider react-native-material-you

Fallback Colors

When dynamic color unavailable:
├── Android < 12
├── User disabled
├── Non-supporting launchers

Provide static color scheme:
├── Define your brand colors
├── Test in both modes
├── Match dynamic color roles
└── Support light + dark

---

7. Color Accessibility

Colorblind Considerations

~8% of men, ~0.5% of women are colorblind

Types:
├── Protanopia (red weakness)
├── Deuteranopia (green weakness)
├── Tritanopia (blue weakness)
├── Monochromacy (rare, no color)

Design rules:
├── Never rely on color alone
├── Use patterns, icons, text
├── Test with simulation tools
├── Avoid red/green distinctions only

Contrast Testing Tools

Use these to verify:
├── Built-in accessibility inspector (Xcode)
├── Accessibility Scanner (Android)
├── Contrast ratio calculators
├── Colorblind simulation
└── Test on actual devices in sunlight

Sufficient Contrast

WCAG Guidelines:

AA (Minimum)
├── Normal text: 4.5:1
├── Large text (18pt+): 3:1
├── UI components: 3:1

AAA (Enhanced)
├── Normal text: 7:1
├── Large text: 4.5:1

Mobile recommendation: Meet AA, aim for AAA

---

8. Color Anti-Patterns

❌ Common Mistakes

❌ AI Color Mistakes

AI tends to:
├── Use same colors for light/dark
├── Ignore OLED battery implications
├── Skip contrast calculations
├── Default to purple/violet (BANNED)
├── Use low contrast "aesthetic" grays
├── Not test in outdoor conditions
└── Forget colorblind users

RULE: Design for the worst case.
Test in bright sunlight, with colorblindness simulation.

---

9. Color System Checklist

Before Choosing Colors

• [ ] Light and dark mode variants defined?
• [ ] Contrast ratios checked (4.5:1+)?
• [ ] OLED battery considered (dark mode)?
• [ ] Semantic colors follow conventions?
• [ ] Colorblind-safe (not color-only indicators)?

Before Release

• [ ] Tested in bright sunlight?
• [ ] Tested dark mode on OLED device?
• [ ] System dark mode respected?
• [ ] Dynamic color supported (Android)?
• [ ] Error/success/warning consistent?
• [ ] All text meets contrast requirements?

---

10. Quick Reference

Dark Mode Backgrounds

True black (OLED max savings): #000000
Near black (Material):         #121212
Surface 1:                     #1E1E1E
Surface 2:                     #2C2C2C
Surface 3:                     #3C3C3C

Text on Dark

Primary:   #E0E0E0 to #ECECEC
Secondary: #A0A0A0 to #B0B0B0
Disabled:  #606060 to #707070

Contrast Ratios

Small text:  4.5:1 (minimum)
Large text:  3:1 (minimum)
UI elements: 3:1 (minimum)
Ideal:       7:1 (AAA)

---

Remember: Color on mobile must work in the worst conditions—bright sun, tired eyes, colorblindness, low battery. Pretty colors that fail these tests are useless colors.

Mobile Debugging Guide

Stop console.log() debugging!

Mobile apps have complex native layers. Text logs are not enough.

This file teaches effective mobile debugging strategies.

---

🧠 MOBILE DEBUGGING MINDSET

Web Debugging:      Mobile Debugging:
┌──────────────┐    ┌──────────────┐
│  Browser     │    │  JS Bridge   │
│  DevTools    │    │  Native UI   │
│  Network Tab │    │  GPU/Memory  │
└──────────────┘    │  Threads     │
                    └──────────────┘

Key Differences: 1. Native Layer: JS code works, but app crashes? It's likely native (Java/Obj-C). 2. Deployment: You can't just "refresh". State gets lost or stuck. 3. Network: SSL Pinning, proxy settings are harder. 4. Device Logs: adb logcat and Console.app are your truth.

---

🚫 AI DEBUGGING ANTI-PATTERNS

---

1. The Toolset

⚡ React Native & Expo

🛠️ Native Layer (The Deep Dive)

---

2. Common Debugging Workflows

🕵️ "The App Just Crashed" (Red Screen vs Crash to Home)

Scenario A: Red Screen (JS Error)

• Cause: Undefined is not an object, import error.
• Fix: Read the stack trace on screen. It's usually clear.

Scenario B: Crash to Home Screen (Native Crash)

• Cause: Native module failure, memory OOM, permission usage without declaration.
• Tools:
• Android: adb logcat *:E (Filter for Errors)
• iOS: Open Xcode → Window → Devices → View Device Logs

💡 Pro Tip: If app crashes immediately on launch, it's almost 100% a native configuration issue (Info.plist, AndroidManifest.xml).

🌐 "API Request Failed" (Network)

Web: Open Chrome DevTools → Network. Mobile: You usually can't see this easily.

Solution 1: Reactotron/Flipper

• View network requests in the monitoring app.

Solution 2: Proxy (Charles/Proxyman)

• Hard but powerful. See ALL traffic even from native SDKs.
• Requires installing SSL cert on device.

🐢 "The UI is Laggy" (Performance)

Don't guess. measure.

• React Native: Performance Monitor (Shake menu).
• Android: "Profile GPU Rendering" in Developer Options.
• Issues:
• JS FPS drop: Heavy calculation in JS thread.
• UI FPS drop: Too many views, intricate hierarchy, heavy images.

---

3. Platform-Specific Nightmares

Android

• Gradle Sync Fail: Usually Java version mismatch or duplicate classes.
• Emulator Network: Emulator localhost is 10.0.2.2, NOT 127.0.0.1.
• Cached Builds: ./gradlew clean is your best friend.

iOS

• Pod Issues: pod deintegrate && pod install.
• Signing Errors: Check Team ID and Bundle Identifier.
• Cache: Xcode → Product → Clean Build Folder.

---

📝 DEBUGGING CHECKLIST

• [ ] Is it a JS or Native crash? (Red screen or home screen?)
• [ ] Did you clean build? (Native caches are aggressive)
• [ ] Are you on a real device? (Simulators hide concurrency bugs)
• [ ] Did you check the native logs? (Not just terminal output)

Remember: If JavaScript looks perfect but the app fails, look closer at the Native side.

Mobile Design Thinking

This file prevents AI from using memorized patterns and forces genuine thinking.

Mechanisms to prevent standard AI training defaults in mobile development.

The mobile equivalent of frontend's layout decomposition approach.

---

🧠 DEEP MOBILE THINKING PROTOCOL

This Process is Mandatory Before Every Mobile Project

┌─────────────────────────────────────────────────────────────────┐
│                    DEEP MOBILE THINKING                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1️⃣ CONTEXT SCAN                                               │
│     └── What are my assumptions for this project?               │
│         └── QUESTION these assumptions                          │
│                                                                 │
│  2️⃣ ANTI-DEFAULT ANALYSIS                                      │
│     └── Am I applying a memorized pattern?                      │
│         └── Is this pattern REALLY the best for THIS project?   │
│                                                                 │
│  3️⃣ PLATFORM DECOMPOSITION                                     │
│     └── Did I think about iOS and Android separately?           │
│         └── What are the platform-specific patterns?            │
│                                                                 │
│  4️⃣ TOUCH INTERACTION BREAKDOWN                                │
│     └── Did I analyze each interaction individually?            │
│         └── Did I apply Fitts' Law, Thumb Zone?                 │
│                                                                 │
│  5️⃣ PERFORMANCE IMPACT ANALYSIS                                │
│     └── Did I consider performance impact of each component?    │
│         └── Is the default solution performant?                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

🚫 AI MOBILE DEFAULTS (FORBIDDEN LIST)

Using These Patterns Automatically is FORBIDDEN!

The following patterns are "defaults" that AIs learned from training data. Before using any of these, QUESTION them and CONSIDER ALTERNATIVES!

┌─────────────────────────────────────────────────────────────────┐
│                 🚫 AI MOBILE SAFE HARBOR                        │
│           (Default Patterns - Never Use Without Questioning)    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  NAVIGATION DEFAULTS:                                           │
│  ├── Tab bar for every project (Would drawer be better?)        │
│  ├── Fixed 5 tabs (Are 3 enough? For 6+, drawer?)               │
│  ├── "Home" tab on left (What does user behavior say?)          │
│  └── Hamburger menu (Is it outdated now?)                       │
│                                                                 │
│  STATE MANAGEMENT DEFAULTS:                                     │
│  ├── Redux everywhere (Is Zustand/Jotai sufficient?)            │
│  ├── Global state for everything (Isn't local state enough?)   │
│  ├── Context Provider hell (Is atom-based better?)              │
│  └── BLoC for every Flutter project (Is Riverpod more modern?)  │
│                                                                 │
│  LIST IMPLEMENTATION DEFAULTS:                                  │
│  ├── FlatList as default (Is FlashList more performant?)        │
│  ├── windowSize=21 (Is it really needed?)                       │
│  ├── removeClippedSubviews (Always?)                            │
│  └── ListView.builder (Is ListView.separated better?)           │
│                                                                 │
│  UI PATTERN DEFAULTS:                                           │
│  ├── FAB bottom-right (Is bottom-left more accessible?)         │
│  ├── Pull-to-refresh on every list (Is it needed everywhere?)   │
│  ├── Swipe-to-delete from left (Is right better?)               │
│  └── Bottom sheet for every modal (Is full screen better?)      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

🔍 COMPONENT DECOMPOSITION (MANDATORY)

Decomposition Analysis for Every Screen

Before designing any screen, perform this analysis:

SCREEN: [Screen Name]
├── PRIMARY ACTION: [What is the main action?]
│   └── Is it in thumb zone? [Yes/No → Why?]
│
├── TOUCH TARGETS: [All tappable elements]
│   ├── [Element 1]: [Size]pt → Sufficient?
│   ├── [Element 2]: [Size]pt → Sufficient?
│   └── Spacing: [Gap]pt → Accidental tap risk?
│
├── SCROLLABLE CONTENT:
│   ├── Is it a list? → FlatList/FlashList [Why this choice?]
│   ├── Item count: ~[N] → Performance consideration?
│   └── Fixed height? → Is getItemLayout needed?
│
├── STATE REQUIREMENTS:
│   ├── Is local state sufficient?
│   ├── Do I need to lift state?
│   └── Is global required? [Why?]
│
├── PLATFORM DIFFERENCES:
│   ├── iOS: [Anything different needed?]
│   └── Android: [Anything different needed?]
│
├── OFFLINE CONSIDERATION:
│   ├── Should this screen work offline?
│   └── Cache strategy: [Yes/No/Which one?]
│
└── PERFORMANCE IMPACT:
    ├── Any heavy components?
    ├── Is memoization needed?
    └── Animation performance?

---

🎯 PATTERN QUESTIONING MATRIX

Ask these questions for every default pattern:

Navigation Pattern Questioning

State Pattern Questioning

List Pattern Questioning

UI Pattern Questioning

---

🧪 ANTI-MEMORIZATION TEST

Ask Yourself Before Every Solution

┌─────────────────────────────────────────────────────────────────┐
│                    ANTI-MEMORIZATION CHECKLIST                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  □ Did I pick this solution "because I always do it this way"?  │
│    → If YES: STOP. Consider alternatives.                       │
│                                                                 │
│  □ Is this a pattern I've seen frequently in training data?     │
│    → If YES: Is it REALLY suitable for THIS project?            │
│                                                                 │
│  □ Did I write this solution automatically without thinking?    │
│    → If YES: Step back, do decomposition.                       │
│                                                                 │
│  □ Did I consider an alternative approach?                      │
│    → If NO: Think of at least 2 alternatives, then decide.      │
│                                                                 │
│  □ Did I think platform-specifically?                           │
│    → If NO: Analyze iOS and Android separately.                 │
│                                                                 │
│  □ Did I consider performance impact of this solution?          │
│    → If NO: What is the memory, CPU, battery impact?            │
│                                                                 │
│  □ Is this solution suitable for THIS project's CONTEXT?        │
│    → If NO: Customize based on context.                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

📊 CONTEXT-BASED DECISION PROTOCOL

Think Differently Based on Project Type

DETERMINE PROJECT TYPE:
        │
        ├── E-Commerce App
        │   ├── Navigation: Tab (Home, Search, Cart, Account)
        │   ├── Lists: Product grids (memoized, image optimized)
        │   ├── Performance: Image caching CRITICAL
        │   ├── Offline: Cart persistence, product cache
        │   └── Special: Checkout flow, payment security
        │
        ├── Social/Content App
        │   ├── Navigation: Tab (Feed, Search, Create, Notify, Profile)
        │   ├── Lists: Infinite scroll, complex items
        │   ├── Performance: Feed rendering CRITICAL
        │   ├── Offline: Feed cache, draft posts
        │   └── Special: Real-time updates, media handling
        │
        ├── Productivity/SaaS App
        │   ├── Navigation: Drawer or adaptive (mobile tab, tablet rail)
        │   ├── Lists: Data tables, forms
        │   ├── Performance: Data sync
        │   ├── Offline: Full offline editing
        │   └── Special: Conflict resolution, background sync
        │
        ├── Utility App
        │   ├── Navigation: Minimal (stack-only possible)
        │   ├── Lists: Probably minimal
        │   ├── Performance: Fast startup
        │   ├── Offline: Core feature offline
        │   └── Special: Widget, shortcuts
        │
        └── Media/Streaming App
            ├── Navigation: Tab (Home, Search, Library, Profile)
            ├── Lists: Horizontal carousels, vertical feeds
            ├── Performance: Preloading, buffering
            ├── Offline: Download management
            └── Special: Background playback, casting

---

🔄 INTERACTION BREAKDOWN

Analysis for Every Gesture

Before adding any gesture:

GESTURE: [Gesture Type]
├── DISCOVERABILITY:
│   └── How will users discover this gesture?
│       ├── Is there a visual hint?
│       ├── Will it be shown in onboarding?
│       └── Is there a button alternative? (MANDATORY)
│
├── PLATFORM CONVENTION:
│   ├── What does this gesture mean on iOS?
│   ├── What does this gesture mean on Android?
│   └── Am I deviating from platform convention?
│
├── ACCESSIBILITY:
│   ├── Can motor-impaired users perform this gesture?
│   ├── Is there a VoiceOver/TalkBack alternative?
│   └── Does it work with switch control?
│
├── CONFLICT CHECK:
│   ├── Does it conflict with system gestures?
│   │   ├── iOS: Edge swipe back
│   │   ├── Android: Back gesture
│   │   └── Home indicator swipe
│   └── Is it consistent with other app gestures?
│
└── FEEDBACK:
    ├── Is haptic feedback defined?
    ├── Is visual feedback sufficient?
    └── Is audio feedback needed?

---

🎭 SPIRIT OVER CHECKLIST (Mobile Edition)

Passing the Checklist is Not Enough!

🔴 Passing the checklist is NOT the goal. Creating great mobile UX IS the goal.

---

📝 MOBILE DESIGN COMMITMENT

Fill This at the Start of Every Mobile Project

📱 MOBILE DESIGN COMMITMENT

Project: _______________
Platform: iOS / Android / Both

1. Default pattern I will NOT use in this project:
   └── _______________
   
2. Context-specific focus for this project:
   └── _______________

3. Platform-specific differences I will implement:
   └── iOS: _______________
   └── Android: _______________

4. Area I will specifically optimize for performance:
   └── _______________

5. Unique challenge of this project:
   └── _______________

🧠 If I can't fill this commitment → I don't understand the project well enough.
   → Go back, understand context better, ask the user.

---

🚨 MANDATORY: Before Every Mobile Work

┌─────────────────────────────────────────────────────────────────┐
│                    PRE-WORK VALIDATION                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  □ Did I complete Component Decomposition?                      │
│  □ Did I fill the Pattern Questioning Matrix?                   │
│  □ Did I pass the Anti-Memorization Test?                       │
│  □ Did I make context-based decisions?                          │
│  □ Did I analyze Interaction Breakdown?                         │
│  □ Did I fill the Mobile Design Commitment?                     │
│                                                                 │
│  ⚠️ Do not write code without completing these!                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Remember: If you chose a solution "because that's how it's always done," you chose WITHOUT THINKING. Every project is unique. Every context is different. Every user behavior is specific. THINK, then code.

Mobile Navigation Reference

Navigation patterns, deep linking, back handling, and tab/stack/drawer decisions.

Navigation is the skeleton of your app—get it wrong and everything feels broken.

---

1. Navigation Selection Decision Tree

WHAT TYPE OF APP?
        │
        ├── 3-5 top-level sections (equal importance)
        │   └── ✅ Tab Bar / Bottom Navigation
        │       Examples: Social, E-commerce, Utility
        │
        ├── Deep hierarchical content (drill down)
        │   └── ✅ Stack Navigation
        │       Examples: Settings, Email folders
        │
        ├── Many destinations (>5 top-level)
        │   └── ✅ Drawer Navigation
        │       Examples: Gmail, complex enterprise
        │
        ├── Single linear flow
        │   └── ✅ Stack only (wizard/onboarding)
        │       Examples: Checkout, Setup flow
        │
        └── Tablet/Foldable
            └── ✅ Navigation Rail + List-Detail
                Examples: Mail, Notes on iPad

---

2. Tab Bar Navigation

When to Use

✅ USE Tab Bar when:
├── 3-5 top-level destinations
├── Destinations are of equal importance
├── User frequently switches between them
├── Each tab has independent navigation stack
└── App is used in short sessions

❌ AVOID Tab Bar when:
├── More than 5 destinations
├── Destinations have clear hierarchy
├── Tabs would be used very unequally
└── Content flows in a sequence

Tab Bar Best Practices

iOS Tab Bar:
├── Height: 49pt (83pt with home indicator)
├── Max items: 5
├── Icons: SF Symbols, 25×25pt
├── Labels: Always show (accessibility)
├── Active indicator: Tint color

Android Bottom Navigation:
├── Height: 80dp
├── Max items: 5 (3-5 ideal)
├── Icons: Material Symbols, 24dp
├── Labels: Always show
├── Active indicator: Pill shape + filled icon

Tab State Preservation

RULE: Each tab maintains its own navigation stack.

User journey:
1. Home tab → Drill into item → Add to cart
2. Switch to Profile tab
3. Switch back to Home tab
→ Should return to "Add to cart" screen, NOT home root

Implementation:
├── React Navigation: Each tab has own navigator
├── Flutter: IndexedStack for state preservation
└── Never reset tab stack on switch

---

3. Stack Navigation

Core Concepts

Stack metaphor: Cards stacked on top of each other

Push: Add screen on top
Pop: Remove top screen (back)
Replace: Swap current screen
Reset: Clear stack, set new root

Visual: New screen slides in from right (LTR)
Back: Screen slides out to right

Stack Navigation Patterns

Back Button Handling

iOS:
├── Edge swipe from left (system)
├── Back button in nav bar (optional)
├── Interactive pop gesture
└── Never override swipe back without good reason

Android:
├── System back button/gesture
├── Up button in toolbar (optional, for drill-down)
├── Predictive back animation (Android 14+)
└── Must handle back correctly (Activity/Fragment)

Cross-Platform Rule:
├── Back ALWAYS navigates up the stack
├── Never hijack back for other purposes
├── Confirm before discarding unsaved data
└── Deep links should allow full back traversal

---

4. Drawer Navigation

When to Use

✅ USE Drawer when:
├── More than 5 top-level destinations
├── Less frequently accessed destinations
├── Complex app with many features
├── Need for branding/user info in nav
└── Tablet/large screen with persistent drawer

❌ AVOID Drawer when:
├── 5 or fewer destinations (use tabs)
├── All destinations equally important
├── Mobile-first simple app
└── Discoverability is critical (drawer is hidden)

Drawer Patterns

Modal Drawer:
├── Opens over content (scrim behind)
├── Swipe to open from edge
├── Hamburger icon ( ☰ ) triggers
└── Most common on mobile

Permanent Drawer:
├── Always visible (large screens)
├── Content shifts over
├── Good for productivity apps
└── Tablets, desktops

Navigation Rail (Android):
├── Narrow vertical strip
├── Icons + optional labels
├── For tablets in portrait
└── 80dp width

---

5. Modal Navigation

Modal vs Push

PUSH (Stack):                    MODAL:
├── Horizontal slide             ├── Vertical slide up (sheet)
├── Part of hierarchy            ├── Separate task
├── Back returns                 ├── Dismiss (X) returns
├── Same navigation context      ├── Own navigation context
└── "Drill in"                   └── "Focus on task"

USE MODAL for:
├── Creating new content
├── Settings/preferences
├── Completing a transaction
├── Self-contained workflows
├── Quick actions

Modal Types

Modal Dismissal

Users expect to dismiss modals by:
├── Tapping X / Close button
├── Swiping down (sheet)
├── Tapping scrim (non-critical)
├── System back (Android)
├── Hardware back (old Android)

RULE: Only block dismissal for unsaved data.

---

6. Deep Linking

Why Deep Links from Day One

Deep links enable:
├── Push notification navigation
├── Sharing content
├── Marketing campaigns
├── Spotlight/Search integration
├── Widget navigation
├── External app integration

Building later is HARD:
├── Requires navigation refactor
├── Screen dependencies unclear
├── Parameter passing complex
└── Always plan deep links at start

URL Structure

Scheme://host/path?params

Examples:
├── myapp://product/123
├── https://myapp.com/product/123 (Universal/App Link)
├── myapp://checkout?promo=SAVE20
├── myapp://tab/profile/settings

Hierarchy should match navigation:
├── myapp://home
├── myapp://home/product/123
├── myapp://home/product/123/reviews
└── URL path = navigation path

Deep Link Navigation Rules

1. FULL STACK CONSTRUCTION
   Deep link to myapp://product/123 should:
   ├── Put Home at root of stack
   ├── Push Product screen on top
   └── Back button returns to Home

2. AUTHENTICATION AWARENESS
   If deep link requires auth:
   ├── Save intended destination
   ├── Redirect to login
   ├── After login, navigate to destination

3. INVALID LINKS
   If deep link target doesn't exist:
   ├── Navigate to fallback (home)
   ├── Show error message
   └── Never crash or blank screen

4. STATEFUL NAVIGATION
   Deep link during active session:
   ├── Don't blow away current stack
   ├── Push on top OR
   ├── Ask user if should navigate away

---

7. Navigation State Persistence

What to Persist

SHOULD persist:
├── Current tab selection
├── Scroll position in lists
├── Form draft data
├── Recent navigation stack
└── User preferences

SHOULD NOT persist:
├── Modal states (dialogs)
├── Temporary UI states
├── Stale data (refresh on return)
├── Authentication state (use secure storage)

Implementation

// React Navigation - State Persistence
const [isReady, setIsReady] = useState(false);
const [initialState, setInitialState] = useState();

useEffect(() => {
  const loadState = async () => {
    const savedState = await AsyncStorage.getItem('NAV_STATE');
    if (savedState) setInitialState(JSON.parse(savedState));
    setIsReady(true);
  };
  loadState();
}, []);

const handleStateChange = (state) => {
  AsyncStorage.setItem('NAV_STATE', JSON.stringify(state));
};

<NavigationContainer
  initialState={initialState}
  onStateChange={handleStateChange}
>

---

8. Transition Animations

Platform Defaults

iOS Transitions:
├── Push: Slide from right
├── Modal: Slide from bottom (sheet) or fade
├── Tab switch: Cross-fade
├── Interactive: Swipe to go back

Android Transitions:
├── Push: Fade + slide from right
├── Modal: Slide from bottom
├── Tab switch: Cross-fade or none
├── Shared element: Hero animations

Custom Transitions

When to custom:
├── Brand identity requires it
├── Shared element connections
├── Special reveal effects
└── Keep it subtle, <300ms

When to use default:
├── Most of the time
├── Standard drill-down
├── Platform consistency
└── Performance critical paths

Shared Element Transitions

Connect elements between screens:

Screen A: Product card with image
            ↓ (tap)
Screen B: Product detail with same image (expanded)

Image animates from card position to detail position.

Implementation:
├── React Navigation: shared element library
├── Flutter: Hero widget
├── SwiftUI: matchedGeometryEffect
└── Compose: Shared element transitions

---

9. Navigation Anti-Patterns

❌ Navigation Sins

❌ AI Navigation Mistakes

AI tends to:
├── Use modals for everything (wrong)
├── Forget tab state preservation (wrong)
├── Skip deep linking (wrong)
├── Override platform back behavior (wrong)
├── Reset stack on tab switch (wrong)
└── Ignore predictive back (Android 14+)

RULE: Use platform navigation patterns.
Don't reinvent navigation.

---

10. Navigation Checklist

Before Navigation Architecture

• [ ] App type determined (tabs/drawer/stack)
• [ ] Number of top-level destinations counted
• [ ] Deep link URL scheme planned
• [ ] Auth flow integrated with navigation
• [ ] Tablet/large screen considered

Before Every Screen

• [ ] Can user navigate back? (not dead end)
• [ ] Deep link to this screen planned
• [ ] State preserved on navigate away/back
• [ ] Transition appropriate for relationship
• [ ] Auth required? Handled?

Before Release

• [ ] All deep links tested
• [ ] Back button works everywhere
• [ ] Tab states preserved correctly
• [ ] Edge swipe back works (iOS)
• [ ] Predictive back works (Android 14+)
• [ ] Universal/App links configured
• [ ] Push notification deep links work

---

Remember: Navigation is invisible when done right. Users shouldn't think about HOW to get somewhere—they just get there. If they notice navigation, something is wrong.

Mobile Performance Reference

Deep dive into React Native and Flutter performance optimization, 60fps animations, memory management, and battery considerations.

This file covers the #1 area where AI-generated code FAILS.

---

1. The Mobile Performance Mindset

Why Mobile Performance is Different

DESKTOP:                          MOBILE:
├── Unlimited power               ├── Battery matters
├── Abundant RAM                  ├── RAM is shared, limited
├── Stable network                ├── Network is unreliable
├── CPU always available          ├── CPU throttles when hot
└── User expects fast anyway      └── User expects INSTANT

Performance Budget Concept

Every frame must complete in:
├── 60fps → 16.67ms per frame
├── 120fps (ProMotion) → 8.33ms per frame

If your code takes longer:
├── Frame drops → Janky scroll/animation
├── User perceives as "slow" or "broken"
└── They WILL uninstall your app

---

2. React Native Performance

🚫 The #1 AI Mistake: ScrollView for Lists

// ❌ NEVER DO THIS - AI's favorite mistake
<ScrollView>
  {items.map(item => (
    <ItemComponent key={item.id} item={item} />
  ))}
</ScrollView>

// Why it's catastrophic:
// ├── Renders ALL items immediately (1000 items = 1000 renders)
// ├── Memory explodes
// ├── Initial render takes seconds
// └── Scroll becomes janky

// ✅ ALWAYS USE FlatList
<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={item => item.id}
/>

FlatList Optimization Checklist

// ✅ CORRECT: All optimizations applied

// 1. Memoize the item component
const ListItem = React.memo(({ item }: { item: Item }) => {
  return (
    <Pressable style={styles.item}>
      <Text>{item.title}</Text>
    </Pressable>
  );
});

// 2. Memoize renderItem with useCallback
const renderItem = useCallback(
  ({ item }: { item: Item }) => <ListItem item={item} />,
  [] // Empty deps = never recreated
);

// 3. Stable keyExtractor (NEVER use index!)
const keyExtractor = useCallback((item: Item) => item.id, []);

// 4. Provide getItemLayout for fixed-height items
const getItemLayout = useCallback(
  (data: Item[] | null, index: number) => ({
    length: ITEM_HEIGHT, // Fixed height
    offset: ITEM_HEIGHT * index,
    index,
  }),
  []
);

// 5. Apply to FlatList
<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={keyExtractor}
  getItemLayout={getItemLayout}
  // Performance props
  removeClippedSubviews={true} // Android: detach off-screen
  maxToRenderPerBatch={10} // Items per batch
  windowSize={5} // Render window (5 = 2 screens each side)
  initialNumToRender={10} // Initial items
  updateCellsBatchingPeriod={50} // Batching delay
/>

Why Each Optimization Matters

FlashList: The Better Option

// Consider FlashList for better performance
import { FlashList } from "@shopify/flash-list";

<FlashList
  data={items}
  renderItem={renderItem}
  estimatedItemSize={ITEM_HEIGHT}
  keyExtractor={keyExtractor}
/>

// Benefits over FlatList:
// ├── Faster recycling
// ├── Better memory management
// ├── Simpler API
// └── Fewer optimization props needed

Animation Performance

// ❌ JS-driven animation (blocks JS thread)
Animated.timing(value, {
  toValue: 1,
  duration: 300,
  useNativeDriver: false, // BAD!
}).start();

// ✅ Native-driver animation (runs on UI thread)
Animated.timing(value, {
  toValue: 1,
  duration: 300,
  useNativeDriver: true, // GOOD!
}).start();

// Native driver supports ONLY:
// ├── transform (translate, scale, rotate)
// └── opacity
// 
// Does NOT support:
// ├── width, height
// ├── backgroundColor
// ├── borderRadius changes
// └── margin, padding

Reanimated for Complex Animations

// For animations native driver can't handle, use Reanimated 3

import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from 'react-native-reanimated';

const Component = () => {
  const offset = useSharedValue(0);

  const animatedStyles = useAnimatedStyle(() => ({
    transform: [{ translateX: withSpring(offset.value) }],
  }));

  return <Animated.View style={animatedStyles} />;
};

// Benefits:
// ├── Runs on UI thread (60fps guaranteed)
// ├── Can animate any property
// ├── Gesture-driven animations
// └── Worklets for complex logic

Memory Leak Prevention

// ❌ Memory leak: uncleared interval
useEffect(() => {
  const interval = setInterval(() => {
    fetchData();
  }, 5000);
  // Missing cleanup!
}, []);

// ✅ Proper cleanup
useEffect(() => {
  const interval = setInterval(() => {
    fetchData();
  }, 5000);
  
  return () => clearInterval(interval); // CLEANUP!
}, []);

// Common memory leak sources:
// ├── Timers (setInterval, setTimeout)
// ├── Event listeners
// ├── Subscriptions (WebSocket, PubSub)
// ├── Async operations that update state after unmount
// └── Image caching without limits

React Native Performance Checklist

## Before Every List
- [ ] Using FlatList or FlashList (NOT ScrollView)
- [ ] renderItem is useCallback memoized
- [ ] List items are React.memo wrapped
- [ ] keyExtractor uses stable ID (NOT index)
- [ ] getItemLayout provided (if fixed height)

## Before Every Animation
- [ ] useNativeDriver: true (if possible)
- [ ] Using Reanimated for complex animations
- [ ] Only animating transform/opacity
- [ ] Tested on low-end Android device

## Before Any Release
- [ ] console.log statements removed
- [ ] Cleanup functions in all useEffects
- [ ] No memory leaks (test with profiler)
- [ ] Tested in release build (not dev)

---

3. Flutter Performance

🚫 The #1 AI Mistake: setState Overuse

// ❌ WRONG: setState rebuilds ENTIRE widget tree
class BadCounter extends StatefulWidget {
  @override
  State<BadCounter> createState() => _BadCounterState();
}

class _BadCounterState extends State<BadCounter> {
  int _counter = 0;
  
  void _increment() {
    setState(() {
      _counter++; // This rebuilds EVERYTHING below!
    });
  }
  
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Counter: $_counter'),
        ExpensiveWidget(), // Rebuilds unnecessarily!
        AnotherExpensiveWidget(), // Rebuilds unnecessarily!
      ],
    );
  }
}

The const Constructor Revolution

// ✅ CORRECT: const prevents rebuilds

class GoodCounter extends StatefulWidget {
  const GoodCounter({super.key}); // CONST constructor!
  
  @override
  State<GoodCounter> createState() => _GoodCounterState();
}

class _GoodCounterState extends State<GoodCounter> {
  int _counter = 0;
  
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Counter: $_counter'),
        const ExpensiveWidget(), // Won't rebuild!
        const AnotherExpensiveWidget(), // Won't rebuild!
      ],
    );
  }
}

// RULE: Add `const` to EVERY widget that doesn't depend on state

Targeted State Management

// ❌ setState rebuilds whole tree
setState(() => _value = newValue);

// ✅ ValueListenableBuilder: surgical rebuilds
class TargetedState extends StatelessWidget {
  final ValueNotifier<int> counter = ValueNotifier(0);
  
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // Only this rebuilds when counter changes
        ValueListenableBuilder<int>(
          valueListenable: counter,
          builder: (context, value, child) => Text('$value'),
          child: const Icon(Icons.star), // Won't rebuild!
        ),
        const ExpensiveWidget(), // Never rebuilds
      ],
    );
  }
}

Riverpod/Provider Best Practices

// ❌ WRONG: Reading entire provider in build
Widget build(BuildContext context) {
  final state = ref.watch(myProvider); // Rebuilds on ANY change
  return Text(state.name);
}

// ✅ CORRECT: Select only what you need
Widget build(BuildContext context) {
  final name = ref.watch(myProvider.select((s) => s.name));
  return Text(name); // Only rebuilds when name changes
}

ListView Optimization

// ❌ WRONG: ListView without builder (renders all)
ListView(
  children: items.map((item) => ItemWidget(item)).toList(),
)

// ✅ CORRECT: ListView.builder (lazy rendering)
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemWidget(items[index]),
  // Additional optimizations:
  itemExtent: 56, // Fixed height = faster layout
  cacheExtent: 100, // Pre-render distance
)

// ✅ EVEN BETTER: ListView.separated for dividers
ListView.separated(
  itemCount: items.length,
  itemBuilder: (context, index) => ItemWidget(items[index]),
  separatorBuilder: (context, index) => const Divider(),
)

Image Optimization

// ❌ WRONG: No caching, full resolution
Image.network(url)

// ✅ CORRECT: Cached with proper sizing
CachedNetworkImage(
  imageUrl: url,
  width: 100,
  height: 100,
  fit: BoxFit.cover,
  memCacheWidth: 200, // Cache at 2x for retina
  memCacheHeight: 200,
  placeholder: (context, url) => const Skeleton(),
  errorWidget: (context, url, error) => const Icon(Icons.error),
)

Dispose Pattern

class MyWidget extends StatefulWidget {
  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late final StreamSubscription _subscription;
  late final AnimationController _controller;
  late final TextEditingController _textController;
  
  @override
  void initState() {
    super.initState();
    _subscription = stream.listen((_) {});
    _controller = AnimationController(vsync: this);
    _textController = TextEditingController();
  }
  
  @override
  void dispose() {
    // ALWAYS dispose in reverse order of creation
    _textController.dispose();
    _controller.dispose();
    _subscription.cancel();
    super.dispose();
  }
  
  @override
  Widget build(BuildContext context) => Container();
}

Flutter Performance Checklist

## Before Every Widget
- [ ] const constructor added (if no runtime args)
- [ ] const keywords on static children
- [ ] Minimal setState scope
- [ ] Using selectors for provider watches

## Before Every List
- [ ] Using ListView.builder (NOT ListView with children)
- [ ] itemExtent provided (if fixed height)
- [ ] Image caching with size limits

## Before Any Animation
- [ ] Using Impeller (Flutter 3.16+)
- [ ] Avoiding Opacity widget (use FadeTransition)
- [ ] TickerProviderStateMixin for AnimationController

## Before Any Release
- [ ] All dispose() methods implemented
- [ ] No print() in production
- [ ] Tested in profile/release mode
- [ ] DevTools performance overlay checked

---

4. Animation Performance (Both Platforms)

The 60fps Imperative

Human eye detects:
├── < 24 fps → "Slideshow" (broken)
├── 24-30 fps → "Choppy" (uncomfortable)
├── 30-45 fps → "Noticeably not smooth"
├── 45-60 fps → "Smooth" (acceptable)
├── 60 fps → "Buttery" (target)
└── 120 fps → "Premium" (ProMotion devices)

NEVER ship < 60fps animations.

GPU vs CPU Animation

GPU-ACCELERATED (FAST):          CPU-BOUND (SLOW):
├── transform: translate          ├── width, height
├── transform: scale              ├── top, left, right, bottom
├── transform: rotate             ├── margin, padding
├── opacity                       ├── border-radius (animated)
└── (Composited, off main)        └── box-shadow (animated)

RULE: Only animate transform and opacity.
Everything else causes layout recalculation.

Animation Timing Guide

Spring Physics

// React Native Reanimated
withSpring(targetValue, {
  damping: 15,      // How quickly it settles (higher = faster stop)
  stiffness: 150,   // How "tight" the spring (higher = faster)
  mass: 1,          // Weight of the object
})

// Flutter
SpringSimulation(
  SpringDescription(
    mass: 1,
    stiffness: 150,
    damping: 15,
  ),
  start,
  end,
  velocity,
)

// Natural feel ranges:
// Damping: 10-20 (bouncy to settled)
// Stiffness: 100-200 (loose to tight)
// Mass: 0.5-2 (light to heavy)

---

5. Memory Management

Common Memory Leaks

Image Memory

Image memory = width × height × 4 bytes (RGBA)

1080p image = 1920 × 1080 × 4 = 8.3 MB
4K image = 3840 × 2160 × 4 = 33.2 MB

10 4K images = 332 MB → App crash!

RULE: Always resize images to display size (or 2-3x for retina).

Memory Profiling

React Native:
├── Flipper → Memory tab
├── Xcode Instruments (iOS)
└── Android Studio Profiler

Flutter:
├── DevTools → Memory tab
├── Observatory
└── flutter run --profile

---

6. Battery Optimization

Battery Drain Sources

OLED Battery Saving

OLED screens: Black pixels = OFF = 0 power

Dark mode savings:
├── True black (#000000) → Maximum savings
├── Dark gray (#1a1a1a) → Slight savings
├── Any color → Some power
└── White (#FFFFFF) → Maximum power

RULE: On dark mode, use true black for backgrounds.

Background Task Guidelines

iOS:
├── Background refresh: Limited, system-scheduled
├── Push notifications: Use for important updates
├── Background modes: Location, audio, VoIP only
└── Background tasks: Max ~30 seconds

Android:
├── WorkManager: System-scheduled, battery-aware
├── Foreground service: Visible to user, continuous
├── JobScheduler: Batch network operations
└── Doze mode: Respect it, batch operations

---

7. Network Performance

Offline-First Architecture

                    ┌──────────────┐
                    │     UI       │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │   Cache      │ ← Read from cache FIRST
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │   Network    │ ← Update cache from network
                    └──────────────┘

Benefits:
├── Instant UI (no loading spinner for cached data)
├── Works offline
├── Reduces data usage
└── Better UX on slow networks

Request Optimization

BATCH: Combine multiple requests into one
├── 10 small requests → 1 batch request
├── Reduces connection overhead
└── Better for battery (radio on once)

CACHE: Don't re-fetch unchanged data
├── ETag/If-None-Match headers
├── Cache-Control headers
└── Stale-while-revalidate pattern

COMPRESS: Reduce payload size
├── gzip/brotli compression
├── Request only needed fields (GraphQL)
└── Paginate large lists

---

8. Performance Testing

What to Test

Test on Real Devices

⚠️ NEVER trust only:
├── Simulator/emulator (faster than real)
├── Dev mode (slower than release)
├── High-end devices only

✅ ALWAYS test on:
├── Low-end Android (< $200 phone)
├── Older iOS device (iPhone 8 or SE)
├── Release/profile build
└── With real data (not 10 items)

Performance Monitoring Checklist

## During Development
- [ ] Performance overlay enabled
- [ ] Watching for dropped frames
- [ ] Memory usage stable
- [ ] No console warnings about performance

## Before Release
- [ ] Tested on low-end device
- [ ] Profiled memory over extended use
- [ ] Cold start time measured
- [ ] List scroll tested with 1000+ items
- [ ] Animations tested at 60fps
- [ ] Network tested on slow 3G

---

9. Quick Reference Card

React Native Essentials

// List: Always use
<FlatList
  data={data}
  renderItem={useCallback(({item}) => <MemoItem item={item} />, [])}
  keyExtractor={useCallback(item => item.id, [])}
  getItemLayout={useCallback((_, i) => ({length: H, offset: H*i, index: i}), [])}
/>

// Animation: Always native
useNativeDriver: true

// Cleanup: Always present
useEffect(() => {
  return () => cleanup();
}, []);

Flutter Essentials

// Widgets: Always const
const MyWidget()

// Lists: Always builder
ListView.builder(itemBuilder: ...)

// State: Always targeted
ValueListenableBuilder() or ref.watch(provider.select(...))

// Dispose: Always cleanup
@override
void dispose() {
  controller.dispose();
  super.dispose();
}

Animation Targets

Transform/Opacity only ← What to animate
16.67ms per frame ← Time budget
60fps minimum ← Target
Low-end Android ← Test device

---

Remember: Performance is not optimization—it's baseline quality. A slow app is a broken app. Test on the worst device your users have, not the best device you have.

Mobile Testing Patterns

Mobile testing is NOT web testing. Different constraints, different strategies.

This file teaches WHEN to use each testing approach and WHY.

Code examples are minimal - focus on decision-making.

---

🧠 MOBILE TESTING MINDSET

Mobile testing differs from web:
├── Real devices matter (emulators hide bugs)
├── Platform differences (iOS vs Android behavior)
├── Network conditions vary wildly
├── Battery/performance under test
├── App lifecycle (background, killed, restored)
├── Permissions and system dialogs
└── Touch interactions vs clicks

---

🚫 AI MOBILE TESTING ANTI-PATTERNS

---

1. Testing Tool Selection

Decision Tree

WHAT ARE YOU TESTING?
        │
        ├── Pure functions, utilities, helpers
        │   └── Jest (unit tests)
        │       └── No special mobile setup needed
        │
        ├── Individual components (isolated)
        │   ├── React Native → React Native Testing Library
        │   └── Flutter → flutter_test (widget tests)
        │
        ├── Components with hooks, context, navigation
        │   ├── React Native → RNTL + mocked providers
        │   └── Flutter → integration_test package
        │
        ├── Full user flows (login, checkout, etc.)
        │   ├── Detox (React Native, fast, reliable)
        │   ├── Maestro (Cross-platform, YAML-based)
        │   └── Appium (Legacy, slow, last resort)
        │
        └── Performance, memory, battery
            ├── Flashlight (RN performance)
            ├── Flutter DevTools
            └── Real device profiling (Xcode/Android Studio)

Tool Comparison

---

2. Testing Pyramid for Mobile

                    ┌───────────────┐
                    │    E2E Tests  │  10%
                    │  (Real device) │  Slow, expensive, essential
                    ├───────────────┤
                    │  Integration  │  20%
                    │    Tests      │  Component + context
                    ├───────────────┤
                    │  Component    │  30%
                    │    Tests      │  Isolated UI
                    ├───────────────┤
                    │   Unit Tests  │  40%
                    │    (Jest)     │  Pure logic
                    └───────────────┘

Why This Distribution?

🔴 If you have 90% unit tests and 0% E2E, you're testing the wrong things.

---

3. What to Test at Each Level

Unit Tests (Jest)

✅ TEST:
├── Utility functions (formatDate, calculatePrice)
├── State reducers (Redux, Zustand stores)
├── API response transformers
├── Validation logic
└── Business rules

❌ DON'T TEST:
├── Component rendering (use component tests)
├── Navigation (use integration tests)
├── Native modules (mock them)
└── Third-party libraries

Component Tests (RNTL / flutter_test)

✅ TEST:
├── Component renders correctly
├── User interactions (tap, type, swipe)
├── Loading/error/empty states
├── Accessibility labels exist
└── Props change behavior

❌ DON'T TEST:
├── Internal implementation details
├── Snapshot everything (only key components)
├── Styling specifics (brittle)
└── Third-party component internals

Integration Tests

✅ TEST:
├── Form submission flows
├── Navigation between screens
├── State persistence across screens
├── API integration (with mocked server)
└── Context/provider interactions

❌ DON'T TEST:
├── Every possible path (use unit tests)
├── Third-party services (mock them)
└── Backend logic (backend tests)

E2E Tests

✅ TEST:
├── Critical user journeys (login, purchase, signup)
├── Offline → online transitions
├── Deep link handling
├── Push notification navigation
├── Permission flows
└── Payment flows

❌ DON'T TEST:
├── Every edge case (too slow)
├── Visual regression (use snapshot tests)
├── Non-critical features
└── Backend-only logic

---

4. Platform-Specific Testing

What Differs Between iOS and Android?

Platform Testing Strategy

FOR EACH PLATFORM:
├── Run unit tests (same on both)
├── Run component tests (same on both)
├── Run E2E on REAL DEVICE
│   ├── iOS: iPhone (not just simulator)
│   └── Android: Mid-range device (not flagship)
└── Test platform-specific features separately

---

5. Offline & Network Testing

Offline Scenarios to Test

How to Test Network Conditions

APPROACH:
├── Unit tests: Mock NetInfo, test logic
├── Integration: Mock API responses, test UI
├── E2E (Detox): Use device.setURLBlacklist()
├── E2E (Maestro): Use network conditions
└── Manual: Use Charles Proxy / Network Link Conditioner

---

6. Performance Testing

What to Measure

When to Performance Test

PERFORMANCE TEST:
├── Before release (required)
├── After adding heavy features
├── After upgrading dependencies
├── When users report slowness
└── On CI (optional, automated benchmarks)

WHERE TO TEST:
├── Real device (REQUIRED)
├── Low-end device (Galaxy A series, old iPhone)
├── NOT on emulator (lies about performance)
└── With production-like data (not 3 items)

---

7. Accessibility Testing

What to Verify

How to Test

AUTOMATED:
├── React Native: jest-axe
├── Flutter: Accessibility checker in tests
└── Lint rules for missing labels

MANUAL:
├── Enable VoiceOver (iOS) / TalkBack (Android)
├── Navigate entire app with screen reader
├── Test with increased text size
└── Test with reduced motion

---

8. CI/CD Integration

What to Run Where

Device Farm Options

---

📝 MOBILE TESTING CHECKLIST

Before PR

• [ ] Unit tests for new logic
• [ ] Component tests for new UI
• [ ] No console.logs in tests
• [ ] Tests pass on CI

Before Release

• [ ] E2E on real iOS device
• [ ] E2E on real Android device
• [ ] Tested on low-end device
• [ ] Offline scenarios verified
• [ ] Performance acceptable
• [ ] Accessibility verified

What to Skip (Consciously)

• [ ] 100% coverage (aim for meaningful coverage)
• [ ] Every visual permutation (use snapshots sparingly)
• [ ] Third-party library internals
• [ ] Backend logic (separate tests)

---

🎯 Testing Questions to Ask

Before writing tests, answer:

1. What could break? → Test that 2. What's critical for users? → E2E test that 3. What's complex logic? → Unit test that 4. What's platform-specific? → Test on both platforms 5. What happens offline? → Test that scenario

Remember: Good mobile testing is about testing the RIGHT things, not EVERYTHING. A flaky E2E test is worse than no test. A failing unit test that catches a bug is worth 100 passing trivial tests.

Mobile Typography Reference

Type scale, system fonts, Dynamic Type, accessibility, and dark mode typography.

Typography failures are the #1 cause of unreadable mobile apps.

---

1. Mobile Typography Fundamentals

Why Mobile Type is Different

DESKTOP:                        MOBILE:
├── 20-30" viewing distance     ├── 12-15" viewing distance
├── Large viewport              ├── Small viewport, narrow
├── Hover for details           ├── Tap/scroll for details
├── Controlled lighting         ├── Variable (outdoor, etc.)
├── Fixed font size             ├── User-controlled sizing
└── Long reading sessions       └── Quick scanning

Mobile Type Rules

---

2. System Fonts

iOS: SF Pro Family

San Francisco (SF) Family:
├── SF Pro Display: Large text (≥ 20pt)
├── SF Pro Text: Body text (< 20pt)
├── SF Pro Rounded: Friendly contexts
├── SF Mono: Monospace
└── SF Compact: Apple Watch, compact UI

Features:
├── Optical sizing (auto-adjusts)
├── Dynamic tracking (spacing)
├── Tabular/proportional figures
├── Excellent legibility

Android: Roboto Family

Roboto Family:
├── Roboto: Default sans-serif
├── Roboto Flex: Variable font
├── Roboto Serif: Serif option
├── Roboto Mono: Monospace
├── Roboto Condensed: Narrow spaces

Features:
├── Optimized for screens
├── Wide language support
├── Multiple weights
├── Good at small sizes

When to Use System Fonts

✅ USE system fonts when:
├── Brand doesn't mandate custom font
├── Reading efficiency is priority
├── App feels native/integrated important
├── Performance is critical
├── Wide language support needed

❌ AVOID system fonts when:
├── Brand identity requires custom
├── Design differentiation needed
├── Editorial/magazine style
└── (But still support accessibility)

Custom Font Considerations

If using custom fonts:
├── Include all weights needed
├── Subset for file size
├── Test at all Dynamic Type sizes
├── Provide fallback to system
├── Test rendering quality
└── Check language support

---

3. Type Scale

iOS Type Scale (Built-in)

Android Type Scale (Material 3)

Creating Custom Scale

If creating custom scale, use modular ratio:

Recommended ratios:
├── 1.125 (Major second): Dense UI
├── 1.200 (Minor third): Compact
├── 1.250 (Major third): Balanced (common)
├── 1.333 (Perfect fourth): Spacious
└── 1.500 (Perfect fifth): Dramatic

Example with 1.25 ratio, 16px base:
├── xs: 10px (16 ÷ 1.25 ÷ 1.25)
├── sm: 13px (16 ÷ 1.25)
├── base: 16px
├── lg: 20px (16 × 1.25)
├── xl: 25px (16 × 1.25 × 1.25)
├── 2xl: 31px
├── 3xl: 39px
└── 4xl: 49px

---

4. Dynamic Type / Text Scaling

iOS Dynamic Type (MANDATORY)

// ❌ WRONG: Fixed size (doesn't scale)
Text("Hello")
    .font(.system(size: 17))

// ✅ CORRECT: Dynamic Type
Text("Hello")
    .font(.body) // Scales with user setting

// Custom font with scaling
Text("Hello")
    .font(.custom("MyFont", size: 17, relativeTo: .body))

Android Text Scaling (MANDATORY)

ALWAYS use sp for text:
├── sp = Scale-independent pixels
├── Scales with user font preference
├── dp does NOT scale (don't use for text)

User can scale from 85% to 200%:
├── Default (100%): 14sp = 14dp
├── Largest (200%): 14sp = 28dp

Test at 200%!

Scaling Challenges

Problems at large text sizes:
├── Text overflows containers
├── Buttons become too tall
├── Icons look small relative to text
├── Layouts break

Solutions:
├── Use flexible containers (not fixed height)
├── Allow text wrapping
├── Scale icons with text
├── Test at extremes during development
├── Use scrollable containers for long text

---

5. Typography Accessibility

Minimum Sizes

Contrast Requirements (WCAG)

Normal text (< 18pt or < 14pt bold):
├── AA: 4.5:1 ratio minimum
├── AAA: 7:1 ratio recommended

Large text (≥ 18pt or ≥ 14pt bold):
├── AA: 3:1 ratio minimum
├── AAA: 4.5:1 ratio recommended

Logos/decorative: No requirement

Line Height for Accessibility

WCAG Success Criterion 1.4.12:

Line height (line spacing): ≥ 1.5×
Paragraph spacing: ≥ 2× font size
Letter spacing: ≥ 0.12× font size
Word spacing: ≥ 0.16× font size

Mobile recommendation:
├── Body: 1.4-1.6 line height
├── Headings: 1.2-1.3 line height
├── Never below 1.2

---

6. Dark Mode Typography

Color Adjustments

Light Mode:               Dark Mode:
├── Black text (#000)     ├── White/light gray (#E0E0E0)
├── High contrast         ├── Slightly reduced contrast
├── Full saturation       ├── Desaturated colors
└── Dark = emphasis       └── Light = emphasis

RULE: Don't use pure white (#FFF) on dark.
Use off-white (#E0E0E0 to #F0F0F0) to reduce eye strain.

Dark Mode Hierarchy

Weight in Dark Mode

Dark mode text appears thinner due to halation
(light bleeding into dark background)

Consider:
├── Using medium weight for body (instead of regular)
├── Increasing letter-spacing slightly
├── Testing on actual OLED displays
└── Using slightly bolder weight than light mode

---

7. Typography Anti-Patterns

❌ Common Mistakes

❌ AI Typography Mistakes

AI tends to:
├── Use fixed px values instead of pt/sp
├── Skip Dynamic Type support
├── Use too small text (12-14px body)
├── Ignore line height settings
├── Use low contrast "aesthetic" grays
├── Apply same scale to mobile as desktop
└── Skip testing at large text sizes

RULE: Typography must SCALE.
Test at smallest and largest settings.

---

8. Font Loading & Performance

Font File Optimization

Font file sizes matter on mobile:
├── Full font: 100-300KB per weight
├── Subset (Latin): 15-40KB per weight
├── Variable font: 100-200KB (all weights)

Recommendations:
├── Subset to needed characters
├── Use WOFF2 format
├── Max 2-3 font files
├── Consider variable fonts
├── Cache fonts appropriately

Loading Strategy

1. SYSTEM FONT FALLBACK
   Show system font → swap when custom loads
   
2. FONT DISPLAY SWAP
   font-display: swap (CSS)
   
3. PRELOAD CRITICAL FONTS
   Preload fonts needed above the fold
   
4. DON'T BLOCK RENDER
   Don't wait for fonts to show content

---

9. Typography Checklist

Before Any Text Design

• [ ] Body text ≥ 16px/pt/sp?
• [ ] Line height ≥ 1.4?
• [ ] Line length ≤ 60 chars?
• [ ] Type scale defined (max 5-7 sizes)?
• [ ] Using pt (iOS) or sp (Android)?

Before Release

• [ ] Dynamic Type tested (iOS)?
• [ ] Font scaling tested at 200% (Android)?
• [ ] Dark mode contrast checked?
• [ ] Sunlight readability tested?
• [ ] All text has proper hierarchy?
• [ ] Custom fonts have fallbacks?
• [ ] Long text scrolls properly?

---

10. Quick Reference

Typography Tokens

// iOS
.largeTitle  // 34pt, Bold
.title       // 28pt, Bold
.title2      // 22pt, Bold
.title3      // 20pt, Semibold
.headline    // 17pt, Semibold
.body        // 17pt, Regular
.subheadline // 15pt, Regular
.footnote    // 13pt, Regular
.caption     // 12pt, Regular

// Android (Material 3)
displayLarge   // 57sp
headlineLarge  // 32sp
titleLarge     // 22sp
bodyLarge      // 16sp
labelLarge     // 14sp

Minimum Sizes

Body:       14-16pt/sp (16 preferred)
Secondary:  12-13pt/sp
Caption:    11-12pt/sp
Nothing:    < 11pt/sp

Line Height

Headings:  1.1-1.3
Body:      1.4-1.6
Long text: 1.5-1.75

---

Remember: If users can't read your text, your app is broken. Typography isn't decoration—it's the primary interface. Test on real devices, in real conditions, with accessibility settings enabled.