cross-plat-design/platform-rules/android.md

Android Platform Rules

Interaction and layout

• Respect safe areas, system bars, and gesture navigation.
• Support Android back navigation through go_router without duplicating navigation state in Riverpod.
• Use touch targets of at least 48 logical px where practical.
• Account for the virtual keyboard and changing insets.
• Prefer single-pane layouts on narrow screens.
• Preserve editor state and scroll position during navigation.
• Respect system text scaling and activity lifecycle events.

Capabilities and permissions

• Request runtime permissions only when the user initiates the capability that needs them.
• Use platform adapters for file selection, storage, clipboard, and lifecycle integration.
• Handle denied, revoked, or unavailable permissions as recoverable states.
• Restore supported editor and route state after activity recreation.

Release requirements

• Validate debug, profile, and release builds as appropriate for the project.
• Test the supported Android API/device matrix, including narrow and large screens.
• Verify application signing, app links if used, and permission declarations.
• Verify keyboard, back navigation, lifecycle restoration, and safe-area behavior.

Smoke-test checklist

• Navigate forward and back through nested routes.
• Open the keyboard and verify content resizes or scrolls without clipping.
• Rotate or resize supported devices and confirm state is preserved.
• Deny and grant file or storage permissions.
• Background and resume the app while editing unsaved content.