From 6adfb68fa53b07c898e3c0799d2576f592f6410d Mon Sep 17 00:00:00 2001
From: Dave Whitley <drw158@gmail.com>
Date: Fri, 15 Mar 2019 09:37:27 -0500
Subject: [PATCH] Components: update CheckboxControl readme (#14153)

* Initial commit to update CheckboxControl readme

These changes add design documentation.

* Fix tabbing on code example
---
 .../components/src/checkbox-control/README.md | 70 ++++++++++++++++---
 1 file changed, 61 insertions(+), 9 deletions(-)

diff --git a/packages/components/src/checkbox-control/README.md b/packages/components/src/checkbox-control/README.md
index 2538fda6b3dd0..91b50a09b2d97 100644
--- a/packages/components/src/checkbox-control/README.md
+++ b/packages/components/src/checkbox-control/README.md
@@ -1,9 +1,57 @@
 # CheckboxControl
 
-CheckboxControl component is used to generate a checkbox input field.
+Checkboxes allow the user to select one or more items from a set.
 
+![](https://make.wordpress.org/design/files/2019/02/CheckboxControl.png)
 
-## Usage
+Selected and unselected checkboxes
+
+## Table of contents
+
+1. [Design guidelines](http://#design-guidelines)
+2. [Development guidelines](http://#development-guidelines)
+3. [Related components](http://#related-components)
+
+## Design guidelines
+
+### Usage
+
+#### When to use checkboxes
+
+Use checkboxes when you want users to:
+
+- Select one or multiple items from a list.
+- Open a list containing sub-selections.
+
+![](https://make.wordpress.org/design/files/2019/02/select-from-list.png)
+
+**Do**
+Use checkboxes when users can select multiple items from a list. They let users select more than one item.
+
+![](https://make.wordpress.org/design/files/2019/02/many-form-toggles.png)
+
+**Don’t**
+Don’t use toggles when a list consists of multiple options. Use checkboxes — they take up less space.
+
+![](https://make.wordpress.org/design/files/2019/02/checkbox-sublist.gif)
+
+Checkboxes can be used to open a list containing sub-selections.
+
+#### Parent and child checkboxes
+
+Checkboxes can have a parent-child relationship, with secondary options nested under primary options.
+
+![](https://make.wordpress.org/design/files/2019/02/checkbox-parent.gif)
+
+When the parent checkbox is *checked*, all the child checkboxes are checked. When a parent checkbox is *unchecked*, all the child checkboxes are unchecked.
+
+![](https://make.wordpress.org/design/files/2019/02/mixed-checkbox.png)
+
+If only a few child checkboxes are checked, the parent checkbox becomes a mixed checkbox.
+
+## Development guidelines
+
+### Usage
 
 Render an is author checkbox:
 ```jsx
@@ -23,20 +71,19 @@ const MyCheckboxControl = withState( {
 ) );
 ```
 
-## Props
+### Props
 
 The set of props accepted by the component will be specified below.
 Props not included in this set will be applied to the input element.
 
-### heading
+#### heading
 
 A heading for the input field, that appears above the checkbox. If the prop is not passed no heading will be rendered. 
 
 - Type: `String`
 - Required: No
 
-
-### label
+#### label
 
 A label for the input field, that appears at the side of the checkbox.
 The prop will be rendered as content a label element.
@@ -45,14 +92,14 @@ If no prop is passed an empty label is rendered.
 - Type: `String`
 - Required: No
 
-### help
+#### help
 
 If this property is added, a help text will be generated using help property as the content.
 
 - Type: `String`
 - Required: No
 
-### checked
+#### checked
 
 If checked is true the checkbox will be checked. If checked is false the checkbox will be unchecked.
 If no value is passed the checkbox will be unchecked.
@@ -60,9 +107,14 @@ If no value is passed the checkbox will be unchecked.
 - Type: `Boolean`
 - Required: No
 
-### onChange
+#### onChange
 
 A function that receives the checked state (boolean) as input.
 
 - Type: `function`
 - Required: Yes
+
+## Related components
+
+- To select one option from a set, and you want to show all the available options at once, use the `RadioControl` component.
+- To toggle a single setting on or off, use the `FormToggle` component.