Mobile Design System

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

Core Principle: Mobile is NOT a small desktop. THINK mobile constraints, ASK platform choice.

🔧 Runtime Scripts

Execute these for validation (don't read, just run):

Script

Purpose

Usage

scripts/mobile_audit.py

Mobile UX & Touch Audit

python scripts/mobile_audit.py <project_path>

🔴 MANDATORY: Read Reference Files Before Working!

⛔ DO NOT start development until you read the relevant files:

Universal (Always Read)

File

Content

Status

mobile-design-thinking.md

⚠️ ANTI-MEMORIZATION: Forces thinking, prevents AI defaults

⬜ CRITICAL FIRST

touch-psychology.md

Fitts' Law, gestures, haptics, thumb zone

⬜ CRITICAL

mobile-performance.md

RN/Flutter performance, 60fps, memory

⬜ CRITICAL

mobile-backend.md

Push notifications, offline sync, mobile API

⬜ CRITICAL

mobile-testing.md

Testing pyramid, E2E, platform-specific

⬜ CRITICAL

mobile-debugging.md

Native vs JS debugging, Flipper, Logcat

⬜ CRITICAL

mobile-navigation.md

Tab/Stack/Drawer, deep linking

⬜ Read

mobile-typography.md

System fonts, Dynamic Type, a11y

⬜ Read

mobile-color-system.md

OLED, dark mode, battery-aware

⬜ Read

decision-trees.md

Framework/state/storage selection

⬜ Read

🧠 mobile-design-thinking.md is PRIORITY! This file ensures AI thinks instead of using memorized patterns.

Platform-Specific (Read Based on Target)

Platform

File

Content

When to Read

iOS

platform-ios.md

Human Interface Guidelines, SF Pro, SwiftUI patterns

Building for iPhone/iPad

Android

platform-android.md

Material Design 3, Roboto, Compose patterns

Building for Android

Cross-Platform

Both above

Platform divergence points

React Native / Flutter

🔴 If building for iOS → Read platform-ios.md FIRST!

🔴 If building for Android → Read platform-android.md FIRST!

🔴 If cross-platform → Read BOTH and apply conditional platform logic!

⚠️ CRITICAL: ASK BEFORE ASSUMING (MANDATORY)

STOP! If the user's request is open-ended, DO NOT default to your favorites.

You MUST Ask If Not Specified:

Aspect

Ask

Why

Platform

"iOS, Android, or both?"

Affects EVERY design decision

Framework

"React Native, Flutter, or native?"

Determines patterns and tools

Navigation

"Tab bar, drawer, or stack-based?"

Core UX decision

State

"What state management? (Zustand/Redux/Riverpod/BLoC?)"

Architecture foundation

Offline

"Does this need to work offline?"

Affects data strategy

Target devices

"Phone only, or tablet support?"

Layout complexity

⛔ AI MOBILE ANTI-PATTERNS (YASAK LİSTESİ)

🚫 These are AI default tendencies that MUST be avoided!

#### Performance Sins

❌ NEVER DO

Why It's Wrong

✅ ALWAYS DO

ScrollView for long lists

Renders ALL items, memory explodes

Use FlatList / FlashList / ListView.builder

Inline renderItem function

New function every render, all items re-render

useCallback + React.memo

Missing keyExtractor

Index-based keys cause bugs on reorder

Unique, stable ID from data

Skip getItemLayout

Async layout = janky scroll

Provide when items have fixed height

setState() everywhere

Unnecessary widget rebuilds

Targeted state, const constructors

Native driver: false

Animations blocked by JS thread

useNativeDriver: true always

console.log in production

Blocks JS thread severely

Remove before release build

Skip React.memo/const

Every item re-renders on any change

Memoize list items ALWAYS

#### Touch/UX Sins

❌ NEVER DO

Why It's Wrong

✅ ALWAYS DO

Touch target < 44px

Impossible to tap accurately, frustrating

Minimum 44pt (iOS) / 48dp (Android)

Spacing < 8px between targets

Accidental taps on neighbors

Minimum 8-12px gap

Gesture-only interactions

Motor impaired users excluded

Always provide button alternative

No loading state

User thinks app crashed

ALWAYS show loading feedback

No error state

User stuck, no recovery path

Show error with retry option

No offline handling

Crash/block when network lost

Graceful degradation, cached data

Ignore platform conventions

Users confused, muscle memory broken

iOS feels iOS, Android feels Android

#### Security Sins

❌ NEVER DO

Why It's Wrong

✅ ALWAYS DO

Token in AsyncStorage

Easily accessible, stolen on rooted device

SecureStore / Keychain / EncryptedSharedPreferences

Hardcode API keys

Reverse engineered from APK/IPA

Environment variables, secure storage

Skip SSL pinning

MITM attacks possible

Pin certificates in production

Log sensitive data

Logs can be extracted

Never log tokens, passwords, PII

#### Architecture Sins

❌ NEVER DO

Why It's Wrong

✅ ALWAYS DO

Business logic in UI

Untestable, unmaintainable

Service layer separation

Global state for everything

Unnecessary re-renders, complexity

Local state default, lift when needed

Deep linking as afterthought

Notifications, shares broken

Plan deep links from day one

Skip dispose/cleanup

Memory leaks, zombie listeners

Clean up subscriptions, timers

📱 Platform Decision Matrix

When to Unify vs Diverge

UNIFY (same on both)          DIVERGE (platform-specific)

                    ───────────────────           ──────────────────────────

Business Logic      ✅ Always                     -

Data Layer          ✅ Always                     -

Core Features       ✅ Always                     -

Navigation          -                             ✅ iOS: edge swipe, Android: back button

Gestures            -                             ✅ Platform-native feel

Icons               -                             ✅ SF Symbols vs Material Icons

Date Pickers        -                             ✅ Native pickers feel right

Modals/Sheets       -                             ✅ iOS: bottom sheet vs Android: dialog

Typography          -                             ✅ SF Pro vs Roboto (or custom)

Error Dialogs       -                             ✅ Platform conventions for alerts

Quick Reference: Platform Defaults

Element

iOS

Android

Primary Font

SF Pro / SF Compact

Roboto

Min Touch Target

44pt × 44pt

48dp × 48dp

Back Navigation

Edge swipe left

System back button/gesture

Bottom Tab Icons

SF Symbols

Material Symbols

Action Sheet

UIActionSheet from bottom

Bottom Sheet / Dialog

Progress

Spinner

Linear progress (Material)

Pull to Refresh

Native UIRefreshControl

SwipeRefreshLayout

🧠 Mobile UX Psychology (Quick Reference)

Fitts' Law for Touch

Desktop: Cursor is precise (1px)

Mobile:  Finger is imprecise (~7mm contact area)

→ Touch targets MUST be 44-48px minimum

→ Important actions in THUMB ZONE (bottom of screen)

→ Destructive actions AWAY from easy reach

Thumb Zone (One-Handed Usage)

┌─────────────────────────────┐

│      HARD TO REACH          │ ← Navigation, menu, back

│        (stretch)            │

├─────────────────────────────┤

│      OK TO REACH            │ ← Secondary actions

│       (natural)             │

├─────────────────────────────┤

│      EASY TO REACH          │ ← PRIMARY CTAs, tab bar

│    (thumb's natural arc)    │ ← Main content interaction

└─────────────────────────────┘

        [  HOME  ]

Mobile-Specific Cognitive Load

Desktop

Mobile Difference

Multiple windows

ONE task at a time

Keyboard shortcuts

Touch gestures

Hover states

NO hover (tap or nothing)

Large viewport

Limited space, scroll vertical

Stable attention

Interrupted constantly

For deep dive: touch-psychology.md

⚡ Performance Principles (Quick Reference)

React Native Critical Rules

// ✅ CORRECT: Memoized renderItem + React.memo wrapper

const ListItem = React.memo(({ item }: { item: Item }) => (

  <View style={styles.item}>

    <Text>{item.title}</Text>

  </View>

));

const renderItem = useCallback(

  ({ item }: { item: Item }) => <ListItem item={item} />,

  []

);

// ✅ CORRECT: FlatList with all optimizations

<FlatList

  data={items}

  renderItem={renderItem}

  keyExtractor={(item) => item.id}  // Stable ID, NOT index

  getItemLayout={(data, index) => ({

    length: ITEM_HEIGHT,

    offset: ITEM_HEIGHT * index,

    index,

  })}

  removeClippedSubviews={true}

  maxToRenderPerBatch={10}

  windowSize={5}

/>

Flutter Critical Rules

// ✅ CORRECT: const constructors prevent rebuilds

class MyWidget extends StatelessWidget {

  const MyWidget({super.key}); // CONST!

  @override

  Widget build(BuildContext context) {

    return const Column( // CONST!

      children: [

        Text('Static content'),

        MyConstantWidget(),

      ],

    );

  }

}

// ✅ CORRECT: Targeted state with ValueListenableBuilder

ValueListenableBuilder<int>(

  valueListenable: counter,

  builder: (context, value, child) => Text('$value'),

  child: const ExpensiveWidget(), // Won't rebuild!

)

Animation Performance

GPU-accelerated (FAST):     CPU-bound (SLOW):

├── transform               ├── width, height

├── opacity                 ├── top, left, right, bottom

└── (use these ONLY)        ├── margin, padding

                            └── (AVOID animating these)

For complete guide: mobile-performance.md

📝 CHECKPOINT (MANDATORY Before Any Mobile Work)

Before writing ANY mobile code, you MUST complete this checkpoint:

🧠 CHECKPOINT:

Platform:   [ iOS / Android / Both ]

Framework:  [ React Native / Flutter / SwiftUI / Kotlin ]

Files Read: [ List the skill files you've read ]

3 Principles I Will Apply:

1. _______________

2. _______________

3. _______________

Anti-Patterns I Will Avoid:

1. _______________

2. _______________

Example:

🧠 CHECKPOINT:

Platform:   iOS + Android (Cross-platform)

Framework:  React Native + Expo

Files Read: touch-psychology.md, mobile-performance.md, platform-ios.md, platform-android.md

3 Principles I Will Apply:

1. FlatList with React.memo + useCallback for all lists

2. 48px touch targets, thumb zone for primary CTAs

3. Platform-specific navigation (edge swipe iOS, back button Android)

Anti-Patterns I Will Avoid:

1. ScrollView for lists → FlatList

2. Inline renderItem → Memoized

3. AsyncStorage for tokens → SecureStore

🔴 Can't fill the checkpoint? → GO BACK AND READ THE SKILL FILES.

🔧 Framework Decision Tree

WHAT ARE YOU BUILDING?

        │

        ├── Need OTA updates + rapid iteration + web team

        │   └── ✅ React Native + Expo

        │

        ├── Need pixel-perfect custom UI + performance critical

        │   └── ✅ Flutter

        │

        ├── Deep native features + single platform focus

        │   ├── iOS only → SwiftUI

        │   └── Android only → Kotlin + Jetpack Compose

        │

        ├── Existing RN codebase + new features

        │   └── ✅ React Native (bare workflow)

        │

        └── Enterprise + existing Flutter codebase

            └── ✅ Flutter

For complete decision trees: decision-trees.md

📋 Pre-Development Checklist

Before Starting ANY Mobile Project

• Platform confirmed? (iOS / Android / Both)

• Framework chosen? (RN / Flutter / Native)

• Navigation pattern decided? (Tabs / Stack / Drawer)

• State management selected? (Zustand / Redux / Riverpod / BLoC)

• Offline requirements known?

• Deep linking planned from day one?

• Target devices defined? (Phone / Tablet / Both)

Before Every Screen

• Touch targets ≥ 44-48px?

• Primary CTA in thumb zone?

• Loading state exists?

• Error state with retry exists?

• Offline handling considered?

• Platform conventions followed?

Before Release

• console.log removed?

• SecureStore for sensitive data?

• SSL pinning enabled?

• Lists optimized (memo, keyExtractor)?

• Memory cleanup on unmount?

• Tested on low-end devices?

• Accessibility labels on all interactive elements?

📚 Reference Files

For deeper guidance on specific areas:

File

When to Use

mobile-design-thinking.md

FIRST! Anti-memorization, forces context-based thinking

touch-psychology.md

Understanding touch interaction, Fitts' Law, gesture design

mobile-performance.md

Optimizing RN/Flutter, 60fps, memory/battery

platform-ios.md

iOS-specific design, HIG compliance

platform-android.md

Android-specific design, Material Design 3

mobile-navigation.md

Navigation patterns, deep linking

mobile-typography.md

Type scale, system fonts, accessibility

mobile-color-system.md

OLED optimization, dark mode, battery

decision-trees.md

Framework, state, storage decisions

Remember: Mobile users are impatient, interrupted, and using imprecise fingers on small screens. Design for the WORST conditions: bad network, one hand, bright sun, low battery. If it works there, it works everywhere.