React Native Arc — Project Scaffolding Skill

You are scaffolding a new React Native (Expo) project using the arc-skill architecture.

Pre-Flight

1. Ask the user for:

   • Project name (used in app.json, package name, display name)
   • Brief description of the app (to inform screen/feature choices)
   • Target platforms: iOS only, Android only, or both
   • Whether they need i18n (internationalization) — default: yes
   • Whether they need authentication flow — default: yes
   • Which navigation pattern: tabs + stack (default) or stack only or drawer + stack

2. Context7 (mandatory): Ask the user to connect Context7 MCP server if not already configured. Use it to fetch the latest docs for:

   • react-native — core APIs and New Architecture
   • expo — SDK setup and latest modules
   • @react-navigation/native — navigation
   • @tanstack/react-query — server state
   • react-native-mmkv — storage
   • react-native-reanimated — animations

   Tell the user: "Do you have Context7 MCP connected? It fetches up-to-date library docs so the generated code uses the latest APIs. If not, add it: https://github.com/upstash/context7" If the user confirms they don't have it and don't want to add it, proceed with the architecture reference files.

3. Expo Skills (recommended): Check if the user has Expo community skills installed. If not, suggest they look into Expo's official documentation for AI-assisted development patterns covering native UI, deployment, and SDK upgrades.

4. Mobile Design Checkpoint (mandatory): Before writing any code, read skills/arc-skill/mobile-design/GUIDE.md and complete:

   Platform:   [iOS / Android / Both]
   Framework:  React Native (Expo)
   
   3 Principles I Will Apply:
   1. Touch-first (44pt+ targets, thumb zone aware)
   2. Platform-respectful (iOS HIG / Material Design 3)
   3. Performance-first (FlatList, Reanimated, memo)
   
   Anti-Patterns I Will Avoid:
   1. ScrollView for lists
   2. Hardcoded pixel values
   3. Inline styles / anonymous functions in render
   

Architecture Reference Files

Read the following skill files from skills/arc-skill/ to understand the full architecture before generating code:

Core Architecture:

1. project-structure.md — Complete folder structure
2. navigation.md — React Navigation patterns
3. theme.md — Theme system with color schemes
4. components.md — Component file structure & patterns
5. api-services.md — Axios HTTP client & API layer
6. storage.md — MMKV storage wrapper
7. state-management.md — React Query setup & patterns
8. performance.md — React Native performance best practices
9. providers.md — Provider stack architecture
10. typescript.md — TypeScript conventions
11. linting.md — ESLint, Prettier, Husky, lint-staged
12. i18n.md — Internationalization with Lingui

Mobile Design System (ALWAYS read — these are mandatory, not optional): 13. mobile-design/GUIDE.md — Master checklist & anti-patterns 14. mobile-design/touch-psychology.md — Touch targets, thumb zones, haptics 15. mobile-design/mobile-performance.md — Deep performance optimization 16. mobile-design/mobile-navigation.md — Navigation UX patterns 17. mobile-design/mobile-typography.md — Type scales, Dynamic Type 18. mobile-design/mobile-color-system.md — OLED, dark mode, contrast 19. mobile-design/platform-ios.md — iOS HIG specifics (read if targeting iOS) 20. mobile-design/platform-android.md — Material Design 3 specifics (read if targeting Android) 21. mobile-design/mobile-backend.md — Offline sync, push, auth patterns 22. mobile-design/decision-trees.md — Framework & architecture decisions 23. mobile-design/mobile-design-thinking.md — Anti-memorization, forces context-based thinking

Template Files

Read templates from skills/arc-skill/templates/ for code generation patterns:

• component.md — Component file templates
• screen.md — Screen file templates
• hook.md — Custom hook templates
• api-service.md — API service module templates

Execution Steps

Step 1: Initialize Expo Project

npx create-expo-app@latest <project-name> --template blank-typescript
cd <project-name>

Step 2: Install Core Dependencies

Always use npx expo install for Expo-compatible packages (resolves correct versions). Use latest — do NOT pin versions. Install in this order (groups can be parallel):

Navigation:

npx expo install @react-navigation/native @react-navigation/native-stack @react-navigation/bottom-tabs react-native-screens react-native-safe-area-context

State & Storage:

npx expo install @tanstack/react-query @tanstack/react-query-persist-client react-native-mmkv

HTTP:

npx expo install axios

UI & Animations:

npx expo install react-native-reanimated react-native-gesture-handler react-native-size-matters expo-blur expo-haptics expo-status-bar expo-image expo-splash-screen expo-font @expo/vector-icons react-native-keyboard-controller

Forms (if auth flow):

npx expo install formik yup

i18n (if enabled):

npm install @lingui/react @lingui/core
npm install -D @lingui/cli @lingui/macro @lingui/babel-plugin-lingui-macro
npx expo install expo-localization

Dev tools:

npm install -D typescript @types/react eslint prettier eslint-config-expo husky lint-staged babel-plugin-module-resolver

Verify compatibility:

npx expo doctor

Fix any version mismatches before proceeding. Follow expo doctor recommendations.

Step 3: Generate Project Structure

Create the full src/ directory structure as defined in project-structure.md.

Step 4: Generate Core Files

Generate files in this order (respecting dependencies):

1. Types (src/types/) — Base type definitions
2. Constants (src/constants/) — App constants, keys, platform utils
3. Theme (src/theme/) — Theme definitions, interfaces, fonts
4. Storage (src/store/storage/) — MMKV storage wrappers
5. API Client (src/api/http/index.ts) — Axios instance with interceptors
6. API Modules (src/api/http/) — Auth, profile, etc.
7. Store Services (src/store/services/) — React Query client, hooks
8. Hooks (src/hooks/) — useAppTheme, useAppNavigation, useStyles
9. Providers (src/providers/) — AppInitialization, i18n
10. Components (src/components/) — Shared UI components
11. Screens (src/screens/) — App screens
12. Navigation (src/navigation/) — Navigator setup
13. App Entry (src/app.tsx) — Root component with provider stack
14. i18n (src/locale/) — If i18n enabled

Step 5: Configure Build Tools

• Update tsconfig.json with path aliases (see typescript.md)
• Update babel.config.js for reanimated + lingui + module-resolver plugins
• Create ESLint config, .prettierrc, .prettierignore (see linting.md)
• Set up Husky + lint-staged for pre-commit hooks (see linting.md)
• Add lint, format, typecheck, check scripts to package.json
• Create .env.example
• Update app.json with project metadata + enable React Compiler:

  { "expo": { "experiments": { "reactCompiler": true } } }
  

Step 6: Verify

npx react-compiler-healthcheck@latest
npx expo doctor
npx expo start

Important Rules

Architecture:

• Always use the component file structure from components.md — separate files for styles, types, constants
• Always use react-native-size-matters moderateScale — never hardcode pixel sizes
• Always type navigation — use typed useAppNavigation() hook
• Always use the useStyles() hook — never call StyleSheet.create directly in components
• Follow the barrel export pattern — every folder has an index.ts
• API calls go through React Query — never call API functions directly from components
• Storage access through typed wrappers — never use MMKV directly in components

Mobile UX (from mobile-design system):

• Touch targets minimum 44pt (iOS) / 48dp (Android) — see touch-psychology.md
• Primary CTAs in thumb-friendly zone (bottom of screen)
• Never gesture-only interactions — always provide visible button alternative
• Haptic feedback for meaningful interactions
• Support Dynamic Type / font scaling — use sp on Android
• Dark mode: use #121212 not pure #000000 for surfaces (avoid OLED smearing)
• Text contrast minimum 4.5:1 (WCAG AA)
• Platform-respectful: iOS follows HIG, Android follows Material Design 3

Performance (from performance.md + mobile-performance.md):

• FlatList for lists — never ScrollView for dynamic/long lists
• Reanimated for animations (UI thread) — never Animated API for complex animations
• expo-image instead of React Native Image — with caching and blurhash
• freezeOnBlur on tab screens
• Clean up timers, listeners, subscriptions in useEffect cleanup
• Remove all console.log before production
• React Compiler handles memoization — do NOT manually add React.memo, useCallback, or useMemo