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.

Chwezi Product Excellence Standard (mandatory)

Any Chwezi app or system UI work (effective 01 Nov 2026) MUST follow the Chwezi Product Excellence Standard in chwezi-design-engine (resolve via the engine-routing table; never hard-code the path): doctrine/product-excellence-standard.md and skill skills/00-cross-cutting-ops-qa-a11y/chwezi-product-excellence-standard. Engineering gates: product-excellence-engineering-gates.md. Play targetSdk 36 consequences (edge-to-edge without opt-out, predictive back, orientation locks ignored at sw600dp), Baseline Profiles with Macrobenchmark on a physical floor device, and Android vitals targets are release gates. Where this skill and the standard differ, the standard wins.

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...

Evidence Produced

References

• Use the references/ directory for deep detail after reading the core workflow below.
• Load the retained Android persistence workflow for Room, DataStore, migrations, or offline sync.
• Load the retained Android TDD workflow for Red-Green-Refactor, test seams, and layer-specific test design.
• 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.

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: Choose from the product's supported-device policy. Play target: API 36 or higher for general new apps and updates, verified 2026-10-29; check the official requirement for platform-specific exceptions before release. Compatibility: test the declared minSdk and the latest stable Android release that the project supports. Current source snapshot identifies Android 17/API 37 as released; this is a compatibility target, not the Play submission target. Reference App: Now in Android - 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:

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

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.

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.
9. 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. Handle edge-to-edge insets on every screen — Edge-to-edge is enforced on Android 15+ for targetSdk 35+, and at targetSdk 36 on Android 16+ the windowOptOutEdgeToEdgeEnforcement opt-out is deprecated and disabled (CR:M6). Since Play requires targetSdk 36 for new apps and updates from 31 Aug 2026 (CR:M7), there is no opt-out: call enableEdgeToEdge(), pad content by WindowInsets (system bars, display cutout, IME), never by fixed numbers, and keep bottom bars and the cart bar above the gesture area. Verify bar contrast, cut-outs, IME, gesture and 3-button navigation on the supported device range. Missing the helper is not evidence by itself that the app crashes; clipped or overlapped content is the observable failure.
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 the actual support boundary — Verify the declared minSdk and a current stable Android emulator/device before shipping; inset, predictive-back and sw600dp rotate/resize tests are mandatory at targetSdk 36.
4. Predictive back is on by default at targetSdk 36 on Android 16+: onBackPressed is not called and KEYCODE_BACK is not dispatched (CR:M8). Put no logic in onBackPressed; use Compose BackHandler / PredictiveBackHandler (or OnBackPressedCallback), and intercept back only to protect unsaved data or an in-flight payment. The manifest opt-out android:enableOnBackInvokedCallback="false" is temporary and needs a DDR.
5. Orientation and resizability locks are ignored at smallest width >= 600 dp at targetSdk 36 (games excepted; CR:M9): screenOrientation, resizeableActivity=false and aspect-ratio limits do not hold on tablets and foldables. Build landscape and resizable layouts with window size classes (CR:M3) and keep state and drafts across rotation and resize. The compat opt-out ends at API 37.
6. elegantTextHeight is ignored at targetSdk 36 (CR:M10): re-check Arabic and other tall scripts at 100% and 200% font scale.
7. Guard version-specific APIs — When using APIs added after minSdk, wrap them in if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.X) checks.
8. Keep targetSdk current — Check the official Play target requirement for the app category at release time. New apps and updates must target API 36 from 31 Aug 2026 (phone and tablet; an extension to 1 Nov 2026 was possible), and existing apps need API 35+ to stay available to new users on newer OS versions (CR:M7); other form factors differ. Keep compileSdk compatibility separate from targetSdk and verify the actual Gradle/AGP/dependency combination.
9. Use AppCompatActivity when locale switching is needed (AppCompatDelegate.setApplicationLocales()). Otherwise prefer ComponentActivity for pure Compose apps.

Correct MainActivity pattern:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        installSplashScreen()  // Before super
        enableEdgeToEdge()     // No opt-out at targetSdk 36; pad content by WindowInsets
        super.onCreate(savedInstanceState)
        setContent { ... }
    }
}

CR:<ID> rows are in the design engine currentness register (skills/00-cross-cutting-ops-qa-a11y/chwezi-product-excellence-standard/references/currentness-register.md, accessed 2026-11-07, review by 2027-02-07). Re-read them there before relying on them; a lapsed row makes the dependent check NOT_ASSESSED.

Version and security currency

Before selecting an Android, Kotlin, Compose, Gradle, AGP, PHP, or database version, check the official release/support and security sources recorded in docs/source-registers/skills-engine-currentness-2026-09.json. The checked 2026-11-05 snapshot lists Android 17/API 37, Compose BOM 2026.09.00, and AGP 9.5.0 (the release the official AGP index points to; Gradle 9.6.0 and JDK 17 minimum) as the current source-listed values at that date. Kotlin 2.4.21 comes from the 2026-10-29 snapshot and was not re-read. Re-check them and their compatibility at implementation time. A Play target requirement is not a statement about the latest Android runtime. For Kotlin 2.0 and later the Compose compiler plugin follows the Kotlin version; still validate the chosen toolchain with a real build.

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:

// 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
• Assuming edge-to-edge can be opted out — at targetSdk 36 on Android 16+ it cannot (CR:M6); unhandled insets put content under the system bars, cut-out or keyboard
• 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
• Generating invoice or receipt numbers on the device while offline — show a provisional "Pending" tag and store the server number after sync (tenant-document-numbering)

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

Decision Rules

Degraded Mode

When builds or devices are unavailable, provide a reviewable patch and list the exact Gradle, unit, instrumentation, accessibility, and min-SDK checks still requiring execution. Do not claim device compatibility from static inspection alone.

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

Now in Android (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)

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)

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

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

Inputs

Outputs

• Produce Android code or design with lifecycle, accessibility, test, performance, and release evidence.

Capability contract

Read/search and local builds follow task scope; signing, store publication, backend mutation, and device-data destruction require explicit authority.