System Navigation Bar APIs are Confusing

[a-wallen]

As a starting point, @bleroux classified several issues using this two categories (imperative vs declarative):

Imperative

• [Android] Edge to Edge should only be offered at a higher API #89774 (great summary of edgeToEdge limitations depending on Android version).
• [Android] Streamline Edge-to-Edge and Navigation Bar behavior across Android versions #90098 (lot of good information. Closed because it was splitted in two separate actionable issues: Set Edge-to-Edge to be the default for Android on API 29+ #105714 and [Android] Avoid hidden navigation bar icons #105716
• [Android]Switching between immersive and edgeToEdge system UI modes shows black status bar #95403 (edgeToEdge and device specific)
• [SystemChrome] setting systemNavigationBarColor and statusBarColor to white turns dark #108855 (device specific)
• SystemChrome setSystemUIOverlayStyle failed #59130 (which seems to be a misunderstanding related to an imperative call overridden by the implicit addition of AnnotatedRegion when there is an AppBar).

Declarative

• Using systemNavigationBarDividerColor changes statusBarIconBrightness and systemNavigationBarIconBrightness on Android11 #100027 (with many insights from rydmike about what could be done to improve the documentation, partially fixed by Add missing window flags for styling system bars engine#32167)
• Flutter SystemUiOverlayStyle does not work with some configurations on Android #76384 (fixed by Add missing window flags for styling system bars engine#32167)
• AnnotatedRegion not working on iOS (to set status bar icon color) #54029 (iOS)
• systemNavigationBarColor not honoured on Android #104410 (where I commented systemNavigationBarColor not honoured on Android #104410 (comment) after analyzing various issues and leads me to this PR)
• systemNavigationBarIconBrightness: Brightness.dark resets to light onResume. #21265 (onResume issue where the proposed solution was to switch to the declarative way, but people seems to be confused by AppBar overridden their values, see systemNavigationBarIconBrightness: Brightness.dark resets to light onResume. #21265 (comment))
• Samsung Galaxy S10 System Navigation Bar Icon Brightness Issue #39132 (seems to be the same confusion)

[a-wallen]

This is effectively a fork of the conversation on #104827, I'd like to keep this discussion going even if that PR is merged.

[exaby73]

Hello @a-wallen. Thanks for filing this issue. Could you clarify the goal of this issue?

[a-wallen]

@bleroux may land #104827 regarding some confusion around the SystemNavigation APIs. I'm not sure that the PR will address the root cause of confusion around the API, so I wanted to keep the issues rounded up and tracked in this issue.

[exaby73]

Thanks for the information. Labelling for further insights from the team.

[wytesk133]

Android official documentation no longer mentions legacy semantics like "Lean Back" and "Immersive Sticky." We should consider updating the APIs here as well.