diff --git a/packages/components/src/panel/README.md b/packages/components/src/panel/README.md
index eefb417b745551..c736ed88b9fa40 100644
--- a/packages/components/src/panel/README.md
+++ b/packages/components/src/panel/README.md
@@ -1,21 +1,94 @@
# Panel
+ Panels expand and collapse multiple sections of content.
+
+
+
+## Table of contents
+
+1. [Design guidelines](#design-guidelines)
+2. [Development guidelines](#development-guidelines)
+3. [Related components](#related-components)
+
+## Design guidelines
+
+### Anatomy
+
+A Panel is a single section of content that can be expanded or collapsed as needed.
+
+
+
+1. Panel
+2. Body
+3. Divider
+
+### Usage
+
+Panels show and hide details of list items by expanding and collapsing list content vertically. Panels help users see only the content they need.
+
+#### When to use Panels
+
+Use Panels when it’s helpful to:
+
+- See an overview of multiple, related sections of content.
+- Show and hide those sections as needed.
+- Hide information that is lower priority that users don’t need to see all the time.
+- View more than one section at a time.
+
+Consider an alternative component when:
+
+- There’s crucial information or error messages that require immediate action.
+- You need to quickly switch between only a few sections (consider using Tabs instead).
+
+### Behavior
+
+#### Expand and collapse
+
+Show and hide details of existing panel items by expanding and collapsing list content vertically.
+
+
+
+Collapsible panels are indicated with a caret icon that is flipped when expanded. Carets are preferable over a plus or arrow icon, because a plus indicates addition, and arrows are closely related to navigation.
+
+Panels should be expanded by default if the content is important or essential. Panels that are open by default should appear at the top.
+
+## Development guidelines
The `Panel` creates a container with a header that can take collapsible `PanelBody` components to easily create a user friendly interface for affecting state and attributes.
-## Sub-Components
+### Usage
-### Panel
+```jsx
+import { Panel, PanelBody, PanelRow } from '@wordpress/components';
+
+const MyPanel = () => (
+
+
+
+ My Panel Inputs and Labels
+
+
+
+);
+```
+
+### Sub-Components
-#### Props
+#### Panel
-##### className
+##### Props
+
+###### className
The class that will be added with `components-panel`. If no `className` is passed only `components-panel__body` and `is-opened` is used.
- Type: `String`
- Required: No
-##### header
+###### header
Title of the `Panel`. Text will be rendered inside an `` tag.
@@ -23,13 +96,13 @@ Title of the `Panel`. Text will be rendered inside an `` tag.
- Required: No
---
-### PanelBody
+#### PanelBody
The `PanelBody` creates a collapsible container that can be toggled open or closed.
-#### Props
+##### Props
-##### title
+###### title
Title of the `PanelBody`. This shows even when it is closed.
@@ -37,35 +110,35 @@ Title of the `PanelBody`. This shows even when it is closed.
- Required: No
-##### opened
+###### opened
If opened is true then the `Panel` will remain open regardless of the `initialOpen` prop and the panel will be prevented from being closed.
- Type: `Boolean`
- Required: No
-##### className
+###### className
The class that will be added with `components-panel__body`, if the panel is currently open, the `is-opened` class will also be passed to the classes of the wrapper div. If no `className` is passed then only `components-panel__body` and `is-opened` is used.
- Type: `String`
- Required: No
-##### icon
+###### icon
An icon to be shown next to the `PanelBody` title.
- Type: `String`
- Required: No
-##### onToggle
+###### onToggle
A function that is called when the user clicks on the `PanelBody` title after the open state is changed.
- Type: `function`
- Required: No
-##### initialOpen
+###### initialOpen
Whether or not the panel will start open.
@@ -74,13 +147,13 @@ Whether or not the panel will start open.
- Default: true
---
-### PanelRow
+#### PanelRow
The is a generic container for panel content. Default styles add a top margin and arrange items in a flex row.
-#### Props
+##### Props
-##### className
+###### className
The class that will be added with `components-panel__row`. to the classes of the wrapper div. If no `className` is passed only `components-panel__row` is used.
@@ -88,35 +161,18 @@ The class that will be added with `components-panel__row`. to the classes of th
- Required: No
---
-### PanelHeader
+#### PanelHeader
This is a simple container for a header component. This is used by the `Panel` component under the hood, so it does not typically need to be used.
-#### Props
+##### Props
-##### label
+###### label
The text that will be rendered as the title of the `Panel`. Will be rendered in an `` tag.
- Type: `String`
- Required: No
-## Usage
-
-```jsx
-import { Panel, PanelBody, PanelRow } from '@wordpress/components';
-
-const MyPanel = () => (
-
-
-
- My Panel Inputs and Labels
-
-
-
-);
-```
+## Related components
+- To divide related sections of content accessed by a horizontal menu, use `TabPanel`