From 6f7fc0990cb87b8f71ecfac4f1ee18a040fea027 Mon Sep 17 00:00:00 2001
From: Kjell Reigstad <kjell@kjellr.com>
Date: Fri, 15 Mar 2019 16:09:07 -0400
Subject: [PATCH] Add MenuGroup design documentation (#14466)

* Update MenuGroup Readme.

Add design guidelines and screenshots.

* Adjust introduction to be more concise.
---
 packages/components/src/menu-group/README.md | 33 +++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/packages/components/src/menu-group/README.md b/packages/components/src/menu-group/README.md
index b40a902b01370..3a6c21791cae0 100644
--- a/packages/components/src/menu-group/README.md
+++ b/packages/components/src/menu-group/README.md
@@ -1,6 +1,31 @@
 # MenuGroup
 
-## Usage
+`MenuGroup` wraps a series of related `MenuItem` components into a common section.
+
+![MenuGroup Example](https://wordpress.org/gutenberg/files/2019/03/MenuGroup.png)
+
+1. MenuGroup
+
+## Table of Contents
+
+1. [Design guidelines](#design-guidelines)
+2. [Development guidelines](#development-guidelines)
+3. [Related components](#related-components)
+
+## Design guidelines
+
+### Usage
+
+A `MenuGroup` should be used to indicate that two or more individual MenuItems are related. When other menu items exist above or below a `MenuGroup`, the group should have a divider line between it and the adjacent item. A MenuGroup can optionally include a label to describe its contents. 
+
+![MenuGroup diagram with label and dividers](https://wordpress.org/gutenberg/files/2019/03/MenuGroup-Anatomy.png)
+
+1. MenuGroup label
+2. MenuGroup dividers
+
+## Development guidelines
+
+### Usage
 
 ```jsx
 import { MenuGroup, MenuItem } from '@wordpress/components';
@@ -12,3 +37,9 @@ const MyMenuGroup = () => (
 	</MenuGroup>
 );
 ```
+
+## Related Components
+
+- `MenuGroup`s are intended to be used in a `DropDownMenu`.
+- To use a single button in a menu, use `MenuItem`.
+- To allow users to toggle between a set of menu options, use `MenuItemsChoice` inside of a `MenuGroup`.