contexture android.instructions.md

android rules

Auto-loaded by Copilot when editing files matching **. Generated from architectural-rules/android/ — do not hand-edit.

Android Lifecycle Discipline

Never hold a static or long-lived reference to an Activity, Fragment, View, or their Context. Use applicationContext for needs that outlive a single screen. A static Activity ref keeps the whole view hierarchy alive past onDestroy, leaking memory. (Android docs — Activity lifecycle)

Do not store UI state in the Activity/Fragment. Hold it in a ViewModel (survives rotation/config changes) plus SavedStateHandle / saved instance state for process death. The system destroys and recreates the Activity on configuration change; instance fields are lost. (Android docs — Handle configuration changes)

Register and unregister listeners, receivers, sensors, and observers symmetrically: acquire in onStart/onResume, release in the paired onStop/onPause. Asymmetric registration leaks callbacks and double-fires after recreation. (Android docs — Activity lifecycle)

Why: The framework owns Activity/Fragment lifetime and recreates them on configuration changes, so any UI state or Context captured in instance/static fields either leaks or is silently lost. Hoisting state into a lifecycle-aware ViewModel and binding resource acquisition to symmetric lifecycle callbacks keeps ownership explicit and prevents both leaks and stale callbacks. Source: Android developer documentation.

Android Resources and Manifest Discipline

Never hardcode UI strings, dimensions, colors, or sizes in code or layouts. Put them in res/values/ (strings.xml, dimens.xml, colors.xml) and provide configuration-qualified variants (values-fr/, values-night/, values-sw600dp/). Externalized resources enable localization, theming, and device adaptation. (Android docs — App resources)

Declare every permission in the manifest, and for dangerous permissions request them at runtime and handle denial gracefully. Assuming a permission is granted without checking crashes on modern Android. Request only what the feature needs. (Android docs — Permissions on Android)