1 files changed, 79 insertions, 0 deletions
diff --git a/packages/SystemUI/docs/dialogs.md b/packages/SystemUI/docs/dialogs.md
new file mode 100644
index 000000000000..e5b4edde39e3
--- /dev/null
+++ b/packages/SystemUI/docs/dialogs.md
@@ -0,0 +1,79 @@
+# Dialogs in SystemUI
+
+### Creating a dialog
+
+### Styling
+
+In order to have uniform styling in dialogs, use [SystemUIDialog][1] with its default theme.
+If not possible, use [AlertDialog][2] with the SystemUI theme `R.style.Theme_SystemUI_Dialog`.
+If needed, consider extending this theme instead of creating a new one.
+
+### Setting the internal elements
+
+The internal elements of the dialog are laid out using the following resources:
+
+* [@layout/alert_dialog_systemui][3]
+* [@layout/alert_dialog_title_systemui][4]
+* [@layout/alert_dialog_button_bar_systemui][5]
+
+Use the default components of the layout by calling the appropriate setters (in the dialog or
+[AlertDialog.Builder][2]). The supported styled setters are:
+
+* `setIcon`: tinted using `attr/colorAccentPrimaryVariant`.
+* `setTitle`: this will use `R.style.TextAppearance_Dialog_Title`.
+* `setMessage`: this will use `R.style.TextAppearance_Dialog_Body_Message`.
+* `SystemUIDialog.set<Positive|Negative|Neutral>Button` or `AlertDialog.setButton`: this will use
+   the following styles for buttons.
+  * `R.style.Widget_Dialog_Button` for the positive button.
+  * `R.style.Widget_Dialog_Button_BorderButton` for the negative and neutral buttons.
+
+  If needed to use the same style for all three buttons, the style attributes
+  `?android:attr/buttonBar<Positive|NegativeNeutral>Button` can be overriden in a theme that extends
+  from `R.style.Theme_SystemUI_Dialog`.
+* `setView`: to set a custom view in the dialog instead of using `setMessage`.
+
+Using `setContentView` is discouraged as this replaces the content completely.
+
+All these calls should be made before `Dialog#create` or `Dialog#show` (which internally calls
+`create`) are called, as that's when the content is installed.
+
+## Showing the dialog
+
+When showing a dialog triggered by clicking on a `View`, you should use [DialogLaunchAnimator][6] to
+nicely animate the dialog from/to that `View`, instead of calling `Dialog.show`.
+
+This animator provides the following methods:
+
+* `showFromView`: animates the dialog show from a view , and the dialog dismissal/cancel/hide to the
+  same view.
+* `showFromDialog`: animates the dialog show from a currently showing dialog, and the dialog
+  dismissal/cancel/hide back to that dialog. The originating dialog must have been shown using
+  `DialogLaunchAnimator`.
+* `dismissStack`: dismisses a stack of dialogs that were launched using `showFromDialog` animating
+  the top-most dialog back into the view that was used in the initial `showFromView`.
+
+## Example
+
+Here's a short code snippet with an example on how to use the guidelines.
+
+```kotlin
+val dialog = SystemUIDialog(context).apply {
+    setIcon(R.drawable.my_icon)
+    setTitle(context.getString(R.string.title))
+    setMessage(context.getString(R.string.message))
+    // Alternatively to setMessage:
+    // val content = LayoutManager.from(context).inflate(R.layout.content, null)
+    // setView(content)
+    setPositiveButton(R.string.positive_button_text, ::onPositiveButton)
+    setNegativeButton(R.string.negative_button_text, ::onNegativeButton)
+    setNeutralButton(R.string.neutral_button_text, ::onNeutralButton)
+}
+dialogLaunchAnimator.showFromView(dialog, view)
+```
+
+[1]: /packages/SystemUI/src/com/android/systemui/statusbar/phone/SystemUIDialog.java
+[2]: /core/java/android/app/AlertDialog.java
+[3]: /packages/SystemUI/res/layout/alert_dialog_systemui.xml
+[4]: /packages/SystemUI/res/layout/alert_dialog_title_systemui.xml
+[5]: /packages/SystemUI/res/layout/alert_dialog_button_bar_systemui.xml
+[6]: /packages/SystemUI/animation/src/com/android/systemui/animation/DialogLaunchAnimator.kt
+\ No newline at end of file