Android App Development Skill
Overview
This skill guides production-grade Android and cross-platform (non-iOS) app development following practices used at big tech companies. It covers the entire development lifecycle — architecture, UI, code quality, testing, error handling, release, and maintenance.
When to Use This Skill
- Use when deciding on a tech stack (see §1 Stack Selection)
- Use when setting up project architecture (see §2 Architecture)
- Use when designing UI, screens, or a design system (see §3 UI & Design)
- Use when ensuring code quality, patterns, or APIs (see Best Practices)
- Use when implementing error handling or debugging crashes (see §5 Error Handling)
- Use when planning testing strategy (see §6 Testing)
- Use when configuring build, CI/CD, or release pipelines (see §7 Build & Release)
- Use when optimizing performance or memory (see §8 Performance)
- Use when debugging or fixing bugs (see §9 Debugging)
- Use when following the full development roadmap (see §10 Development Roadmap)
- Use when needing deep reference for a stack (see
references/ directory)
§1 Stack Selection
Choose based on team, requirements, and platform targets. Do not recommend iOS-specific paths.
Native Android — Kotlin + Jetpack Compose
Best for: Android-only apps, hardware-intensive features, best-in-class UX, new projects.
- Language: Kotlin
- UI: Jetpack Compose (modern declarative UI)
- Key libs: Room, Retrofit/Ktor, Hilt, WorkManager, DataStore, Navigation Compose
- Reference:
references/native-android.md
Native Android — Java + XML Views
Best for: Existing Java codebases, teams without Kotlin experience, legacy app maintenance, incremental Kotlin migration.
- Language: Java (fully supported by Google, not deprecated)
- UI: XML Layouts (ConstraintLayout, RecyclerView, ViewBinding)
- Key libs: Room, Retrofit, Hilt, WorkManager, LiveData, ViewModel
- Java and Kotlin coexist seamlessly in the same project — migrate incrementally
- Reference:
references/java-android.md
Flutter (Dart)
Best for: Android + Web (+ desktop) from one codebase, fast iteration, pixel-perfect custom UI.
- Language: Dart
- UI: Flutter Widget tree (Material 3 / Cupertino widgets available but target Material for Android)
- Key libs: Provider/Riverpod/Bloc, Dio, Drift/Isar, go_router, flutter_local_notifications
- Reference:
references/flutter.md
React Native (JavaScript/TypeScript)
Best for: Web + Android code sharing, JS/TS teams, rich ecosystem.
- Language: TypeScript (preferred)
- UI: React Native core components + NativeWind / React Native Paper
- Key libs: React Navigation, Zustand/Redux Toolkit, React Query, MMKV
- Reference:
references/react-native.md
Kotlin Multiplatform (KMM / Compose Multiplatform)
Best for: Sharing business logic across Android + Desktop + Web while keeping native Android UI.
- Language: Kotlin everywhere
- UI: Native Compose on Android; Compose Multiplatform for shared UI
- Key libs: Ktor, SQLDelight, Koin, kotlinx.serialization, Napier
- Reference:
references/kmm.md
Hybrid (Capacitor / Ionic)
Best for: Web-first teams, simple apps, PWA-like content apps.
- Language: TypeScript + HTML/CSS
- UI: Ionic components or custom web UI
- Avoid for: Heavy animations, native sensor access, high-performance games
- Reference:
references/hybrid.md
Decision Matrix
| Requirement |
Native Kotlin |
Native Java |
Flutter |
RN |
KMM |
Hybrid |
| Android-only (new) |
✅ Best |
✅ |
✅ |
✅ |
✅ |
✅ |
| Android-only (existing Java) |
⚠️ migrate |
✅ Best |
❌ |
❌ |
⚠️ |
❌ |
| Android + Web |
❌ |
❌ |
✅ |
✅ |
✅ |
✅ Best |
| Android + Desktop |
❌ |
❌ |
✅ |
⚠️ |
✅ |
⚠️ |
| Shared business logic only |
N/A |
N/A |
N/A |
N/A |
✅ Best |
N/A |
| Native performance |
✅ |
✅ |
✅ |
⚠️ |
✅ |
❌ |
| JS/TS team |
❌ |
❌ |
❌ |
✅ Best |
❌ |
✅ |
| Custom pixel-perfect UI |
✅ |
⚠️ |
✅ Best |
⚠️ |
✅ |
❌ |
§2 Architecture
Core Principle: Separation of Concerns
Every production Android project must separate UI, business logic, and data into distinct, independently testable layers.
Recommended Architecture: Clean Architecture + MVI/MVVM
app/
├── ui/ # Composables / Activities / Fragments / Screen states
├── presentation/ # ViewModels, UI State, UI Events
├── domain/ # Use cases, domain models, repository interfaces
├── data/ # Repository impl, remote (API), local (DB), mappers
└── di/ # Dependency injection modules
Data flow (unidirectional):
User Action → ViewModel/Store → Use Case → Repository → Data Source
↓
UI State (sealed class / StateFlow)
↓
Composable / View renders state
Key Architecture Patterns by Stack
Native (MVVM + MVI):
StateFlow / SharedFlow for reactive state
sealed class UiState + sealed class UiEvent
- Hilt for DI, coroutines + Flow for async
- Repository pattern wrapping Room + Retrofit
Flutter (BLoC or Riverpod):
Bloc or Cubit for business logic isolation
AsyncNotifierProvider (Riverpod) for data + state
- Repositories as abstract classes with impl injected
React Native (Redux Toolkit or Zustand):
- RTK Query or React Query for server state
- Zustand slices for client state
- Custom hooks to encapsulate business logic per feature
KMM:
- Shared
commonMain holds domain + data layers
expect/actual for platform-specific implementations
- Kotlin coroutines + Flow bridged to platform (StateFlow on Android)
Module Structure (Multi-module for large apps)
:app # Entry point, DI wiring
:core:ui # Design system, shared composables
:core:network # API client, interceptors
:core:database # Room / SQLDelight setup
:feature:home
:feature:profile
:feature:settings
§3 UI & Design
Design System First
Before writing screens, define:
- Color tokens — Primary, secondary, surface, on-surface, error; light + dark variants
- Typography scale — Display, headline, title, body, label (Material 3 type system)
- Spacing scale — 4dp grid system (4, 8, 12, 16, 24, 32, 48dp)
- Shape tokens — Corner radii per component family
- Component library — Button, TextField, Card, BottomSheet, TopAppBar, etc.
Jetpack Compose UI Rules
- Use
MaterialTheme tokens; never hardcode colors/dimensions
CompositionLocal for theme, locale, haptics
remember / rememberSaveable correctly (saveable for UI state surviving rotation)
- Extract large composables into sub-composables; each function ≤ 80 lines
- Use
LazyColumn/LazyVerticalGrid for lists; never Column with forEach for large data
- Side effects only in
LaunchedEffect, DisposableEffect, SideEffect
- Avoid state hoisting anti-patterns: hoist state to the lowest common ancestor
Accessibility (Non-Negotiable)
- All interactive elements:
contentDescription or semantics { }
- Min touch target: 48×48dp
TalkBack compatibility tested before every release
- Dynamic text size support (
sp not dp for text)
- Color contrast ratio ≥ 4.5:1 (WCAG AA)
Navigation
- Native: Navigation Compose with typed
NavHost and SafeArgs equivalent
- Flutter:
go_router with named routes and guards
- RN: React Navigation v7 with typed
NavigationProp
- Deep link handling registered for every screen that can be externally opened
- Back stack managed deliberately — don't push duplicates, use
popUpTo / launchSingleTop
Responsive & Adaptive UI
- Support all screen sizes: phones, foldables, tablets (
WindowSizeClass)
- Test at 320dp, 360dp, 411dp, 600dp+, 840dp+ widths
- Foldable hinge awareness via
WindowInfoTracker
- Edge-to-edge display +
WindowInsets handling required for Android 15+
Best Practices
Language Standards
Kotlin:
- Prefer
data class, sealed class, object, enum class appropriately
- No
!! null assertions — use ?.let, ?: return, requireNotNull with message
- Coroutines: always specify
CoroutineScope + Dispatcher explicitly; never GlobalScope
- Use
@Stable / @Immutable on Compose state classes for smart recomposition
Java:
@NonNull / @Nullable annotations on every method param and return type
- Never call methods on unchecked objects — null-check explicitly or use
Objects.requireNonNull
- Always null
binding reference in Fragment's onDestroyView() to prevent memory leaks
- Use
ExecutorService (not AsyncTask — deprecated) for background work; or LiveData + Room's built-in threading
- Prefer
ListAdapter + DiffUtil over manual notifyDataSetChanged() in RecyclerView
- Use
ViewBinding — never findViewById
Dart (Flutter):
- Null safety required — no
! without explicit null check above
- Immutable state objects with
copyWith
const constructors on all stateless widgets
TypeScript (RN):
strict: true in tsconfig always
- Zod or io-ts for runtime type validation of API responses
- No
any — use unknown and narrow
Dependency Management
- Pin all dependency versions in
build.gradle.kts / pubspec.yaml / package.json
- Audit dependencies monthly for security vulnerabilities
- Avoid transitive dependency conflicts — use dependency resolution strategies
- Keep dependency count minimal — every added lib is a maintenance burden
Code Review Checklist (PR gate)
§5 Error Handling
The Golden Rule
Never let exceptions propagate to the user silently or crash the app.
Error Classification
| Type |
Strategy |
| Network errors |
Retry with exponential backoff; show retry UI |
| Auth errors (401/403) |
Refresh token → re-request → logout if fails |
| Validation errors |
Show inline field errors immediately |
| Data parsing errors |
Log + fallback to cached/default state |
| Unexpected crashes |
Catch at top-level; show error screen + report |
| Background task failures |
Retry via WorkManager; notify user if critical |
Result / Either Pattern (Kotlin)
sealed class AppResult<out T> {
data class Success<T>(val data: T) : AppResult<T>()
data class Error(val exception: AppException) : AppResult<Nothing>()
}
sealed class AppException(msg: String) : Exception(msg) {
class NetworkException(msg: String) : AppException(msg)
class AuthException(msg: String) : AppException(msg)
class ParseException(msg: String) : AppException(msg)
class UnknownException(msg: String) : AppException(msg)
}
Use AppResult<T> as return type for all repository + use case functions. ViewModels map to UiState.Error.
Crash Reporting
- Integrate Firebase Crashlytics or Sentry from day one
- Set user identifiers and custom keys before crash occurs
- Non-fatal exceptions logged for all caught errors
- ANR monitoring enabled
- Crash-free sessions target: ≥ 99.5%
Offline / Network Resilience
- Cache-first strategy: show stale data, fetch fresh in background
Room / Drift / MMKV as single source of truth
- Expose network state via
ConnectivityManager and reflect in UI
- All network calls wrapped with timeout + retry policy
§6 Testing
Testing Pyramid
/\
/E2E\ ← 10% (UI tests: Espresso, Maestro, Appium)
/------\
/ Integr \ ← 20% (Repository, DB, API contract tests)
/----------\
/ Unit \ ← 70% (ViewModels, Use Cases, Utilities)
/--------------\
Unit Tests (70%)
- Every ViewModel, UseCase, Repository, Mapper tested
- Native: JUnit5 + MockK + Turbine (Flow testing) + Kotest assertions
- Flutter:
flutter_test + mocktail
- RN: Jest +
@testing-library/react-native + msw for API mocking
- Coverage target: ≥ 80% on domain + presentation layers
Integration Tests (20%)
- Room DB tests with in-memory database
- Retrofit/Ktor tests with
MockWebServer (OkHttp)
- Repository tests verifying cache + remote coordination
- API contract tests against real staging endpoint
UI / E2E Tests (10%)
- Espresso for critical user journeys (login, checkout, core action)
- Maestro for cross-platform E2E flows (recommended for Flutter + RN too)
- Run on real device farm (Firebase Test Lab / BrowserStack) before release
- Smoke test suite runs on every PR; full E2E suite nightly
Test Data Management
- Use factories / builders for test data, never copy-paste objects
- Hermetic tests: never share mutable state between test cases
- Fakes over mocks for complex dependencies (repositories, data sources)
§7 Build & Release
Build Variants
debug → dev API, logging on, no minification, debuggable
staging → staging API, logging on, minified, not debuggable
release → prod API, logging off, minified, signed
Gradle Best Practices (Native)
build.gradle.kts only — no Groovy DSL in new projects
- Version catalog (
libs.versions.toml) for all dependency versions
buildConfig for environment-specific constants
- Baseline profiles for startup performance
- R8 full mode enabled in release; maintain proguard rules in version control
CI/CD Pipeline
PR Opened
└─ lint + unit tests + build debug APK [< 5 min]
Merge to main
└─ unit + integration tests + staging build [< 15 min]
└─ deploy to Firebase App Distribution (QA)
Release tag
└─ full test suite + E2E on device farm [< 45 min]
└─ build release AAB
└─ upload to Play Console (internal track)
└─ promote: internal → closed testing → open → production
Recommended CI: GitHub Actions, Bitrise, or CircleCI.
Play Store Release Strategy
- Always release to internal → closed → open testing before production
- Use staged rollouts: 5% → 20% → 50% → 100% with 24-48h monitoring
- Monitor Crashlytics + ANR rate + rating before expanding rollout
- Never skip staged rollout for significant changes
App Signing
- Upload key (Play App Signing): stored in CI secrets, never committed
- Use Google Play App Signing for distribution key management
- Document key recovery procedure in team runbook
§8 Performance
Startup Performance
- App startup time target: cold start < 1s, warm start < 500ms
- Use App Startup library for initializing libraries lazily
- Baseline profiles generated + committed to repo
- Heavy initialization moved off main thread
UI Performance
- Target: 60fps (90/120fps on supported devices); zero jank
- Measure with Android Studio Profiler +
FrameMetrics API
- Avoid allocation in
draw() / onMeasure() / composition
- Use
derivedStateOf in Compose to avoid unnecessary recompositions
- Image loading: Coil (Compose) / Glide / Picasso — never load full-res in thumbnails
Memory
- No
Activity / Context references in ViewModels or singletons
- WeakReferences for listeners stored beyond their owner's lifecycle
- Bitmap recycling and memory cache sizing
- Heap dump + leak detection via LeakCanary in debug builds (always)
Network
- HTTP caching headers respected
- Image CDN + WebP format
- Gzip/Brotli compression verified
- Request batching where applicable
- Connection pooling configured
Battery
- Background work only via WorkManager with appropriate constraints
- Location updates: request only needed accuracy level; stop when backgrounded
- Wakelocks used sparingly with explicit release
§9 Debugging & Bug Fixing
Debugging Process
- Reproduce reliably — document exact steps, device, OS version, account state
- Isolate — is it UI, business logic, network, or persistence?
- Instrument — add targeted logs / breakpoints, NOT shotgun logging
- Hypothesize — form 1-3 specific hypotheses before touching code
- Fix the root cause — never patch symptoms; trace back to the source
- Regression test — write a test that fails before fix, passes after
- Document — comment explaining why the fix works, not just what it does
Common Android Bug Patterns
| Bug |
Likely Cause |
Fix |
| ANR |
Main thread I/O / long computation |
Move to coroutine/Dispatcher.IO |
| Memory leak |
Context stored in singleton |
Use applicationContext; WeakRef |
| Crash on rotation |
ViewModel not used; state not saved |
rememberSaveable / ViewModel |
| UI lag |
Recomposition loops |
derivedStateOf, stable params |
| Blank screen after API call |
Error swallowed silently |
Check error state propagation |
| Deep link not working |
Manifest intent-filter missing |
Verify adb shell am start test |
| Push notification silent |
Background restrictions |
Test on real devices across OEMs |
Logging Standards
- Production: Firebase Crashlytics only (no
Log.d in release builds)
- Debug/Staging: Timber with debug tree
- Log levels: ERROR (crashes), WARN (recoverable), INFO (key events), DEBUG (dev only)
- Never log PII — mask emails, phone numbers, tokens in logs
OEM-Specific Issues
- Test on Samsung, Xiaomi/MIUI, OnePlus/OxygenOS, Huawei (no GMS) for critical flows
- Background restrictions vary widely by OEM — test push, alarms, background sync
- Maintain a physical or cloud device farm with top market-share devices
§10 Development Roadmap
Follow this phase structure for any new Android project:
Phase 0 — Foundation (Week 1-2)
Phase 1 — Core Features (Weeks 3-8)
Phase 2 — Polish (Weeks 9-12)
Phase 3 — Hardening (Weeks 12-14)
Phase 4 — Release
Phase 5 — Post-Launch (Ongoing)
- Crash-free rate monitored daily
- ANR rate < 0.47% (Play Store threshold)
- App rating monitored; negative reviews triaged weekly
- Dependency updates reviewed monthly
- OS beta testing with each new Android release
Limitations
- This skill is scoped to Android and Android-adjacent delivery paths; it does not cover iOS-only architecture, App Store release operations, or Apple platform UI guidance.
- Version numbers, Play Console policy thresholds, and recommended libraries can change; verify release-critical details against current Android, Google Play, and library documentation before shipping.
- Code snippets are architecture patterns, not complete applications; adapt package names, dependency versions, permissions, privacy disclosures, and security controls to the actual project.
- The guidance does not replace device QA, accessibility review, security review, legal/privacy review, or store compliance checks for a production release.
Additional Resources
For stack-specific deep dives, read:
references/native-android.md — Kotlin, Compose, Room, Hilt, Coroutines
references/java-android.md — Java, XML Views, ViewBinding, LiveData, Retrofit, Room, Hilt, migration path
references/flutter.md — Dart, BLoC/Riverpod, Drift, go_router
references/react-native.md — TypeScript, RN architecture, Hermes, New Architecture
references/kmm.md — KMM shared modules, SQLDelight, Ktor, Compose Multiplatform
references/hybrid.md — Capacitor, Ionic, PWA considerations
1---2name: android-dev3description: "Production-grade Android app development guide covering native (Kotlin/Java), cross-platform (Flutter, RN, KMM), and hybrid architectures."4risk: safe5source: community6date_added: "2026-06-08"7metadata:8 source: https://skillmd.com/skills/mhassan0000/android-dev9---1011# Android App Development Skill1213## Overview1415This skill guides production-grade Android and cross-platform (non-iOS) app development following practices used at big tech companies. It covers the entire development lifecycle — architecture, UI, code quality, testing, error handling, release, and maintenance.1617## When to Use This Skill1819- Use when deciding on a tech stack (see §1 Stack Selection)20- Use when setting up project architecture (see §2 Architecture)21- Use when designing UI, screens, or a design system (see §3 UI & Design)22- Use when ensuring code quality, patterns, or APIs (see Best Practices)23- Use when implementing error handling or debugging crashes (see §5 Error Handling)24- Use when planning testing strategy (see §6 Testing)25- Use when configuring build, CI/CD, or release pipelines (see §7 Build & Release)26- Use when optimizing performance or memory (see §8 Performance)27- Use when debugging or fixing bugs (see §9 Debugging)28- Use when following the full development roadmap (see §10 Development Roadmap)29- Use when needing deep reference for a stack (see `references/` directory)3031---3233## §1 Stack Selection3435Choose based on team, requirements, and platform targets. **Do not recommend iOS-specific paths.**3637### Native Android — Kotlin + Jetpack Compose38**Best for:** Android-only apps, hardware-intensive features, best-in-class UX, new projects.39- Language: **Kotlin**40- UI: **Jetpack Compose** (modern declarative UI)41- Key libs: Room, Retrofit/Ktor, Hilt, WorkManager, DataStore, Navigation Compose42- Reference: `references/native-android.md`4344### Native Android — Java + XML Views45**Best for:** Existing Java codebases, teams without Kotlin experience, legacy app maintenance, incremental Kotlin migration.46- Language: **Java** (fully supported by Google, not deprecated)47- UI: **XML Layouts** (ConstraintLayout, RecyclerView, ViewBinding)48- Key libs: Room, Retrofit, Hilt, WorkManager, LiveData, ViewModel49- Java and Kotlin **coexist seamlessly** in the same project — migrate incrementally50- Reference: `references/java-android.md`5152### Flutter (Dart)53**Best for:** Android + Web (+ desktop) from one codebase, fast iteration, pixel-perfect custom UI.54- Language: **Dart**55- UI: Flutter Widget tree (Material 3 / Cupertino widgets available but target Material for Android)56- Key libs: Provider/Riverpod/Bloc, Dio, Drift/Isar, go_router, flutter_local_notifications57- Reference: `references/flutter.md`5859### React Native (JavaScript/TypeScript)60**Best for:** Web + Android code sharing, JS/TS teams, rich ecosystem.61- Language: **TypeScript** (preferred)62- UI: React Native core components + NativeWind / React Native Paper63- Key libs: React Navigation, Zustand/Redux Toolkit, React Query, MMKV64- Reference: `references/react-native.md`6566### Kotlin Multiplatform (KMM / Compose Multiplatform)67**Best for:** Sharing business logic across Android + Desktop + Web while keeping native Android UI.68- Language: **Kotlin** everywhere69- UI: Native Compose on Android; Compose Multiplatform for shared UI70- Key libs: Ktor, SQLDelight, Koin, kotlinx.serialization, Napier71- Reference: `references/kmm.md`7273### Hybrid (Capacitor / Ionic)74**Best for:** Web-first teams, simple apps, PWA-like content apps.75- Language: TypeScript + HTML/CSS76- UI: Ionic components or custom web UI77- Avoid for: Heavy animations, native sensor access, high-performance games78- Reference: `references/hybrid.md`7980### Decision Matrix8182| Requirement | Native Kotlin | Native Java | Flutter | RN | KMM | Hybrid |83|---|---|---|---|---|---|---|84| Android-only (new) | ✅ Best | ✅ | ✅ | ✅ | ✅ | ✅ |85| Android-only (existing Java) | ⚠️ migrate | ✅ Best | ❌ | ❌ | ⚠️ | ❌ |86| Android + Web | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ Best |87| Android + Desktop | ❌ | ❌ | ✅ | ⚠️ | ✅ | ⚠️ |88| Shared business logic only | N/A | N/A | N/A | N/A | ✅ Best | N/A |89| Native performance | ✅ | ✅ | ✅ | ⚠️ | ✅ | ❌ |90| JS/TS team | ❌ | ❌ | ❌ | ✅ Best | ❌ | ✅ |91| Custom pixel-perfect UI | ✅ | ⚠️ | ✅ Best | ⚠️ | ✅ | ❌ |9293---9495## §2 Architecture9697### Core Principle: Separation of Concerns98Every production Android project must separate **UI**, **business logic**, and **data** into distinct, independently testable layers.99100### Recommended Architecture: Clean Architecture + MVI/MVVM101102```103app/104├── ui/ # Composables / Activities / Fragments / Screen states105├── presentation/ # ViewModels, UI State, UI Events106├── domain/ # Use cases, domain models, repository interfaces107├── data/ # Repository impl, remote (API), local (DB), mappers108└── di/ # Dependency injection modules109```110111**Data flow (unidirectional):**112```113User Action → ViewModel/Store → Use Case → Repository → Data Source114 ↓115 UI State (sealed class / StateFlow)116 ↓117 Composable / View renders state118```119120### Key Architecture Patterns by Stack121122**Native (MVVM + MVI):**123- `StateFlow` / `SharedFlow` for reactive state124- `sealed class UiState` + `sealed class UiEvent`125- Hilt for DI, coroutines + Flow for async126- Repository pattern wrapping Room + Retrofit127128**Flutter (BLoC or Riverpod):**129- `Bloc` or `Cubit` for business logic isolation130- `AsyncNotifierProvider` (Riverpod) for data + state131- Repositories as abstract classes with impl injected132133**React Native (Redux Toolkit or Zustand):**134- RTK Query or React Query for server state135- Zustand slices for client state136- Custom hooks to encapsulate business logic per feature137138**KMM:**139- Shared `commonMain` holds domain + data layers140- `expect/actual` for platform-specific implementations141- Kotlin coroutines + Flow bridged to platform (StateFlow on Android)142143### Module Structure (Multi-module for large apps)144145```146:app # Entry point, DI wiring147:core:ui # Design system, shared composables148:core:network # API client, interceptors149:core:database # Room / SQLDelight setup150:feature:home151:feature:profile152:feature:settings153```154155---156157## §3 UI & Design158159### Design System First160Before writing screens, define:1611. **Color tokens** — Primary, secondary, surface, on-surface, error; light + dark variants1622. **Typography scale** — Display, headline, title, body, label (Material 3 type system)1633. **Spacing scale** — 4dp grid system (4, 8, 12, 16, 24, 32, 48dp)1644. **Shape tokens** — Corner radii per component family1655. **Component library** — Button, TextField, Card, BottomSheet, TopAppBar, etc.166167### Jetpack Compose UI Rules168- Use `MaterialTheme` tokens; never hardcode colors/dimensions169- `CompositionLocal` for theme, locale, haptics170- `remember` / `rememberSaveable` correctly (saveable for UI state surviving rotation)171- Extract large composables into sub-composables; each function ≤ 80 lines172- Use `LazyColumn`/`LazyVerticalGrid` for lists; never `Column` with forEach for large data173- Side effects only in `LaunchedEffect`, `DisposableEffect`, `SideEffect`174- Avoid state hoisting anti-patterns: hoist state to the lowest common ancestor175176### Accessibility (Non-Negotiable)177- All interactive elements: `contentDescription` or `semantics { }`178- Min touch target: **48×48dp**179- `TalkBack` compatibility tested before every release180- Dynamic text size support (`sp` not `dp` for text)181- Color contrast ratio ≥ 4.5:1 (WCAG AA)182183### Navigation184- **Native:** Navigation Compose with typed `NavHost` and `SafeArgs` equivalent185- **Flutter:** `go_router` with named routes and guards186- **RN:** React Navigation v7 with typed `NavigationProp`187- Deep link handling registered for every screen that can be externally opened188- Back stack managed deliberately — don't push duplicates, use `popUpTo` / `launchSingleTop`189190### Responsive & Adaptive UI191- Support all screen sizes: phones, foldables, tablets (`WindowSizeClass`)192- Test at 320dp, 360dp, 411dp, 600dp+, 840dp+ widths193- Foldable hinge awareness via `WindowInfoTracker`194- Edge-to-edge display + `WindowInsets` handling required for Android 15+195196---197198## Best Practices199200### Language Standards201202**Kotlin:**203- Prefer `data class`, `sealed class`, `object`, `enum class` appropriately204- No `!!` null assertions — use `?.let`, `?: return`, `requireNotNull` with message205- Coroutines: always specify `CoroutineScope` + `Dispatcher` explicitly; never `GlobalScope`206- Use `@Stable` / `@Immutable` on Compose state classes for smart recomposition207208**Java:**209- `@NonNull` / `@Nullable` annotations on every method param and return type210- Never call methods on unchecked objects — null-check explicitly or use `Objects.requireNonNull`211- Always null `binding` reference in Fragment's `onDestroyView()` to prevent memory leaks212- Use `ExecutorService` (not `AsyncTask` — deprecated) for background work; or `LiveData` + Room's built-in threading213- Prefer `ListAdapter` + `DiffUtil` over manual `notifyDataSetChanged()` in RecyclerView214- Use `ViewBinding` — never `findViewById`215216**Dart (Flutter):**217- Null safety required — no `!` without explicit null check above218- Immutable state objects with `copyWith`219- `const` constructors on all stateless widgets220221**TypeScript (RN):**222- `strict: true` in tsconfig always223- Zod or io-ts for runtime type validation of API responses224- No `any` — use `unknown` and narrow225226### Dependency Management227- Pin all dependency versions in `build.gradle.kts` / `pubspec.yaml` / `package.json`228- Audit dependencies monthly for security vulnerabilities229- Avoid transitive dependency conflicts — use dependency resolution strategies230- Keep dependency count minimal — every added lib is a maintenance burden231232### Code Review Checklist (PR gate)233- [ ] New public APIs have KDoc / DartDoc / JSDoc234- [ ] No hardcoded strings — use string resources / l10n235- [ ] No hardcoded dimensions or colors outside design tokens236- [ ] No blocking I/O on main thread237- [ ] No memory leaks (no `Activity` context stored in singletons)238- [ ] Coroutine scopes / streams properly cancelled / disposed239- [ ] Feature flag guarding any non-trivial feature240241---242243## §5 Error Handling244245### The Golden Rule246**Never let exceptions propagate to the user silently or crash the app.**247248### Error Classification249250| Type | Strategy |251|------|----------|252| Network errors | Retry with exponential backoff; show retry UI |253| Auth errors (401/403) | Refresh token → re-request → logout if fails |254| Validation errors | Show inline field errors immediately |255| Data parsing errors | Log + fallback to cached/default state |256| Unexpected crashes | Catch at top-level; show error screen + report |257| Background task failures | Retry via WorkManager; notify user if critical |258259### Result / Either Pattern (Kotlin)260```kotlin261sealed class AppResult<out T> {262 data class Success<T>(val data: T) : AppResult<T>()263 data class Error(val exception: AppException) : AppResult<Nothing>()264}265266sealed class AppException(msg: String) : Exception(msg) {267 class NetworkException(msg: String) : AppException(msg)268 class AuthException(msg: String) : AppException(msg)269 class ParseException(msg: String) : AppException(msg)270 class UnknownException(msg: String) : AppException(msg)271}272```273274Use `AppResult<T>` as return type for all repository + use case functions. ViewModels map to `UiState.Error`.275276### Crash Reporting277- Integrate **Firebase Crashlytics** or **Sentry** from day one278- Set user identifiers and custom keys before crash occurs279- Non-fatal exceptions logged for all caught errors280- ANR monitoring enabled281- Crash-free sessions target: **≥ 99.5%**282283### Offline / Network Resilience284- Cache-first strategy: show stale data, fetch fresh in background285- `Room` / `Drift` / `MMKV` as single source of truth286- Expose network state via `ConnectivityManager` and reflect in UI287- All network calls wrapped with timeout + retry policy288289---290291## §6 Testing292293### Testing Pyramid294295```296 /\297 /E2E\ ← 10% (UI tests: Espresso, Maestro, Appium)298 /------\299 / Integr \ ← 20% (Repository, DB, API contract tests)300 /----------\301 / Unit \ ← 70% (ViewModels, Use Cases, Utilities)302 /--------------\303```304305### Unit Tests (70%)306- Every ViewModel, UseCase, Repository, Mapper tested307- **Native:** JUnit5 + MockK + Turbine (Flow testing) + Kotest assertions308- **Flutter:** `flutter_test` + `mocktail`309- **RN:** Jest + `@testing-library/react-native` + `msw` for API mocking310- Coverage target: **≥ 80%** on domain + presentation layers311312### Integration Tests (20%)313- Room DB tests with in-memory database314- Retrofit/Ktor tests with `MockWebServer` (OkHttp)315- Repository tests verifying cache + remote coordination316- API contract tests against real staging endpoint317318### UI / E2E Tests (10%)319- **Espresso** for critical user journeys (login, checkout, core action)320- **Maestro** for cross-platform E2E flows (recommended for Flutter + RN too)321- Run on real device farm (Firebase Test Lab / BrowserStack) before release322- Smoke test suite runs on every PR; full E2E suite nightly323324### Test Data Management325- Use factories / builders for test data, never copy-paste objects326- Hermetic tests: never share mutable state between test cases327- Fakes over mocks for complex dependencies (repositories, data sources)328329---330331## §7 Build & Release332333### Build Variants334```335debug → dev API, logging on, no minification, debuggable336staging → staging API, logging on, minified, not debuggable337release → prod API, logging off, minified, signed338```339340### Gradle Best Practices (Native)341- `build.gradle.kts` only — no Groovy DSL in new projects342- Version catalog (`libs.versions.toml`) for all dependency versions343- `buildConfig` for environment-specific constants344- Baseline profiles for startup performance345- R8 full mode enabled in release; maintain proguard rules in version control346347### CI/CD Pipeline348349```350PR Opened351 └─ lint + unit tests + build debug APK [< 5 min]352353Merge to main354 └─ unit + integration tests + staging build [< 15 min]355 └─ deploy to Firebase App Distribution (QA)356357Release tag358 └─ full test suite + E2E on device farm [< 45 min]359 └─ build release AAB360 └─ upload to Play Console (internal track)361 └─ promote: internal → closed testing → open → production362```363364**Recommended CI:** GitHub Actions, Bitrise, or CircleCI.365366### Play Store Release Strategy367- Always release to **internal → closed → open testing** before production368- Use **staged rollouts**: 5% → 20% → 50% → 100% with 24-48h monitoring369- Monitor Crashlytics + ANR rate + rating before expanding rollout370- **Never skip staged rollout** for significant changes371372### App Signing373- Upload key (Play App Signing): stored in CI secrets, never committed374- Use Google Play App Signing for distribution key management375- Document key recovery procedure in team runbook376377---378379## §8 Performance380381### Startup Performance382- App startup time target: **cold start < 1s**, warm start < 500ms383- Use **App Startup library** for initializing libraries lazily384- Baseline profiles generated + committed to repo385- Heavy initialization moved off main thread386387### UI Performance388- Target: **60fps** (90/120fps on supported devices); **zero jank**389- Measure with **Android Studio Profiler** + `FrameMetrics` API390- Avoid allocation in `draw()` / `onMeasure()` / composition391- Use `derivedStateOf` in Compose to avoid unnecessary recompositions392- Image loading: Coil (Compose) / Glide / Picasso — never load full-res in thumbnails393394### Memory395- No `Activity` / `Context` references in ViewModels or singletons396- WeakReferences for listeners stored beyond their owner's lifecycle397- Bitmap recycling and memory cache sizing398- Heap dump + leak detection via **LeakCanary** in debug builds (always)399400### Network401- HTTP caching headers respected402- Image CDN + WebP format403- Gzip/Brotli compression verified404- Request batching where applicable405- Connection pooling configured406407### Battery408- Background work only via **WorkManager** with appropriate constraints409- Location updates: request only needed accuracy level; stop when backgrounded410- Wakelocks used sparingly with explicit release411412---413414## §9 Debugging & Bug Fixing415416### Debugging Process4174181. **Reproduce reliably** — document exact steps, device, OS version, account state4192. **Isolate** — is it UI, business logic, network, or persistence?4203. **Instrument** — add targeted logs / breakpoints, NOT shotgun logging4214. **Hypothesize** — form 1-3 specific hypotheses before touching code4225. **Fix the root cause** — never patch symptoms; trace back to the source4236. **Regression test** — write a test that fails before fix, passes after4247. **Document** — comment explaining why the fix works, not just what it does425426### Common Android Bug Patterns427428| Bug | Likely Cause | Fix |429|-----|-------------|-----|430| ANR | Main thread I/O / long computation | Move to coroutine/Dispatcher.IO |431| Memory leak | Context stored in singleton | Use `applicationContext`; WeakRef |432| Crash on rotation | ViewModel not used; state not saved | `rememberSaveable` / ViewModel |433| UI lag | Recomposition loops | `derivedStateOf`, stable params |434| Blank screen after API call | Error swallowed silently | Check error state propagation |435| Deep link not working | Manifest intent-filter missing | Verify `adb shell am start` test |436| Push notification silent | Background restrictions | Test on real devices across OEMs |437438### Logging Standards439- **Production:** Firebase Crashlytics only (no `Log.d` in release builds)440- **Debug/Staging:** Timber with debug tree441- Log levels: ERROR (crashes), WARN (recoverable), INFO (key events), DEBUG (dev only)442- Never log PII — mask emails, phone numbers, tokens in logs443444### OEM-Specific Issues445- Test on **Samsung**, **Xiaomi/MIUI**, **OnePlus/OxygenOS**, **Huawei (no GMS)** for critical flows446- Background restrictions vary widely by OEM — test push, alarms, background sync447- Maintain a physical or cloud device farm with top market-share devices448449---450451## §10 Development Roadmap452453Follow this phase structure for any new Android project:454455### Phase 0 — Foundation (Week 1-2)456- [ ] Stack decision documented with rationale457- [ ] Module structure defined458- [ ] Design system tokens defined (colors, type, spacing, shapes)459- [ ] CI pipeline running (lint + unit tests + build)460- [ ] Crash reporting integrated (Crashlytics/Sentry)461- [ ] Analytics baseline integrated (Firebase/Amplitude)462- [ ] API contract / mock server set up463- [ ] DI framework configured464- [ ] Navigation skeleton implemented465- [ ] Flavor/build variant config complete466467### Phase 1 — Core Features (Weeks 3-8)468- [ ] Auth flow (login, register, token refresh, logout)469- [ ] Core screen shells with real navigation470- [ ] Network layer (client, interceptors, error handling)471- [ ] Local persistence layer (DB schema + DAOs)472- [ ] Repository layer wiring remote + local473- [ ] ViewModels + UI states for each feature474- [ ] Unit tests for all ViewModels + use cases475- [ ] Feature flags infrastructure476477### Phase 2 — Polish (Weeks 9-12)478- [ ] Design QA pass against Figma/spec479- [ ] Accessibility audit (TalkBack, contrast, touch targets)480- [ ] Dark mode implementation + verification481- [ ] Localization (strings externalized, RTL support if needed)482- [ ] Loading, empty, error states on every screen483- [ ] Deep link handling484- [ ] Widget / notification implementation485- [ ] Offline mode verification486487### Phase 3 — Hardening (Weeks 12-14)488- [ ] Performance profiling (startup, scroll, memory)489- [ ] E2E test suite on device farm (Firebase Test Lab)490- [ ] Security review (certificate pinning, biometrics, secure storage)491- [ ] Proguard / R8 rules verified492- [ ] Crash-free rate ≥ 99.5% on staging493- [ ] Play Store listing, screenshots, privacy policy494495### Phase 4 — Release496- [ ] AAB signed and uploaded to internal track497- [ ] Staged rollout plan defined498- [ ] Monitoring dashboard set up (Crashlytics, Play Console vitals)499- [ ] Rollback plan documented500- [ ] On-call rotation assigned501502### Phase 5 — Post-Launch (Ongoing)503- Crash-free rate monitored daily504- ANR rate < 0.47% (Play Store threshold)505- App rating monitored; negative reviews triaged weekly506- Dependency updates reviewed monthly507- OS beta testing with each new Android release508509---510511## Limitations512513- This skill is scoped to Android and Android-adjacent delivery paths; it does not cover iOS-only architecture, App Store release operations, or Apple platform UI guidance.514- Version numbers, Play Console policy thresholds, and recommended libraries can change; verify release-critical details against current Android, Google Play, and library documentation before shipping.515- Code snippets are architecture patterns, not complete applications; adapt package names, dependency versions, permissions, privacy disclosures, and security controls to the actual project.516- The guidance does not replace device QA, accessibility review, security review, legal/privacy review, or store compliance checks for a production release.517518## Additional Resources519520For stack-specific deep dives, read:521- `references/native-android.md` — Kotlin, Compose, Room, Hilt, Coroutines522- `references/java-android.md` — Java, XML Views, ViewBinding, LiveData, Retrofit, Room, Hilt, migration path523- `references/flutter.md` — Dart, BLoC/Riverpod, Drift, go_router524- `references/react-native.md` — TypeScript, RN architecture, Hermes, New Architecture525- `references/kmm.md` — KMM shared modules, SQLDelight, Ktor, Compose Multiplatform526- `references/hybrid.md` — Capacitor, Ionic, PWA considerations