Add guidance for adapting alert dialogs (#8429)

_Description of what this PR is changing or adding, and why:_

This PR adds guidance for alert dialogs to [Platform-specific behaviors
and adaptations
](https://docs.flutter.dev/resources/platform-adaptations). This is the
first of a few cross-platform adaptation guides we're developing. The
goal is to address #8427 over
time.

_Issues fixed by this PR (if any):_

#8427 

## Presubmit checklist
- [X] This PR doesn’t contain automatically generated corrections
(Grammarly or similar).
- [x] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style) — for example, it
doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person).
- [x] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/master/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

---------

Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>

_config.yml

@@ -19,6 +19,7 @@ repo:
   plugins: https://github.com/flutter/plugins
   gallery: https://github.com/flutter/gallery
   engine: https://github.com/flutter/engine
+  uxr: https://github.com/flutter/uxr
 dart:
   api: https://api.dart.dev
   sdk:

src/resources/platform-adaptations.md

@@ -28,6 +28,12 @@ For an example of an app using different information
 architecture structures on Android and iOS but sharing
 the same content code, see the [platform_design code samples][].
 
+{{site.alert.info}}
+Preliminary guides addressing case 2 
+are being added to the UI components section. 
+You can request additional guides by commenting on [issue #8427][].
+{{site.alert.end}}
+
 ## Page navigation
 
 Flutter provides the navigation patterns seen on Android
@@ -548,6 +554,85 @@ double tap and shows the selection toolbar.
   </div>
 </div>
 
+## UI components
+
+This section includes preliminary recommendations on how to adapt 
+Material widgets to deliver a natural and compelling experience on iOS. 
+Your feedback is welcomed on [issue #8427][]. 
+
+### Alert dialog
+
+Since Android 12, the default UI of alert dialogs 
+(also known as a "basic dialog") follows the design guidelines 
+defined in [Material 3][m3-dialog] (M3). 
+On iOS, an equivalent component called “alert” is defined in Apple’s 
+[Human Interface Guidelines][hig-alert] (HIG).
+
+<div class="container">
+  <div class="row">
+    <div class="col-sm text-center">
+      <figure class="figure">
+        <img src="/assets/images/docs/platform-adaptations/m3-alert.png" 
+        class="figure-img img-fluid rounded" alt="Basic Dialog in Material 3" />
+        <figcaption class="figure-caption">
+          Basic Dialog in M3
+        </figcaption>
+      </figure>
+    </div>
+    <div class="col-sm">
+      <figure class="figure text-center">
+        <img src="/assets/images/docs/platform-adaptations/cupertino-alert.png" 
+        class="figure-img img-fluid rounded" alt="Alert in Human Interface Guidelines" />
+        <figcaption class="figure-caption">
+          Alert in HIG
+        </figcaption>
+      </figure>
+    </div>
+  </div>
+</div>
+
+Since alert dialogs are often tightly integrated with the operating system, 
+their design generally needs to follow the platform conventions. 
+This is especially important when a dialog is used to request user input 
+about security, privacy, and destructive operations (e.g., deleting files 
+permanently). As an exception, a branded alert dialog design can be used on 
+non-critical user flows to highlight specific information or messages.
+
+To implement platform-specific alert dialogs, 
+you can use Flutter’s `AlertDialog` widget on Android 
+and the `CupertinoAlertDialog` widget on iOS. Below is a code snippet you can 
+adapt to show a platform-specific alert dialog.
+
+```dart
+void _showAdaptiveDialog(
+  context, {
+  required Text title,
+  required Text content,
+  required List<Widget> actions,
+}) {
+  Platform.isIOS || Platform.isMacOS
+      ? showCupertinoDialog<String>(
+          context: context,
+          builder: (BuildContext context) => CupertinoAlertDialog(
+            title: title,
+            content: content,
+            actions: actions,
+          ),
+        )
+      : showDialog(
+          context: context,
+          builder: (BuildContext context) => AlertDialog(
+            title: title,
+            content: content,
+            actions: actions,
+          ),
+        );
+}
+```
+
+Further detail about adapting alert dialogs is available in 
+[this post][alert-post], where you can leave feedback or ask questions.
+
 
 [issue #8410]: {{site.repo.flutter}}/issues/8410#issuecomment-468034023
 [android.app.AlertDialog]: {{site.android-dev}}/reference/android/app/AlertDialog.html
@@ -565,3 +650,7 @@ double tap and shows the selection toolbar.
 [slides up and fades in]: {{site.api}}/flutter/material/FadeUpwardsPageTransitionsBuilder-class.html
 [`startActivity()`]: {{site.android-dev}}/reference/android/app/Activity.html#startActivity(android.content.Intent
 [`WidgetsApp`]: {{site.api}}/flutter/widgets/WidgetsApp-class.html
+[issue #8427]: {{site.repo.this}}/issues/8427
+[m3-dialog]: https://m3.material.io/components/dialogs/overview
+[hig-alert]: https://developer.apple.com/design/human-interface-guidelines/components/presentation/alerts/
+[alert-post]: {{site.repo.uxr}}/discussions/92