Update TabPanel readme (WordPress#13317)

* Update TabPanel readme

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

Thanks @melchoyce and @alexislloyd for drafting this.

* Remove extra space.

* Decrease headling levels.

The page title should be the only H1, so everything else needs to get pushed down one level.

packages/components/src/tab-panel/README.md

@@ -1,12 +1,58 @@
 # TabPanel
 
-TabPanel is a React component to render an ARIA-compliant TabPanel. It has two sections: a list of tabs, and the view to show when tabs are chosen. When the list of tabs gets focused, the active tab gets focus (the first tab if there isn't one already). Use the arrow keys to navigate between tabs AND select the newly focused tab at the same time.
+TabPanel is a React component to render an ARIA-compliant TabPanel. 
 
-TabPanel is a Function-as-Children component. The function takes the active tab object as as an argument.
+TabPanels organize content across different screens, data sets, and interactions. It has two sections: a list of tabs, and the view to show when tabs are chosen. 
 
-## Usage
+![The “Document” tab selected in the sidebar TabPanel.](https://wordpress.org/gutenberg/files/2019/01/s_E36D9C9B8FFA15A1A8CE224E422535A12B016F88884089575F9998E52016A49F_1541785098230_TabPanel.png)
 
-Renders a TabPanel with each tab representing a paragraph with its title.
+## Table of contents
+
+1. Design guidelines
+2. Development guidelines
+
+## Design guidelines
+
+### Usage
+
+TabPanels organize and allow navigation between groups of content that are related and at the same level of hierarchy.
+
+#### Tabs in a set
+As a set, all tabs are unified by a shared topic. For clarity, each tab should contain content that is distinct from all the other tabs in a set. 
+
+### Anatomy
+
+![](https://wordpress.org/gutenberg/files/2019/01/s_E36D9C9B8FFA15A1A8CE224E422535A12B016F88884089575F9998E52016A49F_1541787297310_TabPanelAnatomy.png)
+
+1. Container
+2. Active text label
+3. Active tab indicator
+4. Inactive text label
+5. Tab item
+
+#### Labels
+
+Tab labels appear in a single row, in the same typeface and size. Use text labels that clearly and succinctly describe the content of a tab, and make sure that a set of tabs contains a cohesive group of items that share a common characteristic.
+
+Tab labels can wrap to a second line, but do not add a second row of tabs.
+
+#### Active tab indicators
+
+To differentiate an active tab from an inactive tab, apply an underline and color change to the active tab’s text and icon.
+
+![An underline and color change differentiate an active tab from the inactive ones.](https://wordpress.org/gutenberg/files/2019/01/s_E36D9C9B8FFA15A1A8CE224E422535A12B016F88884089575F9998E52016A49F_1541787691601_TabPanelActiveTab.png)
+
+### Behavior
+
+Users can navigate between tabs by tapping the tab key on the keyboard.
+
+### Placement
+
+Place tabs above content. Tabs control the UI region displayed below them.
+
+## Development guidelines
+
+### Usage
 
 ```jsx
 import { TabPanel } from '@wordpress/components';
@@ -38,35 +84,35 @@ const MyTabPanel = () => (
 );
 ```
 
-## Props
+### Props
 
 The component accepts the following props:
 
-### className
+#### className
 
 The class to give to the outer container for the TabPanel
 
 - Type: `String`
 - Required: No
 - Default: ''
 
-### orientation
+#### orientation
 
 The orientation of the tablist (`vertical` or `horizontal`)
 
 - Type: `String`
 - Required: No
 - Default: `horizontal`
 
-### onSelect
+#### onSelect
 
 The function called when a tab has been selected. It is passed the `tabName` as an argument.
 
 - Type: `Function`
 - Required: No
 - Default: `noop`
 
-### tabs
+#### tabs
 
 A list of tabs where each tab is defined by an object with the following fields:
 
@@ -79,23 +125,23 @@ Other fields may be added to the object and accessed from the child function if
 - Type: Array
 - Required: Yes
 
-### activeClass
+#### activeClass
 
 The class to add to the active tab
 
 - Type: `String`
 - Required: No
 - Default: `is-active`
 
-### initialTabName
+#### initialTabName
 
 Optionally provide a tab name for a tab to be selected upon mounting of component. If this prop is not set, the first tab will be selected by default.
 
 - Type: `String`
 - Required: No
 - Default: none
 
-### children
+#### children
 
 A function which renders the tabviews given the selected tab. The function is passed the active tab object as an argument as defined the the tabs prop.
 The element to which the tooltip should anchor.