Update & flesh out design handbook

docs/design.md

@@ -0,0 +1,66 @@
+# Gutenberg Design Principles & Vision
+
+This is a living document that outlines the design principles and patterns of the editor interface. Its aim is to explain the background of the design, inform future improvements, and help people design great blocks.
+
+## Principles
+
+![Gutenberg Logo](https://cldup.com/J2MgjuShPv-3000x3000.png)
+
+### Goal of Gutenberg
+
+Gutenberg's all-encompassing goal is a post- and page-building experience that makes it easy to create rich layouts.
+
+From the [kickoff post](https://make.wordpress.org/core/2017/01/04/focus-tech-and-design-leads/):
+
+> The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.
+
+We can extract a few key principles from this:
+
+- **Authoring rich posts is a key strength of WordPress.**
+- **Blocks will unify features and types of interaction under a single interface.** Users shouldn’t have to write shortcodes, custom HTML, or paste URLs to embed. Users only need to learn how the block works in order to use all of its features.
+- **Gutenberg makes core features more discoverable**, reducing hard-to-find “Mystery meat.” WordPress supports a large number of blocks and 30+ embeds. Let’s increase their visibility.
+
+### Why
+
+One thing that sets WordPress apart from other systems is that it allows users to create as rich a post layout as they can imagine — as long as they know HTML and CSS and build a custom theme.
+
+Gutenberg reshapes the editor into tool that allows users write rich posts and build beautiful layouts in a few clicks — no technical knowledge needed. WordPress will become a powerful and flexible content tool that’s accessible to all.
+
+### Vision
+
+Gutenberg wants to make it easier to author rich content. This means ensuring good defaults, bundling advanced layout options into blocks, and making the most important actions immediately available. Authoring content with WordPress should be accessible to anyone.
+
+**Everything on a WordPress website becomes a block:** text, images, galleries, widgets, shortcodes, and even chunks of custom HTML, whether added by plugins or otherwise. Users will only have to learn a single interface —— the block interface.
+
+**All blocks are created equal.** They all live in the same inserter interface. Recency, search, tabs, and grouping ensure that the most-used blocks are within easy reach.
+
+**Drag-and-drop is secondary.** For greater accessibility and platform compatibility, drag-and-drop interactions are used as an additive enhancement on top of explicit actions like click, tab, and space.
+
+**Placeholders are key.** If a block can have a neutral placeholder state, it should. An image placeholder block shows a button to open the media library, and a text placeholder block shows a writing prompt. By embracing placeholders we can predefine editable layouts, so all users have to do is fill in the blanks.
+
+**Direct manipulation is intuitive.** The block interface allows users to manipulate content directly on the page. Plugin and theme authors will support and extend this experience by building their own custom blocks.
+
+**Code editing shouldn't be necessary for customization.** Customizing traditionally required complicated markup, and complicated markup is easy to break. With Gutenberg, customizing becomes more intuitive — and safer. A developer will be able to provide custom blocks that directly render portions of a layout (a three column grid of features, for instance) and clearly specify what can be directly edited by the user. That means the user can update text, swap images, reduce the number of columns, without having to ask a developer, or worrying about breaking things.
+
+### Future Opportunities
+
+The initial phase of Gutenberg as described in the kickoff goal is primarily limited to the content area (specifically `post_content`) of posts and pages. Within those confines, we are embracing the web as a vertical river of content by appending blocks sequentially, then adding layout options to each block.
+
+That said, there isn’t any fixed limit to the kind of layouts Gutenberg will be able to create. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page — one could think of a theme template as a comma separated list of blocks, like this:
+
+```
+{
+	'theme/header',
+	'theme/sidebar',
+	'core/content' {
+		'core/cover-image',
+		'theme/author-card',
+		'core/text',
+	},
+	'theme/footer',
+}
+```
+
+Every block nested inside the content block would be _rearrangeable_. Every block would be _editable_. Every block would use the same API, and both the editor and the theme would load the same `style.css` file directly. In the end, both the editor/page builder and theme/front-end would appear near-identical, allowing for a true WYSIWYG experience.
+
+This concept is speculative, but it’s one direction Gutenberg could go in the future.

docs/design/block-design.md

@@ -0,0 +1,84 @@
+# Block Design
+
+The following is a light guide to designing a new block with recommendations and detailed descriptions of existing blocks to illustrate good practices.
+
+## Best Practices
+
+- Blocks should have a simple label for the Inserter. Keep it as short as possible.
+- Blocks should have an identifying icon, ideally using a single color. Try to avoid using the same icon used by an existing block. Look to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration.
+- Blocks should have a instructive placeholder state when they’re first inserted. If the block includes a text input, provide placeholder text. If your block holds media, include buttons for uploading files and accessing media libraries, as well as drop-zones for drag-and-drop. 
+- When unselected, your block should preview its content as closely to the front-end output as possible.
+- When selected, your block may surface additional options like input fields or buttons to configure the block directly, if those are necessary for basic operation.
+- Every block should include a description in the “Block” tab of the Settings sidebar. The description should explain as clearly as possible what your block does. Keep it to a single sentence.
+- The “Block” tab of the Settings Sidebar can contain additional block options and configuration, but keep in mind that a user might dismiss the sidebar and never use it. Do not put critical options there.
+- Check how your block looks, feels, and works on all sorts of devices and screen sizes.
+
+## Examples
+
+To demonstrate some of these practices, here are a few annotated examples of default Gutenberg blocks:
+
+### Paragraph
+
+The most basic unit of the editor. The paragraph block is a simple input field.
+
+![Paragraph Block](https://cldup.com/HVJe5bGZ8H-3000x3000.png)
+
+**Placeholder:**
+
+- Simple placeholder text that says “Add text or type / to add content.” The placeholder disappears when the block is selected.
+
+**Selected state:**
+
+- Block Toolbar: Has a switcher to perform transformations to headings, etc.
+- Block Toolbar: Has basic text alignments
+- Block Toolbar: Has inline formatting options, bold, italic, strikethrough and link
+
+### Image
+
+Basic image block.
+
+![Image Block Placeholder](https://cldup.com/w6FNywNsj1-3000x3000.png)
+
+**Placeholder:**
+
+- A generic gray placeholder block with options to upload an image, drag and drop an image directly on it, or pick an image from the media library.
+
+**Selected state:**
+
+- Block Toolbar: Alignments, including wide and full-width if the theme supports it.
+- Block Toolbar: Edit Image, to open the Media Library
+- Block Toolbar: Link button
+- When an image is uploaded, a caption input field appears with a “Write caption…” placeholder text below the image:
+
+![Image Block](https://cldup.com/6YYXstl_xX-3000x3000.png)
+
+**Block settings:**
+
+- Has description: “They're worth 1,000 words! Insert a single image.”
+- Has options for changing or adding alt text and adding additional custom CSS classes.
+
+_Future improvements to the Image block could include getting rid of the media modal, in place of letting users select images directly from the placeholder itself. In general, try to avoid modals._
+
+### Latest Post
+
+![Latest Post Block](https://cldup.com/8lyAByDpy_-3000x3000.png)
+
+**Placeholder:**
+
+Has no placeholder, as it works immediately upon insertion. The default inserted state shows the last 5 posts.
+
+**Selected state:**
+
+- Block Toolbar: Alignments
+- Block Toolbar: Options for picking list view or grid view
+
+_Note that the Block Toolbar does not include the Block Chip in this case, since there are no similar blocks to switch to._
+
+**Block settings:**
+
+- Has description: “Display a list of your most recent posts.”
+- Has options for post order, narrowing the list by category, changing the default number of posts to show, and showing the post date.
+
+_Latest Posts is fully functional as soon as it’s inserted, because it comes with good defaults._
+
+

docs/design/design-patterns.md

@@ -0,0 +1,65 @@
+# Patterns
+
+## Basic Editor Interface
+
+Gutenberg’s general layout uses on a bar at the top, with content below.
+
+![Editor Interface](https://cldup.com/VWA_jMcIRw-3000x3000.png)
+
+The **Toolbar** contains document-level actions: Editor mode, save status, global actions for undo/redo/insert, the settings toggle, and publish options.
+
+The **Content Area** contains the document itself.
+
+The **Settings Sidebar** contains additional settings for the document (tags, categories, schedule etc.) and for blocks in the “Block” tab. A cog button in the toolbar hides the Settings Sidebar, allowing the user to enjoy a more immersive writing experience. On small screens, the sidebar is hidden by default. 
+
+## The Block Interface
+
+The block itself is the most basic unit of the editor. Generally speaking, everything is a block. Users build posts and pages using blocks, mimicking the vertical flow of the underlying HTML markup. 
+
+By surfacing each section of the document as a manipulatable block, we surface block-specific features contextually. This is inspired by desktop app conventions, and allows for a breadth of advanced features without weighing down the UI. 
+
+A selected block shows a number of contextual actions:
+
+![Block Interface](https://cldup.com/3tQqIncKPB-3000x3000.png)
+
+The block interface has basic actions. Gutenberg aims for good, common defaults, so users should be able to create a complete document without actually needing the advanced actions in the Settings Sidebar.
+
+**The Block Toolbar** highlights commonly-used actions. The **Block Chip** lives in the block toolbar, and contains high-level controls for the selected block. It primarily allows users to transform a block into another type of compatible block. Some blocks also use the block chip to users to choose from a set of alternate block styles.
+
+The **Block Formatting** options let users adjust block-level settings, and the **Inline Formatting** options allow adjustments to elements inside the block. When a block is long, the block toolbar pins itself to the top of the screen as the user scrolls down the page.
+
+Blocks can be moved up and down via the **Block Mover** icons on the left. Additional block actions are available on the right via an ellipsis menu: deleting and duplicating blocks, as well as **advanced actions** like “Edit as HTML” and “Convert to Reusable Block.”
+
+An unselected block does not show the block toolbar or any other contextual controls. In effect, an unselected block is a preview of the content itself:
+
+![Unselected Block](https://cldup.com/DH9HZnEgwH-3000x3000.png)
+
+Please note that selection and focus can be different. An image block can be selected while the focus is on the caption field.
+
+## Settings Sidebar
+
+![Settings Sidebar](https://cldup.com/iAqrn6Gc8o-3000x3000.png)
+
+The sidebar has two tabs, Document and Block:
+
+- The **Document Tab** shows metadata and settings for the post or page being edited.
+- The **Block Tab** shows metadata and settings for the currently selected block.
+
+Each tab has sets of editable fields (**Sidebar Sections**) that users can toggle open or closed. 
+
+If a block requires advanced configuration, those settings should live in the Settings sidebar (Editor block settings can also be reached directly by clicking the cog icon next to a block). Don’t put anything in the sidebar block tab that is necessary for the basic operation of your block; your user might dismiss the sidebar for an immersive writing experience. Pick good defaults, and make important actions available in the block toolbar.
+
+Actions that could go in the block tab of the sidebar could be:
+
+- Drop cap, for text
+- Number of columns for galleries
+- Number of posts, or category, in the “Latest Posts” block
+- Any configuration that you don’t need access to in order to perform basic tasks
+
+## Block Library
+
+![Block Library](https://cldup.com/7QoQIoLk-A-3000x3000.png)
+
+The **Block Library** appears when someone inserts a block, whether via the toolbar, or contextually within the content area. Inside, blocks are organized into expandable sections. The block library’s search bar auto-filters the list of blocks as the user types. Users can choose a block by selecting the **Block Button** or the **Block Name**. 
+
+**Parent Blocks** (Blocks that contain children blocks) are represented by a layered block button.

docs/design/design-resources.md

@@ -0,0 +1,11 @@
+# Resources
+
+The [SketchPress](https://github.com/10up/SketchPress) project includes a library of Gutenberg design components helpful for designing and prototyping Gutenberg and Gutenberg blocks:
+
+[Download Sketch mockups & patterns files](https://github.com/10up/SketchPress)
+
+These components are built to be used in [Sketch](https://www.sketchapp.com) for Mac. Users on other platforms may have luck importing the file to [Figma](https://www.figma.com) (Mac/Windows/Linux) or [Lunacy](https://icons8.com/lunacy) (Windows).
+
+Please note that these are mockups, so they may not be 1:1 accurate. It is also possible that the Sketch files aren’t up to date with the latest version of Gutenberg itself, as development sometimes moves faster than the Sketch updates.
+
+If you have questions, please don’t hesitate to ask in the #design channel on the WordPress community Slack.

docs/manifest.json

@@ -77,6 +77,30 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/extensibility/autocomplete.md",
 		"parent": "extensibility"
 	},
+	{
+		"title": "Design",
+		"slug": "design",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design.md",
+		"parent": null
+	},
+	{
+		"title": "Patterns",
+		"slug": "design-patterns",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/design-patterns.md",
+		"parent": "design"
+	},
+	{
+		"title": "Block Design",
+		"slug": "block-design",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/block-design.md",
+		"parent": "design"
+	},
+	{
+		"title": "Resources",
+		"slug": "design-resources",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/design-resources.md",
+		"parent": "design"
+	},
 	{
 		"title": "Creating Block Types",
 		"slug": "blocks",
@@ -131,12 +155,6 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/reference/glossary.md",
 		"parent": "reference"
 	},
-	{
-		"title": "Design Principles",
-		"slug": "design-principles",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/reference/design-principles.md",
-		"parent": "reference"
-	},
 	{
 		"title": "History",
 		"slug": "history",

docs/reference.md

@@ -1,7 +1,6 @@
 # Reference
 
 - [Glossary](../docs/reference/glossary.md)
-- [Design Principles](../docs/reference/design-principles.md)
 - [Coding Guidelines](../docs/reference/coding-guidelines.md)
 - [Testing Overview](../docs/reference/testing-overview.md)
 - [Frequently Asked Questions](../docs/reference/faq.md)