Edge to edge behavior on Android (#13099)

Fixes [12211](#12211)

Staged:
https://flutter-docs-prod--pr13099-edge-to-edge-txq2dpei.web.app/release/breaking-changes/default-systemuimode-edge-to-edge

Author: sfshaza2

src/content/release/breaking-changes/default-systemuimode-edge-to-edge.md

@@ -7,33 +7,39 @@ description: >-
 
 {% render "docs/breaking-changes.md" %}
 
-:::note
-You might have found this page because you see a warning in the Google Play
-Console concerning "Edge-to-edge may not display for all users" or "Your app
-uses deprecated APIs or parameters for edge-to-edge".
-These warnings **will not** impact users.
-
-This warning references deprecated code used in the Flutter engine to implement
-edge-to-edge mode. The engine relies on this deprecated code to avoid breaking
-changes for users, so it will continue to work should you set edge-to-edge
-mode in your app. See [flutter#169810] for more information.
-:::
-
 ## Summary
 
+Edge-to-edge mode is Android's default display behavior as of
+Android version 15 and above. In Android 15, you could
+opt out of this behavior but, as of Android 16, you can't.
+To learn more about this change,
+check out the [Android 16 release notes][].
+
+[Android 16 release notes]: {{site.android-dev}}/about/versions/16/behavior-changes-16#edge-to-edge
+
+## Android 16 (or later)
+
+Using the mechanism to opt out of edge-to-edge on Android 16
+or later might cause your app to crash, but you can avoid this
+by using version-specific resources; for details,
+visit the [migration guide](#migration-guide).
+
+To learn how to structure your app to avoid this,
+we recommend that you visit the Leancode article, [Mastering Edge-To-Edge in Flutter:
+A Deep Dive Into the System Navigation Bar in Android][article].
+You can also find more discussion in [Issue 168635][] on GitHub.
+
+[article]: https://leancode.co/blog/mastering-edge-to-edge-in-flutter
+[Issue 168635]: {{site.github}}/flutter/flutter/issues/168635#issuecomment-3485274018
+
+## Android 15 (and below)
+
 If your Flutter app targets Android SDK version 15,
 your app automatically displays in edge-to-edge mode,
 as documented on the [`SystemUiMode`][] API page.
-To maintain non-edge-to-edge app behavior
+To maintain non edge-to-edge app behavior
 (including an unset `SystemUiMode`),
-follow the steps in [migration guide](#migration-guide).
-
-:::note
-If your Flutter app targets Android SDK version 16 or later,
-your app automatically displays in edge-to-edge mode, and you
-cannot opt-out. To learn more about this change, check out the
-[Android 16 release notes][].
-:::
+follow the steps in the [migration guide](#migration-guide).
 
 [`SystemUiMode`]: {{site.api}}/flutter/services/SystemUiMode.html
 
@@ -44,8 +50,8 @@ target Android 15 or later.
 To learn more about this change, check out the [Android 15 release notes][].
 This impacts devices running on Android SDK 15+ or API 35+.
 
-Prior to Flutter 3.27, Flutter apps target Android 14 by default and
-won't opt into edge-to-edge mode automatically, but
+Prior to Flutter 3.27, Flutter apps targeted Android 14 by default and
+didn't opt into edge-to-edge mode automatically, but
 your app _will_ be impacted when you choose to target Android 15.
 If your app targets `flutter.targetSdkVersion` (as it does by default),
 then it targets Android 15 starting with Flutter version 3.27,
@@ -67,16 +73,14 @@ Be aware of the following:
 
 [edge-to-edge mode]: {{site.android-dev}}/develop/ui/views/layout/edge-to-edge
 [Android 15 release notes]: {{site.android-dev}}/about/versions/15/behavior-changes-15#edge-to-edge
-[Android 16 release notes]: {{site.android-dev}}/about/versions/16/behavior-changes-16#edge-to-edge
 [`SystemChrome.setEnabledSystemUIMode`]: {{site.api}}/flutter/services/SystemChrome/setEnabledSystemUIMode.html
 
 ## Migration guide
 
-To opt out of edge-to-edge on SDK 15, specify
-the new style attribute in each activity that requires it.
+To opt out of edge-to-edge on Android SDK 15,
+specify the new style attribute in each activity that requires it.
 If you have a parent style that child styles need to opt out of,
-you can modify the parent only.
-In the following example,
+you can modify the parent only. In the following example,
 update the style configuration generated from `flutter create`.
 
 By default, the styles used in a Flutter app are set in
@@ -127,7 +131,13 @@ Ensure both styles are updated consistently in both files.
 
 This modified style opts your app out of edge-to-edge for
 apps targeting Android SDK 15.
-So now you're done!
+
+:::note
+If your app runs on Android 16 or above, to avoid crashes you can
+create a `your_app/android/app/src/main/res/values-35` resource
+directory that contains styles without the
+`android:windowOptOutEdgeToEdgeEnforcement` attribute.
+:::
 
 ## Timeline