Update DropdownMenu readme (#13410)

Adding documentation to describe the use and functionality of the DropdownMenu component.

Thanks @sarahmonster and @jasmussen for drafting this.

packages/components/src/dropdown-menu/README.md

@@ -1,8 +1,60 @@
-# Dropdown Menu
+# DropdownMenu
 
-Dropdown Menu is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button.
+The DropdownMenu displays a list of actions (each contained in a MenuItem, MenuItemsChoice, or MenuGroup) in a compact way. It appears in a Popover after the user has interacted with an element (a button or icon) or when they perform a specific action. 
 
-## Usage
+![An expanded DropdownMenu, containing a list of MenuItems.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuExample.png)
+
+## Table of contents
+
+1. [Design guidelines](#design-guidelines)
+2. [Development guidelines](#development-guidelines)
+
+## Anatomy
+
+![Anatomy of a DropdownMenu.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuAnatomy.png)
+
+1. Popover: a container component in which the DropdownMenu is wrapped.
+2. Parent button: the icon or button that is used to toggle the display of the Popover containing the DropdownMenu.
+3. MenuItem: the list items within the DropdownMenu.
+
+## Design guidelines
+
+### Usage
+
+#### When to use a DropdownMenu
+
+Use a DropdownMenu when you want users to:
+
+- Choose an action or change a setting from a list, AND
+- Only see the available choices contextually.
+
+If you need to display all the available options at all times, consider using a Toolbar instead.
+
+![Use a DropdownMenu to display a list of actions after the user interacts with an icon.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuDo.png)
+
+**Do**
+Use a DropdownMenu to display a list of actions after the user interacts with an icon.
+
+![Don’t use a DropdownMenu for important actions that should always be visible. Use a Toolbar instead.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuDont.png)
+
+**Don’t**
+Don’t use a DropdownMenu for frequently used actions. Use a Toolbar instead.
+
+#### Behavior
+
+Generally, the parent button should have a triangular icon to the right of the icon or text to indicate that interacting with it will show a DropdownMenu. In rare cases where the parent button directly indicates that there'll be more content (through the use of an ellipsis or "More" label), this can be omitted.
+
+The parent button should retain the same visual styling regardless of whether the DropdownMenu is displayed or not.
+
+#### Placement
+
+The DropdownMenu should typically appear directly below, or below and to the left of, the parent button. If there isn’t enough space below to display the full DropdownMenu, it can be displayed instead above the parent button.
+
+## Development guidelines
+
+DropdownMenu is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button.
+
+### Usage
 
 Render a Dropdown Menu with a set of controls:
 
@@ -39,11 +91,11 @@ const MyDropdownMenu = () => (
 );
 ```
 
-## Props
+### Props
 
 The component accepts the following props:
 
-### icon
+#### icon
 
 The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug to be shown in the collapsed menu button.
 
@@ -53,14 +105,14 @@ The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug to
 
 See also: [https://developer.wordpress.org/resource/dashicons/](https://developer.wordpress.org/resource/dashicons/)
 
-### label
+#### label
 
 A human-readable label to present as accessibility text on the focused collapsed menu button.
 
 - Type: `String`
 - Required: Yes
 
-### controls
+#### controls
 
 An array of objects describing the options to be shown in the expanded menu.