Cursor rule

1---
2description: "Cross-platform mobile: Flutter, React Native, Expo. Load when editing mobile manifests, platform folders, or shared mobile architecture — not for everyday app logic."
3globs: ["**/*.dart", "**/pubspec.yaml", "**/pubspec.lock", "**/android/**", "**/ios/**", "**/App.tsx", "**/app.json", "**/app.config.*"]
4alwaysApply: false
5---
6 
7# Cross-Platform Mobile Development
8 
9Guidance for Flutter, React Native, and Expo projects. For general coding workflow, the always-on core **Code Discipline** and **App And Scaffold Discipline** sections are canonical — especially CLI-first scaffolding and verification.
10 
11Load this rule when globs match mobile project files. Identify the stack from manifests (`pubspec.yaml`, `package.json` + native folders, `app.json`) before choosing patterns. Do not hand-create `pubspec.yaml`, Xcode/Android project trees, or `.xcodeproj` / `.pbxproj` — use the framework CLI.
12 
13---
14 
15## Before Changing Mobile Code
16 
171. Identify stack: **Flutter**, **React Native**, **Expo**, or other.
182. Read manifest, entry point (`main.dart`, `App.tsx`), navigation setup, and existing state-management pattern.
193. Match platform folder conventions already in the repo — do not restructure unprompted.
204. For new dependencies or SDK versions, verify against current official docs before recommending.
21 
22---
23 
24## Scaffold & Verify (CLI-first)
25 
26| Stack | Create | Add deps | Typical verify |
27|-------|--------|----------|----------------|
28| Flutter | `flutter create` | `flutter pub add` | `flutter analyze`, `flutter test` |
29| React Native | `npx react-native init` | `npm install` | `npx react-native doctor`, build one platform |
30| Expo | `npx create-expo-app` | `npx expo install` | `npx expo doctor`, `npx expo start` |
31 
32After structural changes, run the stack's analyze/test/build check before claiming done.
33 
34---
35 
36## Architecture Quick Reference
37 
38**Good cross-platform fit:** content apps, business/productivity, MVPs, teams with web background, similar UI across platforms.
39 
40**Consider more native work when:** heavy AR/camera, games, deep OS integration, strict platform HIG, or performance-critical media pipelines.
41 
42| Framework | Best for | Watch out for |
43|-----------|----------|---------------|
44| Flutter | Custom UI, performance | App size, Dart ecosystem |
45| React Native | JS/TS teams, code share | Native modules, bridge overhead |
46| Expo | Fast iteration, managed workflow | Native module limits (unless dev client) |
47 
48**Share across platforms:** domain logic, models, API client, validation, most state logic.  
49**Keep platform-specific:** native permissions, push/deep links, store billing, platform UI chrome where HIG matters.
50 
51Layering (presentation → domain → data) applies; see `language-agnostic-patterns` when refactoring module boundaries.
52 
53---
54 
55## State & Navigation
56 
57- Reuse the pattern already in the repo (Provider, Riverpod, Bloc, Redux, Zustand, etc.) — do not introduce a second state library.
58- Navigation: one primary approach (go_router, React Navigation, Expo Router) per app; match existing route definitions.
59- Persist only what the product requires; handle offline/error states explicitly on mobile networks.
60 
61---
62 
63## Mobile Design Quality
64 
65Web design instincts do not transfer 1:1 to mobile. The judgment calls:
66 
67- **Platform type defaults are correct here.** SF Pro on iOS and Roboto on Android are the *native* choice, not slop — the web font bans in `anti-slop-design` apply to display/brand moments, not to app body text. Custom fonts earn their place on headings and brand surfaces only.
68- **Design for the thumb, not the cursor.** Primary actions in the bottom half of the screen; destructive actions away from habitual tap zones; nothing important hidden behind hover (there is none).
69- **Navigation follows platform grammar.** Bottom tabs for 3–5 top-level destinations; respect the Android back gesture and iOS swipe-back; use native share sheets, switches, and pickers instead of web-style rebuilds.
70- **Glanceability over density.** One primary piece of information per screen region; web dashboard density fails at arm's length on a 6-inch display.
71- **Loading is layout-shaped.** Skeletons that match the final layout; render cached/partial data immediately rather than blocking the screen on the full payload.
72- **Lists must be virtualized.** `FlatList` / `ListView.builder` with stable keys — never map an unbounded array into scroll children (also listed in traps; it is the #1 mobile perf bug).
73- **Motion at 60fps.** RN: `useNativeDriver` / Reanimated on the UI thread. Flutter: animate with `AnimatedBuilder`/implicit animations, not `setState` rebuilds of whole subtrees.
74 
75For visual direction (palette, tone, category), still load `anti-slop-design` — adapted through the platform conventions above.
76 
77---
78 
79## Platform Integration
80 
81- Request permissions at point of use with clear rationale; handle denied/permanent-deny flows.
82- Test on **both** iOS and Android when behavior is platform-specific — simulators/emulators are minimum proof; label device-only issues `unverified`.
83- Deep links, push, and IAP: follow each store's current guidelines; verify against official docs.
84 
85---
86 
87## Performance & Release
88 
89- Images/assets: appropriate resolution; lazy-load lists (avoid building unbounded scroll children).
90- Profile before optimizing (Flutter DevTools, RN Performance monitor).
91- Release: match existing signing, flavors/schemes, and store listing workflow in the repo — do not invent a new pipeline without asking.
92 
93---
94 
95## Common Traps
96 
97- Hand-written native project files instead of CLI output
98- Hover-only or desktop-sized touch targets (min ~44px)
99- Ignoring safe areas / notches / keyboard overlap
100- Blocking the UI thread with sync I/O or heavy work on the main isolate/thread
101- Adding native modules to Expo managed workflow without checking compatibility
102- Platform-specific code without `#ifdef` / `Platform.is` / conditional imports where the repo uses them
103 
104---
105 
106## Verification After Changes
107 
108| Change | Minimum proof |
109|--------|----------------|
110| Dart/TS logic | `flutter analyze` / lint + targeted test |
111| UI/layout | Run on one platform simulator; check safe area and scroll |
112| Native config | Build succeeds for affected platform (`flutter build`, `npx react-native run-ios`, etc.) |
113| Release/signing | `unverified` until user confirms store/TestFlight path |
114 
115For distinctive mobile UI polish, load `anti-slop-design` (category-aware layout, typography, motion).
116 
117---
118 
119## When NOT to Load This File
120 
121- Backend or web-only tasks — core **Code Discipline** is enough.
122- Greenfield framework choice with no repo context — inspect first, ask on real forks.
123