Update SKILL.md
This commit is contained in:
Munir Abbasi
@@ -1,394 +1,284 @@
|
|||||||
---
|
---
|
||||||
name: mobile-design
|
name: mobile-design
|
||||||
description: 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.
|
description: Mobile-first design and engineering doctrine for iOS and Android apps. Covers touch interaction, performance, platform conventions, offline behavior, and mobile-specific decision-making. Teaches principles and constraints, not fixed layouts. Use for React Native, Flutter, or native mobile apps.
|
||||||
allowed-tools: Read, Glob, Grep, Bash
|
allowed-tools: Read, Glob, Grep, Bash
|
||||||
---
|
---
|
||||||
|
|
||||||
# Mobile Design System
|
# Mobile Design System
|
||||||
|
|
||||||
|
**(Mobile-First · Touch-First · Platform-Respectful)**
|
||||||
|
|
||||||
> **Philosophy:** Touch-first. Battery-conscious. Platform-respectful. Offline-capable.
|
> **Philosophy:** Touch-first. Battery-conscious. Platform-respectful. Offline-capable.
|
||||||
> **Core Principle:** Mobile is NOT a small desktop. THINK mobile constraints, ASK platform choice.
|
> **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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔧 Runtime Scripts
|
## 1. Mobile Feasibility & Risk Index (MFRI)
|
||||||
|
|
||||||
**Execute these for validation (don't read, just run):**
|
Before designing or implementing **any mobile feature or screen**, assess feasibility.
|
||||||
|
|
||||||
| Script | Purpose | Usage |
|
### MFRI Dimensions (1–5)
|
||||||
|--------|---------|-------|
|
|
||||||
| `scripts/mobile_audit.py` | Mobile UX & Touch Audit | `python scripts/mobile_audit.py <project_path>` |
|
| Dimension | Question |
|
||||||
|
| -------------------------- | ----------------------------------------------------------------- |
|
||||||
|
| **Platform Clarity** | Is the target platform (iOS / Android / both) explicitly defined? |
|
||||||
|
| **Interaction Complexity** | How complex are gestures, flows, or navigation? |
|
||||||
|
| **Performance Risk** | Does this involve lists, animations, heavy state, or media? |
|
||||||
|
| **Offline Dependence** | Does the feature break or degrade without network? |
|
||||||
|
| **Accessibility Risk** | Does this impact motor, visual, or cognitive accessibility? |
|
||||||
|
|
||||||
|
### Score Formula
|
||||||
|
|
||||||
|
```
|
||||||
|
MFRI = (Platform Clarity + Accessibility Readiness)
|
||||||
|
− (Interaction Complexity + Performance Risk + Offline Dependence)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Range:** `-10 → +10`
|
||||||
|
|
||||||
|
### Interpretation
|
||||||
|
|
||||||
|
| MFRI | Meaning | Required Action |
|
||||||
|
| -------- | --------- | ------------------------------------- |
|
||||||
|
| **6–10** | Safe | Proceed normally |
|
||||||
|
| **3–5** | Moderate | Add performance + UX validation |
|
||||||
|
| **0–2** | Risky | Simplify interactions or architecture |
|
||||||
|
| **< 0** | Dangerous | Redesign before implementation |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔴 MANDATORY: Read Reference Files Before Working!
|
## 2. Mandatory Thinking Before Any Work
|
||||||
|
|
||||||
**⛔ DO NOT start development until you read the relevant files:**
|
### ⛔ STOP: Ask Before Assuming (Required)
|
||||||
|
|
||||||
### Universal (Always Read)
|
If **any of the following are not explicitly stated**, you MUST ask before proceeding:
|
||||||
|
|
||||||
| File | Content | Status |
|
| Aspect | Question | Why |
|
||||||
|------|---------|--------|
|
| ---------- | ------------------------------------------ | ---------------------------------------- |
|
||||||
| **[mobile-design-thinking.md](mobile-design-thinking.md)** | **⚠️ ANTI-MEMORIZATION: Forces thinking, prevents AI defaults** | **⬜ CRITICAL FIRST** |
|
| Platform | iOS, Android, or both? | Affects navigation, gestures, typography |
|
||||||
| **[touch-psychology.md](touch-psychology.md)** | **Fitts' Law, gestures, haptics, thumb zone** | **⬜ CRITICAL** |
|
| Framework | React Native, Flutter, or native? | Determines performance and patterns |
|
||||||
| **[mobile-performance.md](mobile-performance.md)** | **RN/Flutter performance, 60fps, memory** | **⬜ CRITICAL** |
|
| Navigation | Tabs, stack, drawer? | Core UX architecture |
|
||||||
| **[mobile-backend.md](mobile-backend.md)** | **Push notifications, offline sync, mobile API** | **⬜ CRITICAL** |
|
| Offline | Must it work offline? | Data & sync strategy |
|
||||||
| **[mobile-testing.md](mobile-testing.md)** | **Testing pyramid, E2E, platform-specific** | **⬜ CRITICAL** |
|
| Devices | Phone only or tablet too? | Layout & density rules |
|
||||||
| **[mobile-debugging.md](mobile-debugging.md)** | **Native vs JS debugging, Flipper, Logcat** | **⬜ CRITICAL** |
|
| Audience | Consumer, enterprise, accessibility needs? | Touch & readability |
|
||||||
| [mobile-navigation.md](mobile-navigation.md) | Tab/Stack/Drawer, deep linking | ⬜ Read |
|
|
||||||
| [mobile-typography.md](mobile-typography.md) | System fonts, Dynamic Type, a11y | ⬜ Read |
|
|
||||||
| [mobile-color-system.md](mobile-color-system.md) | OLED, dark mode, battery-aware | ⬜ Read |
|
|
||||||
| [decision-trees.md](decision-trees.md) | Framework/state/storage selection | ⬜ Read |
|
|
||||||
|
|
||||||
> 🧠 **mobile-design-thinking.md is PRIORITY!** This file ensures AI thinks instead of using memorized patterns.
|
🚫 **Never default to your favorite stack or pattern.**
|
||||||
|
|
||||||
### Platform-Specific (Read Based on Target)
|
|
||||||
|
|
||||||
| Platform | File | Content | When to Read |
|
|
||||||
|----------|------|---------|--------------|
|
|
||||||
| **iOS** | [platform-ios.md](platform-ios.md) | Human Interface Guidelines, SF Pro, SwiftUI patterns | Building for iPhone/iPad |
|
|
||||||
| **Android** | [platform-android.md](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)
|
## 3. Mandatory Reference Reading (Enforced)
|
||||||
|
|
||||||
> **STOP! If the user's request is open-ended, DO NOT default to your favorites.**
|
### Universal (Always Read First)
|
||||||
|
|
||||||
### You MUST Ask If Not Specified:
|
| File | Purpose | Status |
|
||||||
|
| ----------------------------- | ---------------------------------- | ----------------- |
|
||||||
|
| **mobile-design-thinking.md** | Anti-memorization, context-forcing | 🔴 REQUIRED FIRST |
|
||||||
|
| **touch-psychology.md** | Fitts’ Law, thumb zones, gestures | 🔴 REQUIRED |
|
||||||
|
| **mobile-performance.md** | 60fps, memory, battery | 🔴 REQUIRED |
|
||||||
|
| **mobile-backend.md** | Offline sync, push, APIs | 🔴 REQUIRED |
|
||||||
|
| **mobile-testing.md** | Device & E2E testing | 🔴 REQUIRED |
|
||||||
|
| **mobile-debugging.md** | Native vs JS debugging | 🔴 REQUIRED |
|
||||||
|
|
||||||
| Aspect | Ask | Why |
|
### Platform-Specific (Conditional)
|
||||||
|--------|-----|-----|
|
|
||||||
| **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İ)
|
| Platform | File |
|
||||||
|
| -------------- | ------------------- |
|
||||||
|
| iOS | platform-ios.md |
|
||||||
|
| Android | platform-android.md |
|
||||||
|
| Cross-platform | BOTH above |
|
||||||
|
|
||||||
> 🚫 **These are AI default tendencies that MUST be avoided!**
|
> ❌ If you haven’t read the platform file, you are not allowed to design UI.
|
||||||
|
|
||||||
#### 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
|
## 4. AI Mobile Anti-Patterns (Hard Bans)
|
||||||
|
|
||||||
### When to Unify vs Diverge
|
### 🚫 Performance Sins (Non-Negotiable)
|
||||||
|
|
||||||
```
|
| ❌ Never | Why | ✅ Always |
|
||||||
UNIFY (same on both) DIVERGE (platform-specific)
|
| ------------------------- | -------------------- | --------------------------------------- |
|
||||||
─────────────────── ──────────────────────────
|
| ScrollView for long lists | Memory explosion | FlatList / FlashList / ListView.builder |
|
||||||
Business Logic ✅ Always -
|
| Inline renderItem | Re-renders all rows | useCallback + memo |
|
||||||
Data Layer ✅ Always -
|
| Index as key | Reorder bugs | Stable ID |
|
||||||
Core Features ✅ Always -
|
| JS-thread animations | Jank | Native driver / GPU |
|
||||||
|
| console.log in prod | JS thread block | Strip logs |
|
||||||
Navigation - ✅ iOS: edge swipe, Android: back button
|
| No memoization | Battery + perf drain | React.memo / const widgets |
|
||||||
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)
|
### 🚫 Touch & UX Sins
|
||||||
|
|
||||||
### Fitts' Law for Touch
|
| ❌ Never | Why | ✅ Always |
|
||||||
|
| --------------------- | -------------------- | ----------------- |
|
||||||
```
|
| Touch <44–48px | Miss taps | Min touch target |
|
||||||
Desktop: Cursor is precise (1px)
|
| Gesture-only action | Excludes users | Button fallback |
|
||||||
Mobile: Finger is imprecise (~7mm contact area)
|
| No loading state | Feels broken | Explicit feedback |
|
||||||
|
| No error recovery | Dead end | Retry + message |
|
||||||
→ Touch targets MUST be 44-48px minimum
|
| Ignore platform norms | Muscle memory broken | iOS ≠ Android |
|
||||||
→ 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](touch-psychology.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚡ Performance Principles (Quick Reference)
|
### 🚫 Security Sins
|
||||||
|
|
||||||
### React Native Critical Rules
|
| ❌ Never | Why | ✅ Always |
|
||||||
|
| ---------------------- | ------------------ | ---------------------- |
|
||||||
|
| Tokens in AsyncStorage | Easily stolen | SecureStore / Keychain |
|
||||||
|
| Hardcoded secrets | Reverse engineered | Env + secure storage |
|
||||||
|
| No SSL pinning | MITM risk | Cert pinning |
|
||||||
|
| Log sensitive data | PII leakage | Never log secrets |
|
||||||
|
|
||||||
```typescript
|
---
|
||||||
// ✅ CORRECT: Memoized renderItem + React.memo wrapper
|
|
||||||
const ListItem = React.memo(({ item }: { item: Item }) => (
|
## 5. Platform Unification vs Divergence Matrix
|
||||||
<View style={styles.item}>
|
|
||||||
<Text>{item.title}</Text>
|
```
|
||||||
</View>
|
UNIFY DIVERGE
|
||||||
|
────────────────────────── ─────────────────────────
|
||||||
|
Business logic Navigation behavior
|
||||||
|
Data models Gestures
|
||||||
|
API contracts Icons
|
||||||
|
Validation Typography
|
||||||
|
Error semantics Pickers / dialogs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Platform Defaults
|
||||||
|
|
||||||
|
| Element | iOS | Android |
|
||||||
|
| --------- | ------------ | -------------- |
|
||||||
|
| Font | SF Pro | Roboto |
|
||||||
|
| Min touch | 44pt | 48dp |
|
||||||
|
| Back | Edge swipe | System back |
|
||||||
|
| Sheets | Bottom sheet | Dialog / sheet |
|
||||||
|
| Icons | SF Symbols | Material Icons |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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)
|
||||||
|
|
||||||
|
```ts
|
||||||
|
const Row = React.memo(({ item }) => (
|
||||||
|
<View><Text>{item.title}</Text></View>
|
||||||
));
|
));
|
||||||
|
|
||||||
const renderItem = useCallback(
|
const renderItem = useCallback(
|
||||||
({ item }: { item: Item }) => <ListItem item={item} />,
|
({ item }) => <Row item={item} />,
|
||||||
[]
|
[]
|
||||||
);
|
);
|
||||||
|
|
||||||
// ✅ CORRECT: FlatList with all optimizations
|
|
||||||
<FlatList
|
<FlatList
|
||||||
data={items}
|
data={items}
|
||||||
renderItem={renderItem}
|
renderItem={renderItem}
|
||||||
keyExtractor={(item) => item.id} // Stable ID, NOT index
|
keyExtractor={(i) => i.id}
|
||||||
getItemLayout={(data, index) => ({
|
getItemLayout={(_, i) => ({
|
||||||
length: ITEM_HEIGHT,
|
length: ITEM_HEIGHT,
|
||||||
offset: ITEM_HEIGHT * index,
|
offset: ITEM_HEIGHT * i,
|
||||||
index,
|
index: i,
|
||||||
})}
|
})}
|
||||||
removeClippedSubviews={true}
|
|
||||||
maxToRenderPerBatch={10}
|
|
||||||
windowSize={5}
|
|
||||||
/>
|
/>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Flutter Critical Rules
|
### Flutter (Required Pattern)
|
||||||
|
|
||||||
```dart
|
```dart
|
||||||
// ✅ CORRECT: const constructors prevent rebuilds
|
class Item extends StatelessWidget {
|
||||||
class MyWidget extends StatelessWidget {
|
const Item({super.key});
|
||||||
const MyWidget({super.key}); // CONST!
|
|
||||||
|
|
||||||
@override
|
@override
|
||||||
Widget build(BuildContext context) {
|
Widget build(BuildContext context) {
|
||||||
return const Column( // CONST!
|
return const Text('Static');
|
||||||
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
|
* `const` everywhere possible
|
||||||
|
* Targeted rebuilds only
|
||||||
```
|
|
||||||
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](mobile-performance.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📝 CHECKPOINT (MANDATORY Before Any Mobile Work)
|
## 8. Mandatory Mobile Checkpoint
|
||||||
|
|
||||||
> **Before writing ANY mobile code, you MUST complete this checkpoint:**
|
Before writing **any code**, you must complete this:
|
||||||
|
|
||||||
```
|
```
|
||||||
🧠 CHECKPOINT:
|
🧠 MOBILE CHECKPOINT
|
||||||
|
|
||||||
Platform: [ iOS / Android / Both ]
|
Platform: ___________
|
||||||
Framework: [ React Native / Flutter / SwiftUI / Kotlin ]
|
Framework: ___________
|
||||||
Files Read: [ List the skill files you've read ]
|
Files Read: ___________
|
||||||
|
|
||||||
3 Principles I Will Apply:
|
3 Principles I Will Apply:
|
||||||
1. _______________
|
1.
|
||||||
2. _______________
|
2.
|
||||||
3. _______________
|
3.
|
||||||
|
|
||||||
Anti-Patterns I Will Avoid:
|
Anti-Patterns I Will Avoid:
|
||||||
1. _______________
|
1.
|
||||||
2. _______________
|
2.
|
||||||
```
|
```
|
||||||
|
|
||||||
**Example:**
|
❌ Cannot complete → go back and read.
|
||||||
```
|
|
||||||
🧠 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
|
## 9. Framework Decision Tree (Canonical)
|
||||||
|
|
||||||
```
|
```
|
||||||
WHAT ARE YOU BUILDING?
|
Need OTA + web team → React Native + Expo
|
||||||
│
|
High-perf UI → Flutter
|
||||||
├── Need OTA updates + rapid iteration + web team
|
iOS only → SwiftUI
|
||||||
│ └── ✅ React Native + Expo
|
Android only → Compose
|
||||||
│
|
|
||||||
├── 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](decision-trees.md)
|
No debate without justification.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📋 Pre-Development Checklist
|
## 10. Release Readiness Checklist
|
||||||
|
|
||||||
### Before Starting ANY Mobile Project
|
### Before Shipping
|
||||||
|
|
||||||
- [ ] **Platform confirmed?** (iOS / Android / Both)
|
* [ ] Touch targets ≥ 44–48px
|
||||||
- [ ] **Framework chosen?** (RN / Flutter / Native)
|
* [ ] Offline handled
|
||||||
- [ ] **Navigation pattern decided?** (Tabs / Stack / Drawer)
|
* [ ] Secure storage used
|
||||||
- [ ] **State management selected?** (Zustand / Redux / Riverpod / BLoC)
|
* [ ] Lists optimized
|
||||||
- [ ] **Offline requirements known?**
|
* [ ] Logs stripped
|
||||||
- [ ] **Deep linking planned from day one?**
|
* [ ] Tested on low-end devices
|
||||||
- [ ] **Target devices defined?** (Phone / Tablet / Both)
|
* [ ] Accessibility labels present
|
||||||
|
* [ ] MFRI ≥ 3
|
||||||
### 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
|
## 11. Related Skills
|
||||||
|
|
||||||
For deeper guidance on specific areas:
|
* **frontend-design** – Visual systems & components
|
||||||
|
* **frontend-dev-guidelines** – RN/TS architecture
|
||||||
| File | When to Use |
|
* **backend-dev-guidelines** – Mobile-safe APIs
|
||||||
|------|-------------|
|
* **error-tracking** – Crash & performance telemetry
|
||||||
| [mobile-design-thinking.md](mobile-design-thinking.md) | **FIRST! Anti-memorization, forces context-based thinking** |
|
|
||||||
| [touch-psychology.md](touch-psychology.md) | Understanding touch interaction, Fitts' Law, gesture design |
|
|
||||||
| [mobile-performance.md](mobile-performance.md) | Optimizing RN/Flutter, 60fps, memory/battery |
|
|
||||||
| [platform-ios.md](platform-ios.md) | iOS-specific design, HIG compliance |
|
|
||||||
| [platform-android.md](platform-android.md) | Android-specific design, Material Design 3 |
|
|
||||||
| [mobile-navigation.md](mobile-navigation.md) | Navigation patterns, deep linking |
|
|
||||||
| [mobile-typography.md](mobile-typography.md) | Type scale, system fonts, accessibility |
|
|
||||||
| [mobile-color-system.md](mobile-color-system.md) | OLED optimization, dark mode, battery |
|
|
||||||
| [decision-trees.md](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.
|
> **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.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|||||||
Reference in New Issue
Block a user