android-development

## Platform Notes

- Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

# Android Development Standards
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Android development standards for AI agent implementation. Kotlin-first, Jetpack Compose UI, MVVM + Clean Architecture, Hilt DI, comprehensive security, testing, and performance patterns. Use when building or reviewing Android applications...
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

## Do Not Use When

- The task is unrelated to `android-development` or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.

## Required Inputs

- Gather relevant project context, constraints, and the concrete problem to solve; load `references` only as needed.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

## Workflow

- Read this `SKILL.md` first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

## Quality Standards

- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

## Anti-Patterns

- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.

## Outputs

- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.

## Evidence Produced

| Category | Artifact | Format | Example |
|----------|----------|--------|---------|
| Correctness | Android feature test plan | Markdown doc covering unit, instrumentation, and Compose tests | `docs/android/feature-tests-checkout.md` |
| UX quality | Accessibility audit | Markdown doc covering TalkBack, semantics, and contrast | `docs/android/a11y-checkout.md` |

## References

- Use the `references/` directory for deep detail after reading the core workflow below.
- `references/android-ai-ml.md` for on-device Android AI/ML, ML Kit, LiteRT, MediaPipe, AICore, and Gemini Nano.
- `references/android-biometric-login.md` for AndroidX Biometric launch gates and CryptoObject-backed authentication.
- `references/android-pdf-export.md` for native `PdfDocument` export and Android report PDF generation.
<!-- dual-compat-end -->
## Load Order

1. Load `world-class-engineering` for shared production gates.
2. Load `system-architecture-design` when the Android app is part of a larger backend or multi-module system.
3. Load this skill for Android implementation details.
4. Load `android-ui-ux-design` for every user-facing Android screen, especially premium, dashboard, onboarding, reporting, form, or revenue-critical flows.
5. Load `vibe-security-skill` and feature-specific skills as needed.

Production-grade Android development standards for AI-assisted implementation. Kotlin-first with Jetpack Compose, following modern Android best practices.

**Core Stack:** Kotlin 100% | Jetpack Compose (default UI toolkit) | MVVM + Clean Architecture | Hilt DI
**Min SDK:** 29 (Android 10) | **Target SDK:** 35 (Android 15)
**Compatibility:** Must run flawlessly on BOTH the minSdk (oldest supported) AND the latest stable Android release
**Reference App:** [Now in Android](https://github.com/android/nowinandroid) - Google's official sample demonstrating these standards in a production-quality codebase

## When to Use

- Building new Android applications or features
- Reviewing Android code for quality and standards compliance
- Generating Kotlin/Compose code via AI agents
- Setting up Android project structure
- Implementing security, testing, or performance patterns
- Integrating with REST APIs from Android clients

## Backend Environments

Android apps connect to a PHP/MySQL backend deployed across three environments:

| Environment | Base URL Pattern | Database | Notes |
|---|---|---|---|
| **Development** | `http://{LAN_IP}:{port}/DMS_web/api/` | MySQL 8.4.7 (Windows WAMP) | Use host machine's LAN IP, not `localhost` |
| **Staging** | `https://staging.{domain}/api/` | MySQL 8.x (Ubuntu VPS) | For QA and testing |
| **Production** | `https://{domain}/api/` | MySQL 8.x (Debian VPS) | Live users |

Configure base URLs using build flavors (`dev`, `staging`, `prod`) so the app targets the correct backend per build variant. All backends use `utf8mb4_unicode_ci` collation and MySQL 8.x.

## Quick Reference

| Topic                       | Reference File                        | Covers                                          |
| --------------------------- | ------------------------------------- | ----------------------------------------------- |
| **Project Structure**       | `references/project-structure.md`     | Directory layout, module organization           |
| **Kotlin Conventions**      | `references/kotlin-conventions.md`    | Coding style, Compose patterns                  |
| **Architecture**            | `references/architecture-patterns.md` | MVVM, Clean Architecture layers                 |
| **Dependency Injection**    | `references/dependency-injection.md`  | Hilt modules, scoping, ViewModel injection      |
| **Security**                | `references/security.md`              | Encrypted storage, biometrics, network security |
| **UI Design System**        | `references/ui-design-system.md`      | Tokens, components, Material 3                  |
| **Premium Android UX**      | `../android-ui-ux-design/SKILL.md`    | Material 3 polish, mobile ergonomics, premium gate |
| **Screen Patterns**         | `references/screen-patterns.md`       | Complete screen templates, state handling       |
| **Testing**                 | `references/testing.md`               | Unit, UI, instrumentation tests                 |
| **Build Configuration**     | `references/build-configuration.md`   | Gradle KTS, Android Studio setup, dependencies, build types, build-speed tuning |
| **API Integration**         | `references/api-integration.md`       | Retrofit, error handling, repository pattern    |
| **Analytics & Performance** | `references/analytics-performance.md` | Firebase, monitoring, optimization              |
| **AI Agent Guidelines**     | `references/ai-agent-guidelines.md`   | Prompt templates, quality checklists            |

## Architecture Overview

```
Presentation Layer (Compose + ViewModels)
         |
    Domain Layer (Use Cases + Repository Interfaces)
         |
    Data Layer (Repository Impl + API + Room)
```

### Layer Rules

1. **Presentation** depends on Domain only
2. **Domain** has no Android dependencies (pure Kotlin)
3. **Data** implements Domain interfaces, handles API/DB

### Package Structure

```
com.company.app/
  core/          # Shared: DI, models, repositories, utils
  data/          # Room DB, API services, data sources
  presentation/  # Screens, ViewModels, components, navigation
  theme/         # Design system tokens
```

## Key Standards Summary

### Kotlin

- 100% Kotlin, no Java for new code
- Coroutines + Flow for async (never callbacks)
- Sealed classes for UI state modeling
- Extension functions for utility code

### Compose

- Jetpack Compose is the default UI toolkit for all new screens
- Views are allowed only for legacy interop or third-party View-only SDKs
- Stateless composables preferred (state hoisted to ViewModel)
- `LaunchedEffect` for side effects, never in composition
- `collectAsStateWithLifecycle()` for Flow collection
- Stable keys for `LazyColumn`/`LazyRow` items
- **Adaptive layouts mandatory** — use `WindowSizeClass` for phone/tablet/foldable
- Material 3 adaptive library: `androidx.compose.material3.adaptive:adaptive`

### Custom PNG Icons (Required)

- Use custom PNG icons only; do not use icon libraries
- Use `painterResource(R.drawable.<name>)` or `@drawable/<name>`
- Maintain `PROJECT_ICONS.md` in the project root

Follow the `mobile-platform-operations` skill (its `mobile-custom-icons` reference) for naming, directory rules, and tracking.

### Charting (Vico Standard)

- Use Vico for all charting needs (line, bar, column, candle, etc.)
- Prefer the Compose module for new screens; use Views only when required
- Always follow the official guide for setup and current versions
- Reference the Vico sample module for patterns and styling

### Report Tables (25+ Rows)

- Any report that can exceed 25 rows must render as a table, not cards
- Follow the `android-ui-ux-design` skill (business reports over 25 rows use table-first or dense list patterns) for table-first guidance, and the `professional-word-output` skill for exported report tables.

### Three Build Variants (Mandatory)

Every Android app MUST have exactly 3 build variants. This is non-negotiable.

| Variant | Purpose | APK Name | Minified | Install Target |
|---------|---------|----------|----------|----------------|
| **debug** (dev) | Local development | `{AppName}-dev-{version}.apk` | No | Emulator (default) |
| **staging** | QA / pre-production | `{AppName}-staging-{version}.apk` | Yes (R8) | Emulator (on request) |
| **release** (prod) | Production / Play Store | `{AppName}-prod-{version}.apk` | Yes (R8) | Device (manual) |

**Rules:**

1. **User must provide** the staging and production API URLs for each project. Debug always points to the local dev server (`http://10.0.2.2/...` for emulator or the host LAN IP).
2. **During active development, build only the variant you need** — usually `debug`. Do not build `staging` and `release` on every iteration.
3. **Default local loop:** `./gradlew installDebug` (or `assembleDebug`) for normal coding, UI work, and device testing.
4. **Build all 3 APKs only for release verification, QA handoff, CI, or when the user explicitly asks for all artifacts**: `./gradlew assembleDebug assembleStaging assembleRelease`
5. If the user explicitly asks to test staging, install staging instead: `./gradlew installStaging`
6. **APK naming** uses a consistent prefix per app (e.g., `DMS-dev-1.0.0.apk`, `DMS-staging-1.0.0.apk`, `DMS-prod-1.0.0.apk`). Configure via the modern Android Components Variant API, not deprecated internal output classes.
7. **Staging** inherits from release (R8 enabled, resource shrinking) but uses the debug signing config so it can be installed alongside dev on the same device.
8. **ProGuard rules** must strip `Log.v`, `Log.d`, `Log.i`, and `println` from staging and release builds.
8. **Never hardcode API URLs** — always use `BuildConfig.API_BASE_URL` (or similar) set per build type.

See `references/build-configuration.md` for the complete Gradle setup.

Always set API endpoints through `BuildConfig.API_BASE_URL` (or a similar generated constant) per build type or flavor. Never hardcode server URLs in app code.

### Android Studio + Build Speed Baseline

Before doing deeper performance work, establish this baseline:

1. **Keep tools current** — update Android Studio, SDK tools, Gradle, and AGP together when the project allows it.
2. **Use KSP instead of kapt** wherever the library supports it. `kapt` should be treated as legacy.
3. **Pin dependency and plugin versions** — never use dynamic versions like `2.+` or `latest.release`.
4. **Disable Jetifier** unless Build Analyzer proves the project still needs it.
5. **Enable configuration cache** once the project and plugins are compatible.
6. **Use configuration-avoidance and lazy APIs** in Gradle scripts; do not run expensive logic during configuration.
7. **Keep debug builds static** — no dynamic version names, manifest placeholders, or generated values that force full rebuilds.
8. **Prefer modularization** when the app is large enough that feature or core modules can compile independently.
9. **Use Build Analyzer and Gradle profiling before guessing**. Measure first, then optimize the real bottleneck.
10. **Develop on API 24+ devices/emulators whenever possible** for faster deployment loops.

### Device & Android Version Compatibility (CRITICAL)

Our apps MUST work for the few people still holding older devices, but MUST ALSO WORK for those with newer/latest devices. Never test only on one Android version.

**Mandatory rules:**

1. **`enableEdgeToEdge()` is REQUIRED** — Call it in `MainActivity.onCreate()` before `super.onCreate()`. Android 15 (API 35) enforces edge-to-edge for apps targeting SDK 35. Without it, the app **crashes immediately** on Android 15 devices. This is non-negotiable.
2. **Do NOT set `window.statusBarColor` directly** — It is deprecated and conflicts with edge-to-edge. Let `enableEdgeToEdge()` handle system bar colors. Only control light/dark icon appearance via `WindowCompat.getInsetsController().isAppearanceLightStatusBars`.
3. **Test on at least two Android versions** — Always verify on both the minSdk emulator (Android 10) AND a recent Android (14/15) emulator or device before shipping.
4. **Guard version-specific APIs** — When using APIs added after minSdk, wrap them in `if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.X)` checks.
5. **Keep targetSdk current** — Target the latest stable SDK (currently 35). Do not lag behind — Google Play requires recent targetSdk and newer Android versions enforce stricter behavior for apps that target them.
6. **Use `AppCompatActivity`** when locale switching is needed (`AppCompatDelegate.setApplicationLocales()`). Otherwise prefer `ComponentActivity` for pure Compose apps.

**Correct MainActivity pattern:**

```kotlin
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        installSplashScreen()  // Before super
        enableEdgeToEdge()     // Before super — MANDATORY for targetSdk 35
        super.onCreate(savedInstanceState)
        setContent { ... }
    }
}
```

### Security

- `EncryptedSharedPreferences` for sensitive data
- Certificate pinning for API calls — **NEVER use placeholder pins** (they cause `SSLPeerUnverifiedException`). Extract real SHA-256 pins from servers using `openssl` before enabling. See `references/security.md` for the extraction command.
- For **Let's Encrypt** servers: always pin the **intermediate CA** (stable) alongside the leaf pin. Leaf pins rotate every 90 days on auto-renewal; intermediate CA pins survive renewals.
- Use `ENABLE_CERT_PINNING` BuildConfig flag: `false` for dev, `true` for staging/prod
- Pin **ALL** server domains the app connects to (both staging AND production)
- Biometric authentication for sensitive operations
- No hardcoded secrets, use `BuildConfig` fields
- ProGuard/R8 for release builds

### Testing

- Unit tests for ViewModels and Use Cases (MockK)
- Compose UI tests for screens (ComposeTestRule)
- Turbine for Flow testing
- Hilt test rules for DI in tests

### Performance

- StrictMode in debug builds
- Stable keys in lazy lists
- `derivedStateOf` for expensive calculations
- Image loading via Coil with caching
- ProGuard + resource shrinking in release
- Build with `debug` only during normal development; reserve full multi-variant builds for QA or release checks
- Use Build Analyzer before changing Gradle memory, GC, or plugin settings
- Prefer KSP-backed processors and remove `kapt` unless there is no supported migration path
- Keep `android.enableJetifier=false` unless a dependency audit proves otherwise
- Enable configuration cache only after checking plugin compatibility and fixing violations

### Release Gate

Before calling an Android feature production-ready:

- Verify the main user journey on minSdk and latest Android.
- Verify offline, slow-network, and denied-permission behavior.
- Verify startup, scrolling, and list interactions against performance expectations.
- Verify crash reporting, analytics, and audit-sensitive actions are instrumented.
- Verify sensitive data never lands in logs, screenshots, or unsecured storage.
- Verify `android-ui-ux-design` premium UX checks for navigation, touch targets, text scaling, TalkBack, state completeness, and platform-native polish.

### Local Development Networking (WAMP)

- When developing on a local machine (Windows WAMP or Ubuntu), the Android emulator must reach the backend via the host machine's static LAN IP, not `localhost`.
- Always document the static IP in dev setup notes and use it for `BASE_URL` in the Android dev build.
- Verify firewall rules allow inbound connections to the WAMP HTTP port.

### Google Play Review Readiness

- Use the `mobile-platform-operations` skill (its `google-play-store-review` reference) before Play Console submission.
- Keep targetSdk current and background work compliant.
- Ensure Data Safety form matches SDKs and permissions.
- Provide a public privacy policy and link it in-app.
- Validate ads and IAP flows for transparency and user control.

### Mandatory Theme Appearance Setting

Every Android app MUST include a theme appearance selector in its Tools/Settings section. This is a **non-negotiable standard** — users must be able to control the app's visual theme.

**Requirements:**
1. **Three options:** System default (follows device setting), Light, Dark
2. **Default:** System default — always respect the user's device-wide preference
3. **Location:** Tools or Settings hub screen, under an "Appearance" section
4. **Persistence:** Store in SharedPreferences (not encrypted — non-sensitive)
5. **Reactivity:** Theme changes apply instantly without app restart (use StateFlow)

**Implementation pattern:**

```kotlin
// 1. ThemePreferences.kt (data/local/prefs/)
enum class ThemeMode(val key: String, val label: String) {
    SYSTEM("system", "System default"),
    LIGHT("light", "Light"),
    DARK("dark", "Dark");
    companion object {
        fun fromKey(key: String): ThemeMode =
            entries.firstOrNull { it.key == key } ?: SYSTEM
    }
}

@Singleton
class ThemePreferences @Inject constructor(
    @ApplicationContext context: Context
) {
    private val prefs = context.getSharedPreferences("theme_prefs", Context.MODE_PRIVATE)
    private val _themeMode = MutableStateFlow(loadThemeMode())
    val themeMode: StateFlow<ThemeMode> = _themeMode.asStateFlow()

    private fun loadThemeMode(): ThemeMode =
        ThemeMode.fromKey(prefs.getString("theme_mode", "system") ?: "system")

    fun setThemeMode(mode: ThemeMode) {
        prefs.edit().putString("theme_mode", mode.key).apply()
        _themeMode.value = mode
    }
}

// 2. MainActivity.kt — resolve ThemeMode to darkTheme boolean
val themeMode by themePreferences.themeMode.collectAsState()
val darkTheme = when (themeMode) {
    ThemeMode.SYSTEM -> isSystemInDarkTheme()
    ThemeMode.LIGHT -> false
    ThemeMode.DARK -> true
}
AppTheme(darkTheme = darkTheme) { /* content */ }

// 3. Tools/Settings screen — FilterChip row for selection
ThemeMode.entries.forEach { mode ->
    FilterChip(
        selected = selected == mode,
        onClick = { viewModel.setThemeMode(mode) },
        label = { Text(mode.label) },
        leadingIcon = if (selected == mode) { { Icon(Icons.Default.Check, null) } } else null
    )
}
```

## Phase 1 Bootstrap Pattern (SaaS Mobile Apps)

When building a native Android app for an existing SaaS backend, **always implement Phase 1 first**: Login + Dashboard + Empty Tabs. This is the mandatory starting point before any business features.

### Phase 1 Delivers

1. **JWT Auth** — Login/logout, token refresh with rotation, breach detection, encrypted storage
2. **Dashboard** — Real KPI stats, offline-first Room caching, pull-to-refresh, shimmer loading
3. **5-Tab Navigation** — Bottom bar with max 5 tabs, placeholder screens for future features
4. **Full Infrastructure** — Hilt DI, Retrofit interceptor chain, Room DB, Material 3 theme, network monitor
5. **40+ Unit Tests** — ViewModels, Use Cases, Repositories, Interceptors all tested

### Why Phase 1 First

- Proves the entire vertical slice (Compose UI → ViewModel → UseCase → Repo → Retrofit → PHP → MySQL)
- Establishes all reusable infrastructure patterns
- Gives user a working installable app immediately
- Uncovers backend integration issues early

See `android-saas-planning` skill for the complete Phase 1 plan template.

## KMP Projects

If this is a **Kotlin Multiplatform** project, this skill governs the
`composeApp/` module (Android UI and platform integration). The `shared/`
module is governed by the `kmp-development` skill. Use Hilt for DI in
`composeApp/` and Koin in `shared/`. Use the `kmp-development` skill for shared module test-driven development.

## Anti-Patterns

- Putting business logic in Composables
- Using `mutableStateOf` in ViewModels instead of `StateFlow`
- Hardcoding colors/dimensions instead of design tokens
- Skipping error states in UI
- Network calls on main thread
- Missing `key` parameter in `LazyColumn` items
- God ViewModels (split by feature, not by screen)
- Ignoring lifecycle (use `collectAsStateWithLifecycle`)
- Building phone-only UIs — all screens must adapt to tablets/foldables
- Using hardcoded `isTablet()` checks instead of `WindowSizeClass` breakpoints
- **Missing `enableEdgeToEdge()`** — causes immediate crash on Android 15 devices
- Setting `window.statusBarColor` directly — deprecated, conflicts with edge-to-edge
- Testing only on one Android version — must verify on both old (minSdk) and new (latest) devices

## Integration with Other Skills

```
feature-planning           -> spec + implementation strategy
  |
android-development        -> Kotlin/Compose implementation
  |
android-ui-ux-design       -> premium Material 3 UX and screen quality
  |
mobile-platform-operations -> Play policy and submission readiness
  |
api-error-handling         -> Backend API error patterns
  |
mysql-best-practices       -> Database schema (backend)
  |
vibe-security-skill        -> Security review
```

**Always apply `vibe-security-skill`** alongside this skill for web-connected Android apps.
Use `mobile-platform-operations` when preparing Play Console submissions.

## Reference Implementations

Google maintains three official reference repos. Use them as canonical examples:

### Now in Android ([github.com/android/nowinandroid](https://github.com/android/nowinandroid))

Full production-quality app. **Use for:** multi-module architecture, convention plugins, offline-first (Room + network sync), Hilt across modules, version catalogs, Gradle KTS build config.

### Architecture Samples ([github.com/android/architecture-samples](https://github.com/android/architecture-samples))

Layered architecture TODO app. **Use for:** MVVM pattern clarity, Repository pattern with dual data sources, single-activity navigation with Compose, product flavors (mock/prod), comprehensive test suite (unit + integration + E2E), clean separation of concerns.

### Compose Samples ([github.com/android/compose-samples](https://github.com/android/compose-samples))

Collection of focused Compose apps. **Use for specific UI patterns:**

| Sample        | Use For                                                     |
| ------------- | ----------------------------------------------------------- |
| **JetNews**   | Material app structure, theming, Compose testing            |
| **Jetchat**   | Material 3, dynamic colors, navigation, state management    |
| **Jetsnack**  | Custom design systems, layouts, animations                  |
| **Jetcaster** | Redux-style architecture, dynamic theming, Room, coroutines |
| **Reply**     | Adaptive UI (phone/tablet/foldable), Material 3             |
| **JetLagged** | Custom layouts, graphics, Canvas/Path drawing               |

When in doubt about how to implement something, check these repos first.