AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
mobilecritical PriorityID: android-15-edge-to-edge-insets-production-standard

Mandatory Android 15 Edge-to-Edge Layout, Insets Handling, and Predictive Back

Android 15 (API level 35) enforces edge-to-edge layouts by default for applications targeting targetSdk 35, ignoring legacy window flags such as fitsSystemWindows=true on root decors. Failure to explicitly consume WindowInsetsCompat or Compose WindowInsets results in critical visual clipping beneath navigation bars, status bars, and display cutouts. In addition, applications must implement OnBackAnimationCallback or predictiveBackAnimation modifier to handle system back navigations without gesture conflicts.

Prohibited Anti-Pattern: Relying on deprecated fitsSystemWindows attributes or hardcoded status/nav bar offsets on Android 15

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Mandatory Android 15 Edge-to-Edge Layout, Insets Handling, and Predictive Back - Android 15 (API level 35) enforces edge-to-edge layouts by default for applications targeting targetSdk 35, ignoring legacy window flags such as fitsSystemWindows=true on root decors. Failure to explicitly consume WindowInsetsCompat or Compose WindowInsets results in critical visual clipping beneath navigation bars, status bars, and display cutouts. In addition, applications must implement OnBackAnimationCallback or predictiveBackAnimation modifier to handle system back navigations without gesture conflicts.
globs: **/*.kt, **/res/values/styles.xml, **/res/values/themes.xml, **/AndroidManifest.xml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/android-15-edge-to-edge-insets-production-standard"
---

# Mandatory Android 15 Edge-to-Edge Layout, Insets Handling, and Predictive Back

> **Severity**: CRITICAL | **Category**: mobile
> **Anti-Pattern Warning**: Relying on deprecated fitsSystemWindows attributes or hardcoded status/nav bar offsets on Android 15

## System Constraints
You are a Principal Mobile Architect enforcing modern Android 15 (API 35) invariants across Jetpack Compose and View hierarchies. You must guarantee that applications properly implement enableEdgeToEdge(), consume system bars and display cutout insets dynamically via WindowInsetsCompat or Compose insets modifiers, avoid double-padding from nested insets consumption, and register Predictive Back callbacks via modern Jetpack navigation or OnBackPressedDispatcher.

## Strict Guidelines
- Engineers MUST ALWAYS invoke ComponentActivity.enableEdgeToEdge() in onCreate before setContent or setContentView.
- Engineers MUST NOT rely on android:fitsSystemWindows="true" on root layouts or windowTranslucentStatus/windowTranslucentNavigation flags in themes for targetSdk 35.
- Components MUST consume insets at the leaf interactive layer using Modifier.windowInsetsPadding(WindowInsets.safeDrawing), WindowInsets.systemBars, or ViewCompat.setOnApplyWindowInsetsListener, rather than applying global root padding that breaks full-bleed backgrounds.
- Nested scrolling containers MUST consume insets via contentPadding (e.g., LazyColumn(contentPadding = WindowInsets.navigationBars.asPaddingValues())) to prevent content from remaining clipped behind the navigation bar at scroll rest.
- Engineers MUST handle predictive back gestures using OnBackPressedDispatcher.addCallback with an OnBackAnimationCallback or Jetpack Compose PredictiveBackHandler rather than legacy Activity.onBackPressed override.
- Code MUST explicitly account for display cutouts and waterfall insets using WindowInsetsCompat.Type.displayCutout() alongside systemBars().

## Bad vs Good Implementations
### Jetpack Compose: Android 15 Edge-to-Edge and Insets Handling

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Failing to invoke enableEdgeToEdge() results in inconsistent rendering on pre-API 35 devices and unexpected behavior on API 35. Ignoring Scaffold's innerPadding or not passing insets to LazyColumn causes items at the top and bottom of the list to be obscured by the status bar, display cutout, or dynamic gesture pill. Overriding onBackPressed() breaks predictive back animations.
```kotlin
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ANTI-PATTERN: No enableEdgeToEdge(), relying on legacy window flags
        setContent {
            MaterialTheme {
                // ANTI-PATTERN: Hardcoded spacer or ignoring insets creates overlap on API 35
                Scaffold {
                    LazyColumn {
                        items(100) { index -> Text("Item $index") }
                    }
                }
            }
        }
    }

    // ANTI-PATTERN: Breaking predictive back gesture
    override fun onBackPressed() {
        super.onBackPressed()
    }
}
```

#### Production Standard (Correct)
> **Standard**: enableEdgeToEdge() standardizes system bar styles across API levels. Scaffold consumes safeDrawing insets (status bars, navigation bars, and display cutouts) and passes them cleanly as innerPadding to LazyColumn.contentPadding, allowing content to scroll edge-to-edge while resting safely outside system bar obstructions. Back navigation is registered using OnBackPressedCallback.
```kotlin
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // INVARIANT: Mandatory edge-to-edge configuration on modern Android
        enableEdgeToEdge()
        super.onCreate(savedInstanceState)

        setContent {
            MaterialTheme {
                Scaffold(
                    contentWindowInsets = WindowInsets.safeDrawing
                ) { innerPadding ->
                    LazyColumn(
                        modifier = Modifier.fillMaxSize(),
                        contentPadding = innerPadding
                    ) {
                        items(100) { index -> Text("Item $index") }
                    }
                }
            }
        }

        // INVARIANT: Enable predictive back via Jetpack OnBackPressedDispatcher
        onBackPressedDispatcher.addCallback(this, object : OnBackPressedCallback(true) {
            override fun handleOnBackPressed() {
                finish()
            }
        })
    }
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Android Developer Documentation MCP
Searches official Android Jetpack and API 35 documentation for insets and window handling.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Android Lint Runner
Executes Gradle lint checks to detect hardcoded fitsSystemWindows and deprecated window flags.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Android 15 Edge-to-Edge Layout, Insets Handling, and Predictive Back

Mandatory Android 15 Edge-to-Edge Layout, Insets Handling, and Predictive Back defines an industrial-grade behavioral standard for mobile engineering. Android 15 (API level 35) enforces edge-to-edge layouts by default for applications targeting targetSdk 35, ignoring legacy window flags such as fitsSystemWindows=true on root decors. Failure to explicitly consume WindowInsetsCompat or Compose WindowInsets results in critical visual clipping beneath navigation bars, status bars, and display cutouts. In addition, applications must implement OnBackAnimationCallback or predictiveBackAnimation modifier to handle system back navigations without gesture conflicts. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Relying on deprecated fitsSystemWindows attributes or hardcoded status/nav bar offsets on Android 15 Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftRelying on deprecated fitsSystemWindows attributes or hardcoded status/nav bar offsets on Android 15Critical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Engineers MUST ALWAYS invoke ComponentActivity.enableEdgeToEdge() in onCreate before setContent or setContentView.

Engineers MUST ALWAYS invoke ComponentActivity.enableEdgeToEdge() in onCreate before setContent or setContentView.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT rely on android

Engineers MUST NOT rely on android:fitsSystemWindows="true" on root layouts or windowTranslucentStatus/windowTranslucentNavigation flags in themes for targetSdk 35.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Components MUST consume insets at the leaf interactive layer using Modifier.windowInsetsPadding(WindowInsets.safeDrawing), WindowInsets.systemBars, or ViewCompat.setOnApplyWindowInsetsListener, rather than applying global root padding that breaks full-bleed backgrounds.

Components MUST consume insets at the leaf interactive layer using Modifier.windowInsetsPadding(WindowInsets.safeDrawing), WindowInsets.systemBars, or ViewCompat.setOnApplyWindowInsetsListener, rather than applying global root padding that breaks full-bleed backgrounds.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Nested scrolling containers MUST consume insets via contentPadding (e.g., LazyColumn(contentPadding = WindowInsets.navigationBars.asPaddingValues())) to prevent content from remaining clipped behind the navigation bar at scroll rest.

Nested scrolling containers MUST consume insets via contentPadding (e.g., LazyColumn(contentPadding = WindowInsets.navigationBars.asPaddingValues())) to prevent content from remaining clipped behind the navigation bar at scroll rest.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST handle predictive back gestures using OnBackPressedDispatcher.addCallback with an OnBackAnimationCallback or Jetpack Compose PredictiveBackHandler rather than legacy Activity.onBackPressed override.

Engineers MUST handle predictive back gestures using OnBackPressedDispatcher.addCallback with an OnBackAnimationCallback or Jetpack Compose PredictiveBackHandler rather than legacy Activity.onBackPressed override.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Code MUST explicitly account for display cutouts and waterfall insets using WindowInsetsCompat.Type.displayCutout() alongside systemBars().

Code MUST explicitly account for display cutouts and waterfall insets using WindowInsetsCompat.Type.displayCutout() alongside systemBars().

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is Mandatory Android 15 Edge-to-Edge Layout, Insets Handling, and Predictive Back critical for AI coding assistants?

Android 15 (API level 35) enforces edge-to-edge layouts by default for applications targeting targetSdk 35, ignoring legacy window flags such as fitsSystemWindows=true on root decors. Failure to explicitly consume WindowInsetsCompat or Compose WindowInsets results in critical visual clipping beneath navigation bars, status bars, and display cutouts. In addition, applications must implement OnBackAnimationCallback or predictiveBackAnimation modifier to handle system back navigations without gesture conflicts. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Relying on deprecated fitsSystemWindows attributes or hardcoded status/nav bar offsets on Android 15) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related MOBILE Rules

View all rules →
mobile
106

Tauri 2.0 Mobile IPC & Capabilities Permissions Matrix Standard

Tauri v2 introduces a capability-driven permissions system replacing legacy v1 allowlists across iOS and Android runtimes. Failure to constrain IPC command handlers with typed schemas and explicit mobile capability definitions exposes native mobile OS surfaces to arbitrary code execution, permission leakage, and silent serialization failures. Production mobile deployments require strictly typed IPC boundary validation, granular capability scopes, and graceful permission degradation.

mobile
70

Capacitor 7 Native Bridge, Biometric Auth & Android 15 Lifecycle Production Standard

Capacitor 7 enforces strict bridge lifecycle contracts, asynchronous native plugin interop, and mandatory Android 15 edge-to-edge window inset handling. Storing sensitive authentication tokens in unencrypted web storage or failing to bind biometric authentication directly to hardware-backed Keystore or Secure Enclave mechanisms compromises app integrity and causes fatal crash or viewport occlusion issues on modern mobile operating systems.

mobile
58

Tauri 2.0 Mobile IPC Isolation and Capabilities Permission Scoping

Enforces strict capability permission boundaries, payload validation, and secure IPC invoke scoping for Tauri v2 Android and iOS environments. Prevents arbitrary IPC command execution, excessive native privilege granting, and deserialization vulnerabilities across the mobile webview-native boundary.

1 Rule in Stack

Mandatory