Mobile Design System

Build for thumbs, not cursors. Respect the battery, respect the platform, survive offline. A phone is its own medium, not a shrunken desktop. Reason about the constraints first, then confirm the platform before you commit to anything.

Validation script

There is one helper script. Run it; you do not need to read its source.

Read the reference files first

Do not begin coding until you have opened the references that apply to the work in front of you. Each one goes deeper than the summaries below.

Read on every mobile task

The thinking guide comes before everything else. It is what keeps the output tailored to the project instead of generic.

Read the one that matches your target

iOS build? Open the iOS file. Android build? Open the Android file. Shipping both? Read both and branch on platform where it matters.

Ask before you assume

When the request is vague, resist filling the gaps with your personal favorites. Surface the open questions instead.

Patterns to avoid

These are the failure modes that show up most often in generated mobile code.

Performance

Touch and UX

Security — keep tokens out of AsyncStorage (use SecureStore / Keychain / EncryptedSharedPreferences); never hardcode API keys or log secrets; pin certificates in production.

Architecture — keep logic out of the view (service layer), default to local state and lift only when shared, plan deep links up front, and tear down every subscription and timer.

Unify or diverge by platform

Share what users never see; honor platform habits for what they touch.

Share across platforms          Split per platform
──────────────────────          ──────────────────
Business logic                  Back navigation (edge swipe vs system back)
Data + networking layer         Gesture feel
Core feature set                Iconography (SF Symbols vs Material)
                                Pickers (native date/time)
                                Sheets and dialogs
                                Type (SF Pro vs Roboto)
                                Alert conventions

Platform defaults at a glance

Reach and touch, in brief

Fingers are blunt where cursors are sharp. A fingertip covers roughly 7mm, so targets need real size and primary actions belong where the thumb naturally lands.

┌─────────────────────────────┐
│   stretch zone              │  back, menu, settings
├─────────────────────────────┤
│   comfortable zone          │  secondary actions, content
├─────────────────────────────┤
│   easy zone (thumb arc)     │  primary CTA, tab bar
└─────────────────────────────┘
          [ home ]

Mobile attention is also different: one task at a time, no hover state, frequent interruptions, slow text entry. Design for the interrupted user with one free hand. Full detail in touch-psychology.md.

Performance, in brief

Only animate transform and opacity (GPU-composited). Animating width, height, margin, padding, or top/left forces layout and drops frames.

React Native lists, the short version:

const Row = React.memo(({ item }: { item: Item }) => (
  <View style={styles.row}><Text>{item.title}</Text></View>
));

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

<FlatList
  data={rows}
  renderItem={renderRow}
  keyExtractor={(item) => item.id}     // stable id, never the index
  getItemLayout={(_, i) => ({ length: ROW_H, offset: ROW_H * i, index: i })}
  removeClippedSubviews
  maxToRenderPerBatch={10}
  windowSize={5}
/>

Flutter, the short version: mark anything static const, prefer builder lists, and rebuild narrowly with ValueListenableBuilder or a provider .select. Full guide in mobile-performance.md.

Before you write code

Answer these in your head (or out loud) first. If you cannot, you have not read enough of the references yet.

• Platform: iOS / Android / both?
• Framework: RN / Flutter / SwiftUI / Kotlin?
• Which reference files did you actually open?
• Three principles you will apply here.
• Two anti-patterns you will steer clear of.

Picking a framework

What is the project?
   ├── OTA updates + fast iteration + web-leaning team  → React Native + Expo
   ├── Bespoke pixel-perfect UI, performance-sensitive  → Flutter
   ├── Deep native, single platform
   │      ├── iOS only      → SwiftUI
   │      └── Android only  → Kotlin + Jetpack Compose
   ├── Already on React Native                          → React Native (bare)
   └── Already on Flutter                               → Flutter

Fuller trees (state, storage, offline, auth) live in decision-trees.md.

Checklists

Project kickoff — platform confirmed, framework chosen, navigation shape decided, state approach picked, offline needs understood, deep links planned, target devices defined.

Per screen — targets at least 44-48px, primary action within thumb reach, loading state present, error state with retry, offline behavior handled, platform conventions followed.

Pre-release — debug logs removed, secrets in secure storage, certificate pinning on, lists memoized with stable keys, listeners and timers cleaned up, verified on a low-end device, accessibility labels on every interactive element.

Picture the worst case: weak signal, one hand, glaring sun, a dying battery, a user who is already distracted. Build for that, and the easy cases take care of themselves.