☂ Reorganize UI adaptation docs

[InMatrix]

We have several different docs related to UI adaptation today:

1. UI > Layout > Creating responsive and adaptive apps. This is a high-level concept doc giving an overview of the terms, the relevant APIs, and some pointers to other resources. Notably, the text part of the doc is focused on responsive layouts. It doesn't introduce APIs (e.g., the Platform class and the Cupertino library) for adapting to platform UI conventions.
2. UI > Layout > Building adaptive apps. This doc was written by gSkinner based on their experience developing the Flutter Folio app. It's mostly focused on desktop platforms (inclusive of desktop web) with mobile mentioned in passing. It addresses topics such as responsive layouts and component differences across desktop platforms.
3. Resources > Platform-specific behaviors and adaptations. This doc is focused on UI adaptation between Android and iOS but currently limited to automatic adaptation supported by the Flutter Framework. We're interested in expanding this doc to include guidance on adapting specific UI components manually (e.g., AlertDialog, AppBar, TextField, etc).

It could be helpful to discuss what the ideal organization of this content. Here's a straw-man proposal:

• Create a new category called Adaptive Design under User Interface. It will be a peer of Layout.
• Under Adaptive Design, rename "Creating responsive and adaptive apps" to "Introduction to creating responsive and adaptive apps" (using shorthand "Introduction" in the left nav).
• In this Intro doc, expand the "Adaptive" section to include key APIs (e.g., Platform) and libraries (e.g., Cupertino and some 3p design language libraries)
• Breaking up "Building adaptive apps" into two docs: 1) "Building responsive Layouts" and 2) " and "Supporting Desktop UI patterns." The latter would include the Input and Idioms and norms section from the original doc.
• Rename "Platform-specific behaviors and adaptations" to "Mobile platform-specific behaviors and adaptations" and move this doc to this new Adaptive Design category.

To recap, this is how the proposed menu hierarchy would look like:

• User interface
  • Layouts
  • Adaptive Design
    • Introduction (Full title: Introduction to creating responsive and adaptive apps)
    • Building responsive Layouts
    • Supporting Desktop UI patterns
    • Platform-specific behaviors and adaptations

@sfshaza2 @leighajarett @nancyhu2023 I'm curious about your thoughts.

---

This should include the following issues:

• [x] https://github.com/flutter/website/issues/4244
• [ ] https://github.com/flutter/website/issues/4306
• [x] https://github.com/flutter/website/issues/6141
• [x] https://github.com/flutter/website/issues/8504
• [x] https://github.com/flutter/website/issues/8678
• [ ] https://github.com/flutter/website/issues/8738
• [ ] https://github.com/flutter/website/issues/5029
• [ ] https://github.com/flutter/website/issues/8427
• [x] https://github.com/flutter/website/issues/8759

[leighajarett]

I like that approach, I'm assuming we would also include "Building adaptive apps" in this new category.

Maybe we should consider naming that doc "Building interfaces that adapt between mobile and desktop" or something more specific?

[InMatrix]

@leighajarett Yes, I just updated my original post to make that clear. I suggest breaking up "Building adaptive apps" to two docs, one focused on responsive layouts and another focused on desktop UI patterns.

[sfshaza2]

I like this, too.

[fredgrott]

@InMatrix a question.

I am looking at from the teaching Flutter App design perspective. Similar front-ends usually have one write the custom adaptive UI nav approach.

Would it be helpful since we need Canonical layouts and one has to rewrite Flutter Adaptive Scaffold using the Adaptive Layout class to just start with the writing adaptive scaffold using the AdaptiveLayout class using Canonical Layouts as the start of the doc?

Yes, for certain seasoned Flutter devs its easy to see that one can take the TwoPane class from MS's dual screen package and just customize an AdaptiveScaffold using the AdaptiveLayout class but I am looking at making as reachable to beginning developer as possible.

My bias, I was a small contributor to the Flutter Platform Widgets project at one point.

BTW, using TwoPane layout eliminates having to use orientation builders and also means the toMaterialGrid methods in Flutter Adaptive Scaffold should no longer be private along with the BrickLayout.

[fredgrott]

Note @InMatrix the platform adaptive widgets Medium article is still up, maybe update that as part of the re-org of adaptive docs? See Do Flutter apps dream of platform aware widgets?

[fredgrott]

There are errors in this doc

https://docs.flutter.dev/platform-integration/platform-adaptations

As we grab platform Flutter is on via Theme.of so that testing with platform simulation works correctly. The platform adaptive code is not currently showing using Theme.of

[InMatrix]

@fredgrott Thank you for your comments. I have a few clarifying questions:

Would it be helpful since we need Canonical layouts and one has to rewrite Flutter Adaptive Scaffold using the Adaptive Layout class to just start with the writing adaptive scaffold using the AdaptiveLayout class using Canonical Layouts as the start of the doc?

I'm not sure I understand your suggestion. If you'd like adding or modifying a particular page on docs.flutter.dev, please open a new issue describing what the problem is in detail, ideally with some example code.

Do Flutter apps dream of platform aware widgets?

Since the Flutter team is not the author of this article, we're not able to update it.

The platform adaptive code is not currently showing using Theme.of

Could you point me to the specific section of the doc where this error exists? I'd appreciate it you can include the correct code in your reply. Thanks.

[fredgrott]

I did find interesting that one could adapt the codelabs animated adaptive responsive scaffold example and MS Surface Duo Flutter examples to use Dual Screen TwoPane widget to finally get canonical layouts. Given that it may be misguided to think that coupling canonical layouts to flutter adaptive scaffold package is good idea as it dramatically ignores how all Nav 2.0 router plugins work in only accepting one child to the shared scaffold.

Sorry, I know its bad news in some assumptions are wrong and that there will be no plug in solution.