mobile-design

davila7

Mobile-first design thinking and decision-making for iOS and Android apps. Touch interaction, performance patterns, platform conventions. Teaches principles, not fixed values. Use when building React Native, Flutter, or native mobile apps.

Quick Install

bunx add-skill davila7/claude-code-templates -s mobile-design

Read,Glob,Grep,Bashanthropicanthropic-claudeclaudeclaude-code

Instructions

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

Loading…

Related Skills

flow

Use when you need to run Flow type checking, or when seeing Flow type errors in React code.

242,585

verify

Use when you want to validate changes before committing, or when you need to check all React contribution requirements.

242,585

feature-flags

Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.

242,585

flags

Use when you need to check feature flag states, compare channels, or debug why a feature behaves differently across release channels.

242,582

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

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

❌ 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

❌ 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

❌ 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

❌ 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

                    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

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

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

┌─────────────────────────────┐
│      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  ]

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

// ✅ 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}
/>

// ✅ 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!
)

GPU-accelerated (FAST):     CPU-bound (SLOW):
├── transform               ├── width, height
├── opacity                 ├── top, left, right, bottom
└── (use these ONLY)        ├── margin, padding
                            └── (AVOID animating these)

🧠 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. _______________

🧠 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

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

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

mobile-design

Mobile Design System

🔧 Runtime Scripts

🔴 MANDATORY: Read Reference Files Before Working!

Universal (Always Read)

Related Skills

flow

verify

feature-flags

flags

Mobile Design System

🔧 Runtime Scripts

🔴 MANDATORY: Read Reference Files Before Working!

Universal (Always Read)

Platform-Specific (Read Based on Target)

⚠️ CRITICAL: ASK BEFORE ASSUMING (MANDATORY)

You MUST Ask If Not Specified:

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

Performance Sins

Touch/UX Sins

Security Sins

Architecture Sins

📱 Platform Decision Matrix

When to Unify vs Diverge

Quick Reference: Platform Defaults

🧠 Mobile UX Psychology (Quick Reference)

Fitts' Law for Touch

Thumb Zone (One-Handed Usage)

Mobile-Specific Cognitive Load

⚡ Performance Principles (Quick Reference)

React Native Critical Rules

Flutter Critical Rules

Animation Performance

📝 CHECKPOINT (MANDATORY Before Any Mobile Work)

🔧 Framework Decision Tree

📋 Pre-Development Checklist

Before Starting ANY Mobile Project

Before Every Screen

Before Release

📚 Reference Files

Related Skills

flow

verify

feature-flags

flags