From 445b39eb005e694a5e1b9c9c5b41280cac2f2bd5 Mon Sep 17 00:00:00 2001
From: Dave Whitley <drw158@gmail.com>
Date: Fri, 29 Mar 2019 14:04:18 -0500
Subject: [PATCH] Adding design documentation to the Notice readme (#14514)

* Adding design documentation to the Notice readme

* Updating copy based on feedback
---
 packages/components/src/notice/README.md | 81 +++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 3 deletions(-)

diff --git a/packages/components/src/notice/README.md b/packages/components/src/notice/README.md
index 9b0b62937b7f84..16de133c4346ae 100644
--- a/packages/components/src/notice/README.md
+++ b/packages/components/src/notice/README.md
@@ -1,8 +1,79 @@
 # Notice
 
-This component is used to display notices in editor.
+Use Notices to communicate prominent messages to the user.
 
-## Usage
+![Notice component](https://make.wordpress.org/design/files/2019/03/Notice-Screenshot-alt.png)
+
+## Table of contents
+
+1. [Design guidelines](#design-guidelines)
+2. [Development guidelines](#development-guidelines)
+3. [Related components](#related-components)
+
+## Design guidelines
+
+A Notice displays a succinct message. It can also offer the user options, like viewing a published post or updating a setting, and requires a user action to be dismissed.
+
+Use Notices to communicate things that are important but don’t necessarily require action — a user can keep using the product even if they don’t choose to act on a Notice. They are less interruptive than a Modal.
+
+### Anatomy
+
+![Diagram of a Notice component with numbered labels](https://make.wordpress.org/design/files/2019/03/Notice-Anatomy.png)
+
+1. Container (status indicated with color)
+2. Icon (optional)
+3. Message
+4. Dismiss icon (optional)
+
+### Usage
+
+Notices display at the top of the screen, below any toolbars anchored to the top of the page. They’re persistent and non-modal. Since they don’t overlay the content, users can ignore or dismiss them, and choose when to interact with them.
+
+![](https://make.wordpress.org/design/files/2019/03/Notice-States.png)
+
+Notices are color-coded to indicate the type of message being communicated:
+
+- **Default** notices have **no background**.
+- **Informational** notices are **blue.**
+- **Success** notices are **green.**
+- **Warning** notices are **yellow****.**
+- **Error** notices are **red.**
+
+If an icon is included in the Notice, it should be color-coded to match the Notice state.
+
+![A success Notice for updating a post](https://make.wordpress.org/design/files/2019/03/Notice-Do-1-alt.png)
+
+**Do**
+Do use a Notice when you want to communicate a message of medium importance.
+
+![A Notice that requires an immediate action](https://make.wordpress.org/design/files/2019/03/Notice-Dont-1-alt.png)
+
+**Don’t**
+Don't use a Notice for a message that requires immediate attention and action from the user. Use a Modal for this instead.
+
+![A success Notice for publishing a post](https://make.wordpress.org/design/files/2019/03/Notice-Do-2-alt.png)
+
+**Do**
+Do display Notices at the top of the screen, below any toolbars.
+
+![A success Notice on top of the editor toolbar](https://make.wordpress.org/design/files/2019/03/Notice-Dont-2-alt.png)
+
+**Don’t**
+Don't show Notices on top of toolbars.
+
+![An error Notice using red](https://make.wordpress.org/design/files/2019/03/Notice-Do-3-alt.png)
+
+**Do**
+Do use color to indicate the type of message being communicated.
+
+![An error Notice using purple](https://make.wordpress.org/design/files/2019/03/Notice-Dont-3-alt.png)
+
+**Don’t**
+Don't apply any colors other than those for Warnings, Success, or Errors.
+
+## Development guidelines
+
+### Usage
 
 To display a plain notice, pass `Notice` a string:
 
@@ -24,7 +95,7 @@ const MyNotice = () => (
 );
 ```
 
-### Props
+#### Props
 
 The following props are used to control the display of the component.
 
@@ -32,3 +103,7 @@ The following props are used to control the display of the component.
 * `onRemove`: function called when dismissing the notice
 * `isDismissible`: (boolean) defaults to true, whether the notice should be dismissible or not
 * `actions`: (array) an array of action objects. Each member object should contain a `label` and either a `url` link string or `onClick` callback function. A `className` property can be used to add custom classes to the button styles. By default, some classes are used (e.g: is-link or is-default) the default classes can be removed by setting property `noDefaultClasses` to `false`.
+
+## Related components
+
+- To create a more prominent message that requires action, use a Modal.