Add an add-to-app landing page (#3265)

src/_data/sidenav.yml

@@ -147,6 +147,8 @@
     - title: Add Flutter to existing app
       permalink: /docs/development/add-to-app
       children:
+      - title: Introduction
+        permalink: /docs/development/add-to-app
       - title: Adding to an Android app
         permalink: /docs/development/add-to-app/android
         children:

src/docs/development/add-to-app/android/add-flutter-fragment.md

@@ -64,11 +64,11 @@ public class MyActivity extends FragmentActivity {
         super.onCreate(savedInstanceState);
 
         // Inflate a layout that has a container for your FlutterFragment. For
-        // this example, assume that a FrameLayout exists with an ID of 
+        // this example, assume that a FrameLayout exists with an ID of
         // R.id.fragment_container.
         setContentView(R.layout.my_activity_layout);
 
-        // Get a reference to the Activity's FragmentManager to add a new 
+        // Get a reference to the Activity's FragmentManager to add a new
         // FlutterFragment, or find an existing one.
         FragmentManager fragmentManager = getSupportFragmentManager();
 
@@ -80,12 +80,12 @@ public class MyActivity extends FragmentActivity {
         // Create and attach a FlutterFragment if one does not yet exist.
         if (flutterFragment == null) {
             flutterFragment = FlutterFragment.createDefault();
-            
+
             fragmentManager
                 .beginTransaction()
                 .add(
-                    R.id.fragment_container, 
-                    flutterFragment, 
+                    R.id.fragment_container,
+                    flutterFragment,
                     TAG_FLUTTER_FRAGMENT
                 )
                 .commit();
@@ -96,9 +96,9 @@ public class MyActivity extends FragmentActivity {
 
 The above code is sufficient to render a Flutter UI that begins with a call to
 your `main()` Dart entrypoint, an initial Flutter route of `/`, and a new
-`FlutterEngine`. However, this code is not sufficient to achieve all expected 
-Flutter behavior. Flutter depends on various OS signals that need to be 
-forwarded from your host `Activity` to `FlutterFragment`. These calls are shown 
+`FlutterEngine`. However, this code is not sufficient to achieve all expected
+Flutter behavior. Flutter depends on various OS signals that need to be
+forwarded from your host `Activity` to `FlutterFragment`. These calls are shown
 below:
 
 ```java
@@ -121,13 +121,13 @@ public class MyActivity extends FragmentActivity {
 
     @Override
     public void onRequestPermissionsResult(
-        int requestCode, 
-        @NonNull String[] permissions, 
+        int requestCode,
+        @NonNull String[] permissions,
         @NonNull int[] grantResults
     ) {
         flutterFragment.onRequestPermissionsResult(
-            requestCode, 
-            permissions, 
+            requestCode,
+            permissions,
             grantResults
         );
     }
@@ -306,7 +306,7 @@ For this reason, Flutter supports translucency in a `FlutterFragment`.
   below and above your Flutter experience, then you must specify a
   `RenderMode` of `texture`. See the previous section titled "Control
   `FlutterFragment`'s render mode" for information on controlling the
-  `RenderMode`. 
+  `RenderMode`.
 {{site.alert.end}}
 
 To enable transparency for a `FlutterFragment`, build it with the following
@@ -331,8 +331,8 @@ would be reasonable for a `Fragment` to control system chrome like Android's
 status bar, navigation bar, and orientation.
 
 {% asset
-development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_fullscreen.png
-class="mw-100" alt="Fullscreen Flutter" %}
+ development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_fullscreen.png
+ class="mw-100" alt="Fullscreen Flutter" %}
 
 In other apps, `Fragment`s are used to represent only a portion of a UI. A
 `FlutterFragment` might be used to implement the inside of a drawer, or a video
@@ -341,13 +341,13 @@ player, or a single card. In these situations, it would be inappropriate for the
 pieces within the same `Window`.
 
 {% asset
-development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_partial-ui.png
-class="mw-100" alt="Flutter as Partial UI" %}
+ development/add-to-app/android/add-flutter-fragment/add-flutter-fragment_partial-ui.png
+ class="mw-100" alt="Flutter as Partial UI" %}
 
 `FlutterFragment` comes with a concept that helps differentiate between the case
 where a `FlutterFragment` should be able to control its host `Activity`, and the
 cases where a `FlutterFragment` should only affect its own behavior. To prevent
-a `FlutterFragment` from exposing its `Activity` to Flutter plugins, and to 
+a `FlutterFragment` from exposing its `Activity` to Flutter plugins, and to
 prevent Flutter from controlling the `Activity`'s system UI, use the
 `shouldAttachEngineToActivity()` method in `FlutterFragment`'s `Builder` as
 shown below.
@@ -370,6 +370,6 @@ value is `true`, which allows Flutter and Flutter plugins to interact with the
 surrounding `Activity`.
 
 {{site.alert.note}}
-  Some plugins may expect or require an `Activity` reference. Ensure that none 
+  Some plugins may expect or require an `Activity` reference. Ensure that none
   of your plugins require an `Activity` before disabling access.
 {{site.alert.end}}

src/docs/development/add-to-app/android/index.md

@@ -0,0 +1,4 @@
+---
+layout: toc
+title: Adding Flutter to Android
+---

src/docs/development/add-to-app/index.md

@@ -1,4 +1,93 @@
 ---
-layout: toc
-title: Add to existing app
+title: Add Flutter to existing app
+description: Adding Flutter as a library to an existing Android or iOS app.
 ---
+
+## Add-to-app
+
+It's sometimes not practical to rewrite your entire application in Flutter all
+at once. For those situations, Flutter can be integrated into your existing
+application in a piecemeal fashion as a library or module. That module can then
+be imported into your Android or iOS (currently supported platforms) app to
+render a part of your app's UI in Flutter. Or just to run shared Dart logic.
+
+In a few steps, you can also bring the productivity and the expressiveness of
+Flutter into your own app.
+
+TODO(xster): add steps overview videos.
+
+As of Flutter release v1.12, add-to-app is supported for basic scenarios with
+the _**following limitations**_:
+
+- One fullscreen Flutter instance at a time. Running multiple Flutter instances
+or in partial screen views may have undefined behaviors.
+- Using Flutter in background mode is still WIP.
+- Packing a Flutter library into another sharable library or packing multiple
+Flutter libraries into an application is not currently supported
+
+## Supported features
+
+### Add to Android applications
+
+- Auto-build and import the Flutter module by adding a Flutter SDK hook to
+  your Gradle script; or
+- Build your Flutter module into a generic [Android AAR](https://developer.android.com/studio/projects/android-library)
+- Android Studio Android/Flutter co-editing and module creation/import wizard
+- Java and Kotlin host apps supported
+
+### Add to iOS applications
+- Auto-build and import the Flutter module by adding a Flutter SDK hook to
+ your CocoaPods and to your Xcode build phase; or
+- Build your Flutter module into a generic [iOS Framework](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html)
+- Objective-C and Swift host apps supported
+
+### Android and iOS
+- Flutter modules can use [Flutter plugins](https://pub.dev/flutter) to interact
+  with the platform
+- Flutter modules support Stateful Hot Reload by using `flutter attach` from
+  IDEs or the command line to connect to an app containing Flutter
+
+See our [add-to-app GitHub Samples repository](https://github.com/flutter/samples/tree/master/experimental/add_to_app)
+for sample projects in Android and iOS that import a Flutter module for UI.
+
+## Get started
+
+To get started, see our project integration guide for
+
+<div class="card-deck mb-8">
+  <a class="card" href="/docs/development/add-to-app/android/project-setup">
+    <div class="card-body">
+      <header class="card-title text-center m-0">
+        Android
+      </header>
+    </div>
+  </a>
+  <a class="card" href="/docs/development/add-to-app/ios/project-setup">
+    <div class="card-body">
+      <header class="card-title text-center m-0">
+        iOS
+      </header>
+    </div>
+  </a>
+</div>
+
+## API usage
+
+Once Flutter has been integrated into your project, see our API usage guides for
+
+<div class="card-deck mb-8">
+  <a class="card" href="/docs/development/add-to-app/android/add-flutter-screen">
+    <div class="card-body">
+      <header class="card-title text-center m-0">
+        Android
+      </header>
+    </div>
+  </a>
+  <a class="card" href="/docs/development/add-to-app/ios/add-flutter-screen">
+    <div class="card-body">
+      <header class="card-title text-center m-0">
+        iOS
+      </header>
+    </div>
+  </a>
+</div>

src/docs/development/add-to-app/ios/index.md

@@ -0,0 +1,4 @@
+---
+layout: toc
+title: Adding Flutter to iOS
+---