Mobile Design

Mobile Design System

(Mobile-First · Touch-First · Platform-Respectful)

Philosophy: Touch-first. Battery-conscious. Platform-respectful. Offline-capable. 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.

---

1. Scope and risk

Use the existing project/platform requirements and preserve its conventions. Ask only for missing information that changes the implementation. Do not require an interview or framework switch for a targeted fix. The former MFRI score was an unvalidated heuristic with inconsistent dimensions/range; it is not a safety or release gate. Record concrete interaction, data, accessibility and performance risks instead.

2. Choose the relevant checks

For a new app, establish platform, framework, audience, device classes, navigation, offline needs and actual output. For existing work, reuse that context. Read only the reference material needed for the changed behavior. User scope and repository instructions take precedence over this skill's suggested ceremony.

3. Mandatory Reference Reading (Enforced)

Reference map (read what the task needs)

File	Purpose	Status
mobile-design-thinking.md	Anti-memorization, context-forcing	Context reference
touch-psychology.md	Fitts’ Law, thumb zones, gestures	Task-dependent
mobile-performance.md	60fps, memory, battery	Task-dependent
mobile-backend.md	Offline sync, push, APIs	Task-dependent
mobile-testing.md	Device & E2E testing	Task-dependent
mobile-debugging.md	Native vs JS debugging	Task-dependent

Platform-Specific (Conditional)

Platform	File
iOS	platform-ios.md
Android	platform-android.md
Cross-platform	BOTH above

Read the relevant platform guidance before changing platform-specific behavior.

---

4. AI Mobile Anti-Patterns (Hard Bans)

🚫 Performance Sins (Non-Negotiable)

❌ Never	Why	✅ Always
ScrollView for long lists	Memory explosion	FlatList / FlashList / ListView.builder
Unmeasured row churn	May cause avoidable work	Profile identity/state updates; memoize only where useful
Index as key	Reorder bugs	Stable ID
JS-thread animations	Jank	Native driver / GPU
console.log in prod	JS thread block	Strip logs
Blanket memoization claims	Can add complexity without benefit	Profile and apply targeted optimization

---

🚫 Touch & UX Sins

❌ Never	Why	✅ Always
Undersized hit area	Miss taps	Use platform logical units: typically 44pt iOS / 48dp Android
Gesture-only action	Excludes users	Button fallback
No loading state	Feels broken	Explicit feedback
No error recovery	Dead end	Retry + message
Ignore platform norms	Muscle memory broken	iOS ≠ Android

---

🚫 Security Sins

❌ Never	Why	✅ Always
Tokens in AsyncStorage	Easily stolen	SecureStore / Keychain
Embedded app secrets	Can be extracted	Keep server secrets on server; secure per-user credentials
Disabled TLS verification	MITM risk	Valid platform TLS; pinning only for a justified managed threat model
Log sensitive data	PII leakage	Never log secrets

---

5. Platform Unification vs Divergence Matrix

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 (fixed-height illustrative pattern)

const Row = React.memo(({ item }) => (
  <View><Text>{item.title}</Text></View>
));

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

<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={(i) => i.id}
  getItemLayout={(_, i) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * i,
    index: i,
  })}
/>

Flutter (illustrative static widget)

class Item extends StatelessWidget {
  const Item({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text('Static');
  }
}

• const everywhere possible
• Targeted rebuilds only

---

8. Implementation evidence

State the target platform, changed behavior and checks actually performed. Profile representative devices/data; a static pattern scan cannot measure touch targets, contrast, frame rate, battery, platform navigation or secure storage behavior.

9. Framework choice

Preserve an existing stack unless a change is requested. For new work compare team experience, native integrations, accessibility, deployment policies and measured workload constraints. Expo OTA is bounded by runtime compatibility and store policies; it does not authorize bypassing review or delivering arbitrary native code. No framework is universally fastest or smallest.

10. Release Readiness Checklist

Before Shipping

• Platform hit targets checked in logical units
• Offline handled
• Secure storage used
• Lists optimized
• Logs stripped
• Tested on low-end devices
• Accessibility labels present
• Concrete risks and any unavailable checks documented

---

11. Related Skills

• frontend-design – Visual systems & components
• frontend-dev-guidelines – RN/TS architecture
• backend-dev-guidelines – Mobile-safe APIs
• error-tracking – Crash & performance telemetry

---

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.

---

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Audit helper and limits

Run python scripts/mobile_audit.py . --json from the intended project directory. The helper is read-only, bounded and advisory. It never imports project code and never declares compliance; compliant is null. Exit 2 means incomplete inspection or no detected mobile source. Source-pattern hints can match comments or miss behavior spread across files. Validate findings before editing. No simulator, real-device, screen-reader or GPU run was performed in this catalog review.

Use touch guidance, typography, color, navigation and decisions for focused checks. Code blocks are version-sensitive fragments, not certified complete apps; verify current APIs before execution.