links; doc tweaks

CONTRIBUTING.md

@@ -16,9 +16,14 @@ Start by filing an issue. The existing committers on this project work to reach
 consensus around project direction and issue solutions within issue threads
 (when appropriate).
 
+Please note the following:
+
+* Pull Requests to the plugin-docs repository will be rejected; please file an issue for incorrect documentation instead. This is because we need to ensure that the issue is corrected in the internal source code.
+* Pull Requests to the plugin-samples repository and other repositories in the AdobeXD organization are welcome. Please file an issue first so that your contribution can be discussed.
+
 ## Contributor License Agreement
 
-All third-party contributions to this project must be accompanied by a signed contributor
+All third-party contributions to this project and associated repositories must be accompanied by a signed contributor
 license agreement. This gives Adobe permission to redistribute your contributions
 as part of the project. [Sign our CLA](http://opensource.adobe.com/cla.html). You
 only need to submit an Adobe CLA one time, so if you have submitted one previously,
@@ -27,42 +32,3 @@ you are good to go!
 ## Security Issues
 
 Security issues shouldn't be reported on this issue tracker. Instead, [file an issue to our security experts](https://helpx.adobe.com/security/alertus.html).
-
-## Gitbook Configuration
-
-The GitHub Pages rendering of this documentation is generated using [Gitbook](https://www.gitbook.com/). To preview this rendering locally:
-
-```bash
-npm install
-npm run book:install
-npm run book:build
-
-# Now the generated Gitbook site is in a '_book' folder. It's best viewed from
-# http://localhost (not file://), so start a local web server, e.g.:
-http-server -c-1 _book
-```
-
-### Adding pages
-
-When adding an entirely new documentation page to this site, be sure to add the new file to the correct location in `SUMMARY.MD`. Otherwise your content will not be rendered when the site is published.
-
-### Gitbook plugins in use
-
-Plugin                            | For                                   | Link
----------------------------------:|:--------------------------------------|:-----------------------
-page-toc                          | Page Table of Contents                | https://plugins.gitbook.com/plugin/page-toc
-anchorjs                          | Deep link anchor support              | https://plugins.gitbook.com/plugin/anchorjs
-collapse                          | In-text collapse support              | https://plugins.gitbook.com/plugin/collapse
-search-plus                       | Better searching                      | https://plugins.gitbook.com/plugin/search-plus-normal
-code                              | Code line numbers and copy code btn   | https://plugins.gitbook.com/plugin/code
-dashing                           | Convert dashes to hyphens             | https://plugins.gitbook.com/plugin/dashing
-todo                              | Read only checkboxes                  | https://plugins.gitbook.com/plugin/checkbox
-expandable-chapters-interactive   | Expandable chapters                   | https://plugins.gitbook.com/plugin/expandable-chapters-interactive
-styled-blockquotes                | Hints, etc.                           | https://plugins.gitbook.com/plugin/styled-blockquotes
-recently-updated                  | Include last update link on page      | https://plugins.gitbook.com/plugin/recently-updated
-addcssjs                          | Adding custom styling                 |
-replace                           | Linking functions, etc. between pages |
-simpletabs                        | Tabbed sections of content            |
-components                        | Header and footer customization       |
-github-tables                     | Github GFM for tables                 |
-nestedmd                          | Nested markdown                       |

README.md

@@ -40,8 +40,11 @@ If you've never worked with JavaScript before, we recommend taking a moment to g
 **HTML/CSS**: If you plan to offer a UI for your plugin, some familiarity with HTML and CSS is recommended. XD plugin APIs support a _subset_ of HTML and CSS for creating plugin UI.
 
 ##### Optional
-**React**: If you want to push your plugin UI even further, you can put your React skills to use.
+**React**: If you want to push your plugin UI even further, you can put your React skills to use. React is a great option for complex plugins that must manage both state and user interface. Please refer to the following samples for more about how to configure React:
 
+* [ui-hello-react](https://github.com/AdobeXD/plugin-samples/tree/master/ui-hello-react)
+* [e2e-adobe-stock]https://github.com/AdobeXD/plugin-samples/tree/master/e2e-adobe-stock)
+* [ui-html-playground]https://github.com/AdobeXD/plugin-samples/tree/master/ui-html-playground)
 
 ## Where to start?
 

SUMMARY.md

@@ -52,6 +52,7 @@
     * [Block layout](./reference/ui/layout/block.md)
     * [Flexbox layout](./reference/ui/layout/flex.md)
     * [Positioning](./reference/ui/layout/positioning.md)
+    * [Utility classes](./reference/ui/layout/utility-classes.md)
   * [Elements](./reference/ui/elements/index.md)
     * [Buttons](./reference/ui/elements/buttons.md)
     * [Checkboxes](./reference/ui/elements/checkboxes.md)
@@ -62,14 +63,8 @@
     * [Text fields](./reference/ui/elements/textfields.md)
     * [Tooltips](./reference/ui/elements/tooltips.md)
   * [Modal dialogs](./reference/ui/dialogs/index.md)
-    * [DOM structure](./reference/ui/dialogs/dom-structure.md)
-      * [Building with HTML](./reference/ui/dialogs/building-dialog-with-html.md)
-      * [Building with React](./reference/ui/dialogs/building-dialog-with-react.md)
     * [Showing dialogs](./reference/ui/dialogs/showing.md)
     * [Dismissing dialogs](./reference/ui/dialogs/dismissal.md)
-    * [User experience](./reference/ui/dialogs/ux.md)
-    * [Utility classes](./reference/ui/dialogs/utility-classes.md)
-    * [Helpers](./reference/ui/dialogs/helpers.md)
 * [XD Plugin Experience Guidelines](./xdpegs/index.md)
   * [Introduction](./xdpegs/intro.md)
   * [1.0 Performance](./xdpegs/1-performance.md)

known-issues.md

@@ -26,15 +26,10 @@
 ## User Interface
 
 - Checkboxes may fail to render correctly if in a scrollable container. To work around this issue, make sure the containing element has a background color. (`transparent` does not count; macOS only.)
-- Dialogs are neither movable nor resizable.
-- It is not possible to show multiple dialogs at once, *except* for file and folder pickers.
 - It is not possible to trigger the emoji selector in a text field on macOS.
-- It is not possible to intercept the **ESC** gesture when dismissing a dialog. Dialogs are always dismissible using **ESC**.
 - SVG images are not supported in the UI.
 - When tabbing in a scroll view, the scroll view is not automatically scrolled to ensure the target control is in view (macOS Only).
-- When **TAB**ing in Windows 10, the focus border may appear incorrectly on some elements.
 - Inline layout is not supported. Inline elements will render as `block` elements instead.
-- On Windows 10, the tab order in a dialog's footer may be reversed.
 
 ### HTML Elements
 
@@ -49,7 +44,6 @@
 - `<progress>` is not currently supported.
 - HTML5 input validation is not supported.
 - Images that fail to load will not render any “broken icon” image in place.
-- The `<dialog>` background color is different on Windows and macOS. On macOS, it is `#F5F5F5`, and on Windows it is `#FFFFFF`.
 - Input elements do not accept `defaultValue`.
 - `<input type="password" />` is not supported.
 - `<option>` tags do not support `selected` or `disabled` attributes.

reference/ui/dialogs/index.md

@@ -212,13 +212,101 @@ function render() {
 
 {% endtabs %}
 
-
-* [DOM Structure](./dialogs/dom-structure.md)
-* [Building a Dialog with HTML](./dialogs/building-dialog-with-html.md)
-* [Building a Dialog with React](./dialogs/building-dialog-with-react.md)
-* [Helpers](./dialogs/helpers.md)
-
 Once a dialog is built, you will need to manage its lifecycle:
 
 * [Showing a Modal Dialog](./dialogs/showing.md)
-* [Dismissing a Modal Dialog](./dialogs.dismissal.md)
+* [Dismissing a Modal Dialog](./dialogs/dismissal.md)
+
+## Variations
+
+### Alert
+
+A simple "alert" can be used to display a message along with a **Close** button. You can customize the content of the title and message, but you cannot customize the button itself.
+
+![Example Alert](../assets/helper-alert.png)
+
+E## Error
+
+An error "alert" (with a red heading). These are useful for rendering error messages. Just like regular alerts, you cannot customize the button itself.
+
+![Example Error Alert](./assets/Example%20Error%20Alert.png)
+
+### Confirmation
+
+Confirmation dialogs display a message and _two_ buttons. The user is free to pick which of the buttons they wish to invoke.
+
+![Example Confirmation Dialog](./assets/Example%20Confirmation%20Dialog.png)
+
+> **Danger**
+>
+> Do not use confirmation dialogs for destructive actions.
+
+### Warning
+
+Warning dialogs display a message and _two_ buttons, one of which is destructive. Pressing **ENTER** in this case should _not_ invoke the destructive action. Otherwise it is the same as a confirmation dialog.
+
+![Example Warning Dialog](./assets/Example%20Warning%20Dialog.png)
+
+### Prompt
+
+Prompts display a single line text field in addition to a message and two buttons.
+
+![Example Prompt Dialog](./assets/Example%20Prompt%20Dialog.png)
+
+## Guidelines
+
+You should always strive to provide a good user experience with a modal dialog. That means providing easy access to dismissive buttons, avoiding dark patterns, and ensuring that your dialog doesn't block the user from forward progress in their work.
+
+You should definitely read up on the [experience guidelines](../../../xdpegs/5-ui.md) to learn more about what to do and what not to do.
+
+##### When to Use Dialogs
+
+Dialogs are very intrusive to the user's workflow. As such, you should consider their use very carefully.
+
+* **Don't** display a "success" dialog when the result of the plugin is obvious to the user.
+* **Do** display a "success" dialog when the result of the plugin is **not** obvious to the user (such as data being sent to a remote endpoint.)
+* **Don't** fail silently — let the user know what went wrong and how they can fix it by showing a modal dialog.
+
+##### No Nested Dialogs
+
+You should avoid nesting dialogs within other dialogs. The only exception to this guideline is when displaying file or folder pickers.
+
+##### Three Buttons
+
+In general, try to strive to avoid dialogs with lots of buttons in the footer. You should try to use up to three buttons in the footer.
+
+##### Dismissive Buttons
+
+Dismissive dialog buttons live within a `footer` element. Within the `footer`, you can have any number of buttons, but you should follow these guidelines when defining variants (which you can use to indicate if a button is the default or is destructive):
+
+* `uxp-variant="cta"` indicates that the button is a "call to action". This is typically used for the default action. You should only have one of these buttons in a dialog.
+* `uxp-variant="primary"` indicates the button is a "primary" button. This is the _default_ if `uxp-variant` is not specified.
+* `uxp-variant="secondary"` indicates the button is a "secondary" button. It receives a lighter color than primary buttons.
+* `uxp-variant="warning"` indicates that the button will trigger a destructive action. This button should not be the default action.
+
+> **Tip**
+>
+> Dismissive buttons should always be visible on screen without scrolling. If a dismissive button isn't visible, the user may think they are trapped in the dialog.
+
+##### Dismissal by other means
+
+You should avoid dismissing a dialog using other means, including action buttons, checkboxes, etc.
+
+## Keyboard Interaction
+
+Key       | Action
+----------|----------------------------
+ENTER     | Submits the dialog's form
+ESC       | Cancels the dialog
+TAB       | Moves to the next focusable element.
+SHIFT+TAB | Moves to the previous focusable element.
+
+## Known Issues
+
+- Large dialogs on small screens (or in small windows) do not scroll automatically and will clip. You should apply a fixed height to your dialogs.
+- Dialogs are neither movable nor resizable.
+- It is not possible to show multiple dialogs at once, *except* for file and folder pickers.
+- It is not possible to intercept the **ESC** gesture when dismissing a dialog. Dialogs are always dismissible using **ESC**.
+- When **TAB**ing in Windows 10, the focus border may appear incorrectly on some elements.
+- On Windows 10, the tab order in a dialog's footer may be reversed.
+- The `<dialog>` background color is different on Windows and macOS. On macOS, it is `#F5F5F5`, and on Windows it is `#FFFFFF`.