Mobile Design

1---
2name: mobile-design
3description: 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.
4allowed-tools: Read, Glob, Grep, Bash
5---
6# Mobile Design System
7 
8**(Mobile-First · Touch-First · Platform-Respectful)**
9 
10> **Philosophy:** Touch-first. Battery-conscious. Platform-respectful. Offline-capable.
11> **Core Law:** Mobile is NOT a small desktop.
12> **Operating Rule:** Think constraints first, aesthetics second.
13 
14This skill exists to **prevent desktop-thinking, AI-defaults, and unsafe assumptions** when designing or building mobile applications.
15 
16---
17 
18## 1. Mobile Feasibility & Risk Index (MFRI)
19 
20Before designing or implementing **any mobile feature or screen**, assess feasibility.
21 
22### MFRI Dimensions (1–5)
23 
24| Dimension                  | Question                                                          |
25| -------------------------- | ----------------------------------------------------------------- |
26| **Platform Clarity**       | Is the target platform (iOS / Android / both) explicitly defined? |
27| **Interaction Complexity** | How complex are gestures, flows, or navigation?                   |
28| **Performance Risk**       | Does this involve lists, animations, heavy state, or media?       |
29| **Offline Dependence**     | Does the feature break or degrade without network?                |
30| **Accessibility Risk**     | Does this impact motor, visual, or cognitive accessibility?       |
31 
32### Score Formula
33 
34```
35MFRI = (Platform Clarity + Accessibility Readiness)
36       − (Interaction Complexity + Performance Risk + Offline Dependence)
37```
38 
39**Range:** `-10 → +10`
40 
41### Interpretation
42 
43| MFRI     | Meaning   | Required Action                       |
44| -------- | --------- | ------------------------------------- |
45| **6–10** | Safe      | Proceed normally                      |
46| **3–5**  | Moderate  | Add performance + UX validation       |
47| **0–2**  | Risky     | Simplify interactions or architecture |
48| **< 0**  | Dangerous | Redesign before implementation        |
49 
50---
51 
52## 2. Mandatory Thinking Before Any Work
53 
54### ⛔ STOP: Ask Before Assuming (Required)
55 
56If **any of the following are not explicitly stated**, you MUST ask before proceeding:
57 
58| Aspect     | Question                                   | Why                                      |
59| ---------- | ------------------------------------------ | ---------------------------------------- |
60| Platform   | iOS, Android, or both?                     | Affects navigation, gestures, typography |
61| Framework  | React Native, Flutter, or native?          | Determines performance and patterns      |
62| Navigation | Tabs, stack, drawer?                       | Core UX architecture                     |
63| Offline    | Must it work offline?                      | Data & sync strategy                     |
64| Devices    | Phone only or tablet too?                  | Layout & density rules                   |
65| Audience   | Consumer, enterprise, accessibility needs? | Touch & readability                      |
66 
67🚫 **Never default to your favorite stack or pattern.**
68 
69---
70 
71## 3. Mandatory Reference Reading (Enforced)
72 
73### Universal (Always Read First)
74 
75| File                          | Purpose                            | Status            |
76| ----------------------------- | ---------------------------------- | ----------------- |
77| **mobile-design-thinking.md** | Anti-memorization, context-forcing | 🔴 REQUIRED FIRST |
78| **touch-psychology.md**       | Fitts’ Law, thumb zones, gestures  | 🔴 REQUIRED       |
79| **mobile-performance.md**     | 60fps, memory, battery             | 🔴 REQUIRED       |
80| **mobile-backend.md**         | Offline sync, push, APIs           | 🔴 REQUIRED       |
81| **mobile-testing.md**         | Device & E2E testing               | 🔴 REQUIRED       |
82| **mobile-debugging.md**       | Native vs JS debugging             | 🔴 REQUIRED       |
83 
84### Platform-Specific (Conditional)
85 
86| Platform       | File                |
87| -------------- | ------------------- |
88| iOS            | platform-ios.md     |
89| Android        | platform-android.md |
90| Cross-platform | BOTH above          |
91 
92> ❌ If you haven’t read the platform file, you are not allowed to design UI.
93 
94---
95 
96## 4. AI Mobile Anti-Patterns (Hard Bans)
97 
98### 🚫 Performance Sins (Non-Negotiable)
99 
100| ❌ Never                   | Why                  | ✅ Always                                |
101| ------------------------- | -------------------- | --------------------------------------- |
102| ScrollView for long lists | Memory explosion     | FlatList / FlashList / ListView.builder |
103| Inline renderItem         | Re-renders all rows  | useCallback + memo                      |
104| Index as key              | Reorder bugs         | Stable ID                               |
105| JS-thread animations      | Jank                 | Native driver / GPU                     |
106| console.log in prod       | JS thread block      | Strip logs                              |
107| No memoization            | Battery + perf drain | React.memo / const widgets              |
108 
109---
110 
111### 🚫 Touch & UX Sins
112 
113| ❌ Never               | Why                  | ✅ Always          |
114| --------------------- | -------------------- | ----------------- |
115| Touch <44–48px        | Miss taps            | Min touch target  |
116| Gesture-only action   | Excludes users       | Button fallback   |
117| No loading state      | Feels broken         | Explicit feedback |
118| No error recovery     | Dead end             | Retry + message   |
119| Ignore platform norms | Muscle memory broken | iOS ≠ Android     |
120 
121---
122 
123### 🚫 Security Sins
124 
125| ❌ Never                | Why                | ✅ Always               |
126| ---------------------- | ------------------ | ---------------------- |
127| Tokens in AsyncStorage | Easily stolen      | SecureStore / Keychain |
128| Hardcoded secrets      | Reverse engineered | Env + secure storage   |
129| No SSL pinning         | MITM risk          | Cert pinning           |
130| Log sensitive data     | PII leakage        | Never log secrets      |
131 
132---
133 
134## 5. Platform Unification vs Divergence Matrix
135 
136```
137UNIFY                          DIVERGE
138──────────────────────────     ─────────────────────────
139Business logic                Navigation behavior
140Data models                    Gestures
141API contracts                  Icons
142Validation                     Typography
143Error semantics                Pickers / dialogs
144```
145 
146### Platform Defaults
147 
148| Element   | iOS          | Android        |
149| --------- | ------------ | -------------- |
150| Font      | SF Pro       | Roboto         |
151| Min touch | 44pt         | 48dp           |
152| Back      | Edge swipe   | System back    |
153| Sheets    | Bottom sheet | Dialog / sheet |
154| Icons     | SF Symbols   | Material Icons |
155 
156---
157 
158## 6. Mobile UX Psychology (Non-Optional)
159 
160### Fitts’ Law (Touch Reality)
161 
162* Finger ≠ cursor
163* Accuracy is low
164* Reach matters more than precision
165 
166**Rules:**
167 
168* Primary CTAs live in **thumb zone**
169* Destructive actions pushed away
170* No hover assumptions
171 
172---
173 
174## 7. Performance Doctrine
175 
176### React Native (Required Pattern)
177 
178```ts
179const Row = React.memo(({ item }) => (
180  <View><Text>{item.title}</Text></View>
181));
182 
183const renderItem = useCallback(
184  ({ item }) => <Row item={item} />,
185  []
186);
187 
188<FlatList
189  data={items}
190  renderItem={renderItem}
191  keyExtractor={(i) => i.id}
192  getItemLayout={(_, i) => ({
193    length: ITEM_HEIGHT,
194    offset: ITEM_HEIGHT * i,
195    index: i,
196  })}
197/>
198```
199 
200### Flutter (Required Pattern)
201 
202```dart
203class Item extends StatelessWidget {
204  const Item({super.key});
205 
206  @override
207  Widget build(BuildContext context) {
208    return const Text('Static');
209  }
210}
211```
212 
213* `const` everywhere possible
214* Targeted rebuilds only
215 
216---
217 
218## 8. Mandatory Mobile Checkpoint
219 
220Before writing **any code**, you must complete this:
221 
222```
223🧠 MOBILE CHECKPOINT
224 
225Platform:     ___________
226Framework:    ___________
227Files Read:   ___________
228 
2293 Principles I Will Apply:
2301.
2312.
2323.
233 
234Anti-Patterns I Will Avoid:
2351.
2362.
237```
238 
239❌ Cannot complete → go back and read.
240 
241---
242 
243## 9. Framework Decision Tree (Canonical)
244 
245```
246Need OTA + web team → React Native + Expo
247High-perf UI → Flutter
248iOS only → SwiftUI
249Android only → Compose
250```
251 
252No debate without justification.
253 
254---
255 
256## 10. Release Readiness Checklist
257 
258### Before Shipping
259 
260* [ ] Touch targets ≥ 44–48px
261* [ ] Offline handled
262* [ ] Secure storage used
263* [ ] Lists optimized
264* [ ] Logs stripped
265* [ ] Tested on low-end devices
266* [ ] Accessibility labels present
267* [ ] MFRI ≥ 3
268 
269---
270 
271## 11. Related Skills
272 
273* **frontend-design** – Visual systems & components
274* **frontend-dev-guidelines** – RN/TS architecture
275* **backend-dev-guidelines** – Mobile-safe APIs
276* **error-tracking** – Crash & performance telemetry
277 
278---
279 
280> **Final Law:**
281> Mobile users are distracted, interrupted, and impatient—often using one hand on a bad network with low battery.
282> **Design for that reality, or your app will fail quietly.**
283 
284---
285