From 008c9cedffdaba39b361e4b550195cd8ffeeb3c3 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Wed, 8 Aug 2018 13:11:52 -0400 Subject: [PATCH 01/13] Adding revised design handbook strucutre + content --- docs/design.md | 62 ++++++++++++++++++++++++ docs/design/block-design.md | 83 +++++++++++++++++++++++++++++++++ docs/design/design-patterns.md | 65 ++++++++++++++++++++++++++ docs/design/design-resources.md | 11 +++++ 4 files changed, 221 insertions(+) create mode 100644 docs/design.md create mode 100644 docs/design/block-design.md create mode 100644 docs/design/design-patterns.md create mode 100644 docs/design/design-resources.md diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 000000000000..f136913bb937 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,62 @@ +# Gutenberg Design Principles & Vision + +This living document serves to describe some of the design principles and patterns that have served in designing the editor interface. The purpose is to explain the background for the design, to help inform future improvements, and to define how a great block should be designed. + +## Principles + +![Gutenberg Logo](https://cldup.com/J2MgjuShPv-3000x3000.png) + +### Goal of Gutenberg + +The all-encompassing goal of Gutenberg is to create a post and page building experience that makes it easy to create rich post 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 it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery. + +We can extract from this the following: + +- **Authoring rich posts is a key strength of WordPress.** +- **The block concept aims to unify multiple different interfaces under a single umbrella.** Users shouldn’t have to write shortcodes, custom HTML or paste URLs to embed. Users should only have to learn how the block works, and then know how to do everything. +- **Gutenberg ams to make core features discoverable.** “Mystery meat” refers to hard to find features in software. WordPress supports a large amount of blocks and 30+ embeds, so 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 — but only if they know HTML & CSS and build their own custom theme. By thinking of the editor as a tool to let users write rich posts, and in a few clicks create beautiful layouts, hopefully, we can make people start to love WordPress and what it can do for their content, as opposed to pick it because it installed with one click. + +### Vision + +Gutenberg aims to make it much easier to author rich content. This is achieved by 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 is a block.** Text, images, galleries, widgets, shortcodes, and even chunks of custom HTML, no matter if it’s added by plugins or otherwise. Users should only have to learn a single interface: the block interface. + +**All blocks are created equal.** They all live in the same inserter interface. We use recency, search, tabs, and grouping, to ensure the blocks users use the most are easily within reach. + +**Drag and drop is secondary.** For greater accessibility and platform compatibility, drag and drop is used as an additive enhancement on top of more explicit actions (like click, tab, and 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.** The blocks interface allows users to manipulate content directly on the page. Plugin and theme authors will support and extend this experience by creating their own custom blocks. + +**Customization.** What previously required using complicated markup and shielding users from breaking it — through shortcodes, meta-fields, etc. — becomes easier and more intuitive. A developer will be able to provide custom blocks that directly render portions of a layout (a three columns grid of features, for instance) and clearly specifies what can be directly edited by the user. That means the user can easily update text, swap images, reduce the number of columns, and more — all without having to ask a developer, or worrying that they will break things. + +### Future Opportunities + +The initial phase of Gutenberg — as described in the the kickoff goal — is primarily limited to the confines of 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 layout Gutenberg will be able to accomplish in the future. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page. For instance, 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 be built using 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. \ No newline at end of file diff --git a/docs/design/block-design.md b/docs/design/block-design.md new file mode 100644 index 000000000000..04ee828a615e --- /dev/null +++ b/docs/design/block-design.md @@ -0,0 +1,83 @@ +# Block Design + +The following is a light guide to designing a new block. It consists of some recommendations, as well as detailed descriptions of existing blocks to help demonstrate good practices. + +## Best Practices + +- Blocks should have a simple icon and label for the Inserter. Ideally, this is a single color icon. Look to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration. +- Blocks should have a good placeholder state when they’re first inserted. If the block includes a text input, provide placeholder text. If it’s meant to hold media, include buttons for uploading or accessing media libraries, as well as drop-zones for drag and drop. In the future, the placeholder state will be used to make page and post templates. +- When unselected, your block should preview its content. +- When selected, your block may surface additional options: 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. +- Additional block options and configuration can also be added to the “Block” tab of the Settings Sidebar, but keep in mind that a user might dismiss the sidebar and never use it. Do not put critical options there. +- Be sure to consider how your block looks, feels, and works on all sorts of devices and screen sizes. + +## Examples + +To help 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” (This 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, drop an image directly on it, or pick an image from the media library. + +**Selected state:** + +- Block Toolbar: Alignments, including wide and full-wide (if the theme supports it). +- Block Toolbar: Edit Image (opens 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 fine 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._ + + diff --git a/docs/design/design-patterns.md b/docs/design/design-patterns.md new file mode 100644 index 000000000000..253081917953 --- /dev/null +++ b/docs/design/design-patterns.md @@ -0,0 +1,65 @@ +# Design Patterns + +## Basic Editor Interface + +Gutenberg’s general layout relies on a bar at the top, with content below. + +![Editor Interface](https://cldup.com/VWA_jMcIRw-3000x3000.png) + +The **Toolbar** holds document level actions: Editor mode, save status, global actions for undo/redo/insert, the settings toggle, and publish options. + +The **Content Area** holds the document itself. + +The **Settings Sidebar** holds additional settings for the document itself (tags, categories, schedule etc.), and also for blocks in the “Block” tab. A cog button in the toolbar can be used to hide the Settings Sidebar, creating 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, block-specific features can be surfaced contextually. This is inspired by the 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 holds basic actions. Gutenberg aims to ensure good, common defaults, so users should be able to get all their creating done without ever having to use the advanced actions in the Settings Sidebar. + +Commonly used actions are highlighted in the **Block Toolbar**. The **Block Chip** lives in the block toolbar, and contains high level block 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 for 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 options are available on the right: **Advanced Settings** like “Edit as HTML” and “Convert to Shared Block,” and the ability to delete the block. + +An unselected block does not show the block toolbar or any other contextual controls. In effect, an unselected block is essentially a preview of the content itself: + +![Unselected Block](https://cldup.com/DH9HZnEgwH-3000x3000.png) + +Please note that selection and focus can be different. For example, an image block can be selected but the focus can be on the caption field, exposing extra (caption-specific) UI. + +## 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 consists of sets of editable fields (**Sidebar Sections**) that can be toggled 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. So pick good defaults, and make important actions available in the block toolbar. + +Examples of 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 via the toolbar, or contextually within the content area. Inside, blocks are organized into sections that can be expanded or collapsed. 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. diff --git a/docs/design/design-resources.md b/docs/design/design-resources.md new file mode 100644 index 000000000000..eecfabb7df71 --- /dev/null +++ b/docs/design/design-resources.md @@ -0,0 +1,11 @@ +# Design Resources + +The [SketchPress](https://github.com/10up/SketchPress) project includes a library of Gutenberg design components, and is incredibly 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 meant as 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 Gutenberg itself, as development sometimes moves faster than updating of the Sketch files. + +If you have questions, please don’t hesitate to ask in the #design channel on the WordPress community Slack. \ No newline at end of file From e06c897179b6ae10069c5df5c4eaad67b28946fc Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Wed, 8 Aug 2018 13:12:36 -0400 Subject: [PATCH 02/13] Removing old Design doc from the Reference section. --- docs/reference.md | 1 - docs/reference/design-principles.md | 223 ---------------------------- 2 files changed, 224 deletions(-) delete mode 100644 docs/reference/design-principles.md diff --git a/docs/reference.md b/docs/reference.md index 043155e9f651..09d86c381fc1 100644 --- a/docs/reference.md +++ b/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) diff --git a/docs/reference/design-principles.md b/docs/reference/design-principles.md deleted file mode 100644 index 2622c0784f05..000000000000 --- a/docs/reference/design-principles.md +++ /dev/null @@ -1,223 +0,0 @@ -# Gutenberg Design Principles & Vision - -This living document serves to describe some of the design principles and patterns that have served in designing the editor interface. The purpose is to explain the background for the design, to help inform future improvements. - -![Block](https://cldup.com/7HCnN5cFc0.png) - -This document will also go over how a _good block_ should be designed. - -## Goal of Gutenberg - -The all-encompassing goal of Gutenberg is to create a post and page building experience that makes it easy to create _rich post 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 it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery. - -We can extract from this the following: - -- Authoring rich posts is a key strength of WordPress. -- The block concept aims to unify multiple different interfaces under a single umbrella. You shouldn't have to write shortcodes, custom HTML or paste URLs to embed. You should only have to learn how the block works, and then know how to do everything. -- "Mystery meat" refers to hidden features in software, that you have to discover. WordPress already supports a large amount of blocks and 30+ embeds, so let's increase their visibility so people don't install plugins thinking it isn't already there. - -## Why - -One thing that sets WordPress apart from other systems is that it allows you to create as rich a post layout as you can imagine -- but only if you know HTML & CSS and build your own custom theme. By thinking of the editor as a tool to let you write rich posts, and in a few clicks create beautiful layouts, hopefully, we can make people start to love WordPress and what it can do for your content, as opposed to pick it because it installed with one click. - -## Vision - -**Everything is a block**. Text, images, galleries, widgets, shortcodes, and even chunks of custom HTML, no matter if it's added by plugins or otherwise. You should only have to learn to master a single interface: the block interface, and then you know how to do everything. - -**All blocks are created equal**. They all live in the same inserter interface. We use recency, search, tabs, and grouping, to ensure the blocks you use the most are easily within reach. - -**Drag and drop is additive**. Only when explicit actions (click or tab & space) exist, can we add drag and drop as an additive enhancement on top of it. - -**Placeholders are key**. If your block can have a neutral placeholder state, it should. An image placeholder block shows a button to open the media library, a text placeholder block shows a writing prompt. By embracing placeholders we can predefine editable layouts, so all you have to do is _fill in the blanks_. - -**Direct manipulation**. The block technology we are building optimizes for the user experience of manipulating content directly on the page. Plugin and theme authors will have the ability of composing together the different tools core will provide to create their own tailored and specific blocks that give users a WYSIWYG environment for creating on the web. - -**Customization**. What previously required using complicated markup and shielding users from breaking it—through shortcodes, meta-fields, etc. becomes easier and more intuitive. With blocks a developer would be able to provide a theme-specific block that directly renders a portion of a layout (a three columns grid of features, for instance) and clearly specifies what can be directly edited by the user. That means the user gets a WYSIWYG experience where they can't ruin the markup established but can easily update text, swap images, reduce the number of columns, etc, without having to ask the developer for it and without fearing that they will break things. - -Ultimately, the vision for Gutenberg is to make it much easier to author rich content. Through ensuring good defaults, wrapping and bundling advanced layout options blocks, and making the most important actions immediately available, authoring content with WordPress should be accessible to anyone. - -## Interface Blueprints - -Basic editor interface: - -![Basic Interface](https://cldup.com/NDhf6ofFmq.png) - -Block interface: - -![Block Selected](https://cldup.com/GlUdQnu0TR.png) - -Gutenberg has a basic separation between a bar at the top, and content below. - -The **editor bar** holds _document level_ actions. Like editor mode, save status indicator, global actions for undo/redo/insert, the settings toggle, and finally publish options. - -The **content area** holds the document itself. - -The **settings sidebar** holds document metadata. Both for the document itself (tags, categories, schedule etc.), but also for blocks in the "Block" tab. - -On mobile, the sidebar is hidden until you click the cog button to open it. On a desktop you can dismiss it for an immersive writing experience. - -## The Block Interface - -The block itself is the most basic unit of the editor. Everything is a block, and you build them together mimicking the vertical flow of the underlying HTML markup. By surfacing each section of the document as a block we can manipulate, we can attach features that are unique to each block, contextually. Inspired by desktop layout apps, it's a way to add a breadth of advanced features without weighing down the UI. - -The block interface holds _basic actions_. Through ensuring good defaults, and only the most common actions, you should be able to get all your blogging done without ever having to use the Settings sidebar. - -The block itself has multiple states: - -- An _unselected block_ is the closest thing to a live preview of the contents itself. -- A _selected block_ shows the "quick toolbar", direct actions that manipulate the block. Extra elements can also be surfaced in the block content itself. For example an image block surfaces a caption field, a quote surfaces a citation field, and dynamic blocks can surface buttons to let you add form fields. - -Note that _selection_ and _focus_ can be different, i.e. an image block can be selected but the focus can be on the caption field, exposing extra (caption-specific) UI. - -As you scroll down a page on long blocks, the quick toolbar unsticks from the block, and sticks to the top of the screen. - -## Editor Settings - -If your block needs advanced configuration, those live in the Settings sidebar. Editor block settings can also be reached directly by clicking the cog icon next to a block. - -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. - -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. So pick good defaults, and make important actions available in the quick toolbar. - -Examples of 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 Design Checklist, Do's and Don'ts, and Examples - -The following is a list of blocks and which options go where. If you're developing a new block, hopefully this can help suggest where to put an option. - -This is the basic recipe for a block: - -- It should have a nice icon and label for the Inserter. Keep it simple. -- When you insert it, it should have a good placeholder state. If it's meant for text input, provide good placeholder text. If it's meant to hold media, have buttons for uploading or accessing media libraries, drop-zones for drag and drop, or anything else. The placeholder state will be used to make page and post templates in the future. -- Your block when unselected should preview its contents. -- Your block when selected can surface additional options, like input fields, or — if necessary for basic operation — buttons to configure the block directly. -- Every block should, at minimum, show a description in the "Block" tab of the Settings sidebar. You can access this for any block by clicking the cog next to the selected block. -- Additional block options and configuration can be added to the "Block" tab, but keep in mind a user might dismiss the sidebar and never use it, so you can't put configuration critical to the block here. - -Here are a couple of block examples, describing which options go where, and why. - -### Text - -The most basic unit of the editor. Text is a simple input field. - -Placeholder: - -- Simple placeholder text that says "New Paragraph". - -Selected state: - -- Quick Toolbar: Has a switcher to perform transformations to headings, etc. -- Quick Toolbar: Has basic text alignments -- Quick Toolbar: Has inline formatting options, bold, italic, strikethrough and link - -Editor block settings: - -- Has description: "This is a simple text only block for inserting a single paragraph of content." -- Has option to enable or disable a drop-cap. Note that the drop-cap is only visible in the blocks unselected (preview) state. - -_Because the drop-cap feature is not critical to the basic operation of the block, it's in the advanced sidebar, thus keeping the Quick Toolbar light-weight._ - -### Image - -Basic image block. - -Placeholder: - -- A generic gray placeholder block with options to upload an image, drop an image directly on it, or pick an image from the media library. The placeholder block can be laid out as if it was an actual image, and this layout persists when a user adds an actual image into it. - -Selected state: - -- Quick Toolbar: Alignments, including wide and full-wide (if the theme supports it). -- Quick Toolbar: Edit Gallery (opens media library) -- Quick Toolbar: Link button -- A caption input field appears with a "Write caption..." placeholder text below the image - -Editor block settings: - -- Has description: "Worth a thousand words." -- 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 you select images directly from the placeholder itself. In general, try to avoid modals._ - -### Latest Posts - -Placeholder: - -- Has no placeholder, as it works fine upon insertion. The default inserted state shows the last 5 posts. - -Selected state: - -- Quick Toolbar: Alignments -- Quick Toolbar: Options for picking list view or grid view - -Editor block settings: - -- Has description: "Shows a list of your site's most recent posts." -- Has options for showing the post date, changing the default number of posts to show, and an option for adding an additional CSS class. - -_Latest Posts is fully functional as soon as you insert it, because it comes with good defaults._ - -### Contact Form - -Placeholder: - -- Has no placeholder, as the default inserted state shows a functional contact form. - -Selected state: - -- Quick Toolbar: Alignments -- Shows "Remove" buttons next to fields that can be removed. -- Shows an "Add field" button, which opens a popout where you can select additional contact field options. - -Editor block settings: - -- Has description: "A basic contact form." -- Has options for making email address mandatory, checked by default. -- Has options for changing the form ID/name, in case you have multiple forms on a page. - -_Note: this block doesn't exist in Gutenberg currently, but the above describes a "best practices" for designing such a block. Being one of the more complex blocks, it's still important that it is fully functional upon insertion, helped along by good defaults._ - -## Future Opportunities - -Gutenberg as part of the kickoff goal is primarily limited to the confines of 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. - -But just like how the verticality of the web itself doesn't prevent more advanced layouts from being possible, similarly there isn't any fixed limit to the kind of layout Gutenberg will be able to accomplish. As such, it's very possible for Gutenberg to grow beyond the confines of post and page _content_, to include the whole page, including everything that surrounds the content. - -One way to think of it is a theme template being just a comma separated list of blocks, like this: - -```{ -{ - 'themename/header', - 'themename/sidebar', - 'core/content' { - 'core/cover-image', - 'themename/author-card', - 'core/text', - }, - 'themename/footer', -} -``` - -Every block nested inside the _content_ block would be _rearrangable_. Every block would be _editable_. Every block would be built using the same API, and both the editor and the theme would load the same `style.css` file directly. In the end you'd see the same in the editor/page builder, as you would looking at the theme/front-end itself. - -*Page Templates*. Since blocks have empty states, it becomes easy to imagine theme templates being a declaration of which blocks compose a given page. These blocks would naturally guide a user to fill the information necessary to achieve what the theme promises it can deliver — it's very common that users struggle to mimic the theme demo that caught their attention. These templates could function similarly to apps like Keynote, where you can choose a specific template when creating a new page and have content blocks already laid out to help you achieve specific looks. - -This concept is speculative, but it's one direction Gutenberg could go in the future. - -## More resources - -If you'd like to contribute, you can download a Sketch file of the Gutenberg mockups. Note that those are still mockups, and not 1:1 accurate. It is also possible that the Sketch files aren't up-to-date with the latest Gutenberg itself, as development sometimes moves faster than our updating of the Sketch files! - -**Download Sketch mockups & patterns files**. - -Be sure to also read the FAQ, and how to build blocks. From f45493d765b0094cefcc709ceec2cc8d4c01b169 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Wed, 8 Aug 2018 14:05:05 -0400 Subject: [PATCH 03/13] Properly closing the code block in the theme example. --- docs/design.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/design.md b/docs/design.md index f136913bb937..1270ff854a26 100644 --- a/docs/design.md +++ b/docs/design.md @@ -55,7 +55,8 @@ That said, there isn’t any fixed limit to the kind of layout Gutenberg will be 'core/text', }, 'theme/footer', -}``` +} +``` Every block nested inside the content block would be _rearrangeable_. Every block would be _editable_. Every block would be built using 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. From d5a08c4571f80e7146f30221d596402a0bb5fed5 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Wed, 8 Aug 2018 14:05:47 -0400 Subject: [PATCH 04/13] Properly opening the code block in the theme example. --- docs/design.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/design.md b/docs/design.md index 1270ff854a26..ab1cd62a57a4 100644 --- a/docs/design.md +++ b/docs/design.md @@ -46,7 +46,8 @@ The initial phase of Gutenberg — as described in the the kickoff goal — is p That said, there isn’t any fixed limit to the kind of layout Gutenberg will be able to accomplish in the future. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page. For instance, one could think of a theme template as a comma separated list of blocks, like this: -```{ +``` +{ 'theme/header', 'theme/sidebar', 'core/content' { From b26743452da26de19c17048a00c5ee727a35e715 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Thu, 9 Aug 2018 08:01:53 -0400 Subject: [PATCH 05/13] Rename pages to prevent the repeated use of "Design" "Design Patterns" > "Patterns" "Design Resources" > "Resources" These all live under the "Design" folder anyway, so I think it's fine to remove that part of the title. --- docs/design/{design-patterns.md => patterns.md} | 2 +- docs/design/{design-resources.md => resources.md} | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/design/{design-patterns.md => patterns.md} (99%) rename docs/design/{design-resources.md => resources.md} (92%) diff --git a/docs/design/design-patterns.md b/docs/design/patterns.md similarity index 99% rename from docs/design/design-patterns.md rename to docs/design/patterns.md index 253081917953..715a220550f1 100644 --- a/docs/design/design-patterns.md +++ b/docs/design/patterns.md @@ -1,4 +1,4 @@ -# Design Patterns +# Patterns ## Basic Editor Interface diff --git a/docs/design/design-resources.md b/docs/design/resources.md similarity index 92% rename from docs/design/design-resources.md rename to docs/design/resources.md index eecfabb7df71..c8e67d900c25 100644 --- a/docs/design/design-resources.md +++ b/docs/design/resources.md @@ -1,4 +1,4 @@ -# Design Resources +# Resources The [SketchPress](https://github.com/10up/SketchPress) project includes a library of Gutenberg design components, and is incredibly helpful for designing and prototyping Gutenberg and Gutenberg blocks: From e2016e4bfff2e047d816f1846c6f125c5f03eeb1 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Thu, 9 Aug 2018 08:05:22 -0400 Subject: [PATCH 06/13] Add new pages/structure to root-manifest.json --- docs/manifest.json | 30 ++++++++++++++++++++++++------ docs/root-manifest.json | 30 ++++++++++++++++++++++++------ 2 files changed, 48 insertions(+), 12 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index 8fad33d7258b..135b78b3be63 100644 --- a/docs/manifest.json +++ b/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": "patterns", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/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": "resources", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/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", diff --git a/docs/root-manifest.json b/docs/root-manifest.json index fe28ba7ea027..fce0ad28b689 100644 --- a/docs/root-manifest.json +++ b/docs/root-manifest.json @@ -83,6 +83,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": "patterns", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/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": "resources", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/design\/resources.md", + "parent": "design" + }, { "title": "Creating Block Types", "slug": "blocks", @@ -137,12 +161,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", From b34cd920a2be2408d91c0d6c58ad734a92981dd2 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Thu, 9 Aug 2018 08:18:20 -0400 Subject: [PATCH 07/13] Update filenames + slugs. Changing "patterns" to "design-patterns", and "resources" to "design-resources" to prevent conflict with other slugs we're already using. --- docs/design/{patterns.md => design-patterns.md} | 0 docs/design/{resources.md => design-resources.md} | 0 docs/manifest.json | 8 ++++---- docs/root-manifest.json | 8 ++++---- 4 files changed, 8 insertions(+), 8 deletions(-) rename docs/design/{patterns.md => design-patterns.md} (100%) rename docs/design/{resources.md => design-resources.md} (100%) diff --git a/docs/design/patterns.md b/docs/design/design-patterns.md similarity index 100% rename from docs/design/patterns.md rename to docs/design/design-patterns.md diff --git a/docs/design/resources.md b/docs/design/design-resources.md similarity index 100% rename from docs/design/resources.md rename to docs/design/design-resources.md diff --git a/docs/manifest.json b/docs/manifest.json index 135b78b3be63..8c193e8fb351 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -85,8 +85,8 @@ }, { "title": "Patterns", - "slug": "patterns", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/patterns.md", + "slug": "design-patterns", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/design-patterns.md", "parent": "design" }, { @@ -97,8 +97,8 @@ }, { "title": "Resources", - "slug": "resources", - "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/resources.md", + "slug": "design-resources", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/design/design-resources.md", "parent": "design" }, { diff --git a/docs/root-manifest.json b/docs/root-manifest.json index fce0ad28b689..eace6358148e 100644 --- a/docs/root-manifest.json +++ b/docs/root-manifest.json @@ -91,8 +91,8 @@ }, { "title": "Patterns", - "slug": "patterns", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/design\/patterns.md", + "slug": "design-patterns", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/design\/design-patterns.md", "parent": "design" }, { @@ -103,8 +103,8 @@ }, { "title": "Resources", - "slug": "resources", - "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/design\/resources.md", + "slug": "design-resources", + "markdown_source": "https:\/\/raw.githubusercontent.com\/WordPress\/gutenberg\/master\/docs\/design\/design-resources.md", "parent": "design" }, { From 0bcee52a52c78102668301307b1685be3f4c7463 Mon Sep 17 00:00:00 2001 From: sarah Date: Thu, 9 Aug 2018 14:34:56 +0100 Subject: [PATCH 08/13] Wee copyedits to main design page. --- docs/design.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/design.md b/docs/design.md index ab1cd62a57a4..df7f80b6eb43 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,6 @@ # Gutenberg Design Principles & Vision -This living document serves to describe some of the design principles and patterns that have served in designing the editor interface. The purpose is to explain the background for the design, to help inform future improvements, and to define how a great block should be designed. +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, to help inform future improvements, and to help people design great blocks. ## Principles @@ -8,41 +8,43 @@ This living document serves to describe some of the design principles and patter ### Goal of Gutenberg -The all-encompassing goal of Gutenberg is to create a post and page building experience that makes it easy to create rich post layouts. +The all-encompassing goal of Gutenberg is to create a post and page building experience that makes it easy to create rich post 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 it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery. +> 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 from this the following: - **Authoring rich posts is a key strength of WordPress.** -- **The block concept aims to unify multiple different interfaces under a single umbrella.** Users shouldn’t have to write shortcodes, custom HTML or paste URLs to embed. Users should only have to learn how the block works, and then know how to do everything. -- **Gutenberg ams to make core features discoverable.** “Mystery meat” refers to hard to find features in software. WordPress supports a large amount of blocks and 30+ embeds, so let’s increase their visibility. +- **The block concept aims to unify multiple different interfaces under a single umbrella.** 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 aims to make core features discoverable.** “Mystery meat” refers to hard-to-find features in software. 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 — but only if they know HTML & CSS and build their own custom theme. By thinking of the editor as a tool to let users write rich posts, and in a few clicks create beautiful layouts, hopefully, we can make people start to love WordPress and what it can do for their content, as opposed to pick it because it installed with one click. +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 & CSS and build a custom theme. + +Instead, we're reframing the editor as a 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 aims to make it much easier to author rich content. This is achieved by 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 is a block.** Text, images, galleries, widgets, shortcodes, and even chunks of custom HTML, no matter if it’s added by plugins or otherwise. Users should only have to learn a single interface: the block interface. +**Everything is a block:** text, images, galleries, widgets, shortcodes, and even chunks of custom HTML, whether added by plugins or otherwise. Users should only have to learn a single interface: the block interface. -**All blocks are created equal.** They all live in the same inserter interface. We use recency, search, tabs, and grouping, to ensure the blocks users use the most are easily within reach. +**All blocks are created equal.** They all live in the same inserter interface. We use recency, search, tabs, and grouping to ensure the blocks people use the most are easily within reach. -**Drag and drop is secondary.** For greater accessibility and platform compatibility, drag and drop is used as an additive enhancement on top of more explicit actions (like click, tab, and and space). +**Drag and drop is secondary.** For greater accessibility and platform compatibility, drag and drop is used as an additive enhancement on top of more 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.** The blocks interface allows users to manipulate content directly on the page. Plugin and theme authors will support and extend this experience by creating their own custom blocks. +**Direct manipulation.** The blocks 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. -**Customization.** What previously required using complicated markup and shielding users from breaking it — through shortcodes, meta-fields, etc. — becomes easier and more intuitive. A developer will be able to provide custom blocks that directly render portions of a layout (a three columns grid of features, for instance) and clearly specifies what can be directly edited by the user. That means the user can easily update text, swap images, reduce the number of columns, and more — all without having to ask a developer, or worrying that they will break things. +**Customization.** What previously required using complicated markup and shielding users from breaking it — through shortcodes, meta-fields, etc. — becomes easier and more intuitive. 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 specifies what can be directly edited by the user. That means the user can easily update text, swap images, reduce the number of columns, and more — all without having to ask a developer, or worrying that they will break things. ### Future Opportunities -The initial phase of Gutenberg — as described in the the kickoff goal — is primarily limited to the confines of 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. +The initial phase of Gutenberg — as described in the kickoff goal — is primarily limited to the confines of 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 layout Gutenberg will be able to accomplish in the future. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page. For instance, one could think of a theme template as a comma separated list of blocks, like this: @@ -59,6 +61,6 @@ That said, there isn’t any fixed limit to the kind of layout Gutenberg will be } ``` -Every block nested inside the content block would be _rearrangeable_. Every block would be _editable_. Every block would be built using 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. +Every block nested inside the content block would be _rearrangeable_. Every block would be _editable_. Every block would be built using 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. \ No newline at end of file +This concept is speculative, but it’s one direction Gutenberg could go in the future. From 418793458e201b533c42a006432fa61e51fddc99 Mon Sep 17 00:00:00 2001 From: sarah Date: Fri, 10 Aug 2018 12:44:41 +0100 Subject: [PATCH 09/13] Minor copyedits to block design page. --- docs/design/block-design.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/design/block-design.md b/docs/design/block-design.md index 04ee828a615e..f6e01044844d 100644 --- a/docs/design/block-design.md +++ b/docs/design/block-design.md @@ -1,14 +1,15 @@ # Block Design -The following is a light guide to designing a new block. It consists of some recommendations, as well as detailed descriptions of existing blocks to help demonstrate good practices. +Want to design a new block? These recommendations and examples should start you off on the right foot. ## Best Practices -- Blocks should have a simple icon and label for the Inserter. Ideally, this is a single color icon. Look to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration. -- Blocks should have a good placeholder state when they’re first inserted. If the block includes a text input, provide placeholder text. If it’s meant to hold media, include buttons for uploading or accessing media libraries, as well as drop-zones for drag and drop. In the future, the placeholder state will be used to make page and post templates. -- When unselected, your block should preview its content. +- 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. Keep in mind that in the future, the placeholder state will be used to make page and post templates. +- 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: 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. +- 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. - Additional block options and configuration can also be added to the “Block” tab of the Settings Sidebar, but keep in mind that a user might dismiss the sidebar and never use it. Do not put critical options there. - Be sure to consider how your block looks, feels, and works on all sorts of devices and screen sizes. @@ -40,11 +41,11 @@ Basic image block. **Placeholder:** -A generic gray placeholder block with options to upload an image, drop an image directly on it, or pick an image from the media library. +A generic gray placeholder block with options to upload an image, drop an image directly on it, or choose an image from the media library. **Selected state:** -- Block Toolbar: Alignments, including wide and full-wide (if the theme supports it). +- Block Toolbar: Alignments, including wide and full-width (if the theme supports it). - Block Toolbar: Edit Image (opens 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: From a533bffbbad937b8d4fd8ecd578a67b57332344b Mon Sep 17 00:00:00 2001 From: sarah Date: Fri, 10 Aug 2018 12:52:07 +0100 Subject: [PATCH 10/13] Copyedit design resources page. --- docs/design/design-resources.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design/design-resources.md b/docs/design/design-resources.md index c8e67d900c25..c031bb1d32d7 100644 --- a/docs/design/design-resources.md +++ b/docs/design/design-resources.md @@ -1,6 +1,6 @@ # Resources -The [SketchPress](https://github.com/10up/SketchPress) project includes a library of Gutenberg design components, and is incredibly helpful for designing and prototyping Gutenberg and Gutenberg blocks: +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) @@ -8,4 +8,4 @@ These components are built to be used in [Sketch](https://www.sketchapp.com) for Please note that these are meant as 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 Gutenberg itself, as development sometimes moves faster than updating of the Sketch files. -If you have questions, please don’t hesitate to ask in the #design channel on the WordPress community Slack. \ No newline at end of file +If you have questions, please don’t hesitate to ask in the #design channel on the WordPress community Slack. From efb6e1bc49c9fa7771fc9e3310188e681a74f3f9 Mon Sep 17 00:00:00 2001 From: sarah Date: Fri, 10 Aug 2018 14:17:31 +0100 Subject: [PATCH 11/13] Tiny copyedit for clarity on the design patterns page. --- docs/design/design-patterns.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/design/design-patterns.md b/docs/design/design-patterns.md index 715a220550f1..80f6d66708af 100644 --- a/docs/design/design-patterns.md +++ b/docs/design/design-patterns.md @@ -24,13 +24,13 @@ A selected block shows a number of contextual actions: The block interface holds basic actions. Gutenberg aims to ensure good, common defaults, so users should be able to get all their creating done without ever having to use the advanced actions in the Settings Sidebar. -Commonly used actions are highlighted in the **Block Toolbar**. The **Block Chip** lives in the block toolbar, and contains high level block 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. +Commonly used actions are highlighted in the **Block Toolbar**. The **Block Chip** lives in the block toolbar, and contains high level block 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 for 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. +The **Block Formatting** options let users adjust block-level settings, and the **Inline Formatting** options allow for 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 options are available on the right: **Advanced Settings** like “Edit as HTML” and “Convert to Shared Block,” and the ability to delete the block. +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 essentially a preview of the content itself: +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) From 9fb90830646d408ea52536ab26afb542653512bb Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Fri, 10 Aug 2018 09:20:49 -0400 Subject: [PATCH 12/13] Copyedits to the Design Principles & Vision page props @michelleweber. --- docs/design.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/design.md b/docs/design.md index df7f80b6eb43..8299cc21f64d 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,6 @@ # 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, to help inform future improvements, and to help people design great blocks. +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 @@ -8,45 +8,45 @@ This is a living document that outlines the design principles and patterns of th ### Goal of Gutenberg -The all-encompassing goal of Gutenberg is to create a post and page building experience that makes it easy to create rich post layouts. +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 from this the following: +We can extract a few key principles from this: - **Authoring rich posts is a key strength of WordPress.** -- **The block concept aims to unify multiple different interfaces under a single umbrella.** 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 aims to make core features discoverable.** “Mystery meat” refers to hard-to-find features in software. WordPress supports a large number of blocks and 30+ embeds. Let’s increase their visibility. +- **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 & CSS and build a custom theme. +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. -Instead, we're reframing the editor as a 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. +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 aims to make it much easier to author rich content. This is achieved by 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. +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 is a block:** text, images, galleries, widgets, shortcodes, and even chunks of custom HTML, whether added by plugins or otherwise. Users should only have to learn a single interface: the block interface. +**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. We use recency, search, tabs, and grouping to ensure the blocks people use the most are easily within reach. +**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 is used as an additive enhancement on top of more explicit actions like click, tab, and space. +**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.** The blocks 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. +**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. -**Customization.** What previously required using complicated markup and shielding users from breaking it — through shortcodes, meta-fields, etc. — becomes easier and more intuitive. 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 specifies what can be directly edited by the user. That means the user can easily update text, swap images, reduce the number of columns, and more — all without having to ask a developer, or worrying that they will break things. +**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 confines of 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. +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 layout Gutenberg will be able to accomplish in the future. It’s very possible for Gutenberg to grow beyond the confines of post and page content, to include the whole page. For instance, one could think of a theme template as a comma separated list of blocks, like this: +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: ``` { @@ -61,6 +61,6 @@ That said, there isn’t any fixed limit to the kind of layout Gutenberg will be } ``` -Every block nested inside the content block would be _rearrangeable_. Every block would be _editable_. Every block would be built using 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. +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. From fee76b626d5e1d4514cdd842b23dae960db608b7 Mon Sep 17 00:00:00 2001 From: Kjell Reigstad Date: Fri, 10 Aug 2018 09:37:18 -0400 Subject: [PATCH 13/13] More copyedits. props @michelleweber --- docs/design/block-design.md | 24 ++++++++++++------------ docs/design/design-patterns.md | 28 ++++++++++++++-------------- docs/design/design-resources.md | 2 +- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/design/block-design.md b/docs/design/block-design.md index f6e01044844d..3036c7e64702 100644 --- a/docs/design/block-design.md +++ b/docs/design/block-design.md @@ -1,21 +1,21 @@ # Block Design -Want to design a new block? These recommendations and examples should start you off on the right foot. +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. Keep in mind that in the future, the placeholder state will be used to make page and post templates. +- 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: input fields or buttons to configure the block directly (if those are necessary for basic operation). +- 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. -- Additional block options and configuration can also be added to the “Block” tab of the Settings Sidebar, but keep in mind that a user might dismiss the sidebar and never use it. Do not put critical options there. -- Be sure to consider how your block looks, feels, and works on all sorts of devices and screen sizes. +- 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 help demonstrate some of these practices, here are a few annotated examples of default Gutenberg blocks: +To demonstrate some of these practices, here are a few annotated examples of default Gutenberg blocks: ### Paragraph @@ -25,7 +25,7 @@ The most basic unit of the editor. The paragraph block is a simple input field. **Placeholder:** -- Simple placeholder text that says “Add text or type / to add content” (This placeholder disappears when the block is selected). +- Simple placeholder text that says “Add text or type / to add content.” The placeholder disappears when the block is selected. **Selected state:** @@ -41,12 +41,12 @@ Basic image block. **Placeholder:** -A generic gray placeholder block with options to upload an image, drop an image directly on it, or choose an image from the media library. +- 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 (opens the Media Library) +- 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: @@ -55,7 +55,7 @@ A generic gray placeholder block with options to upload an image, drop an image **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. +- 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._ @@ -65,7 +65,7 @@ _Future improvements to the Image block could include getting rid of the media m **Placeholder:** -Has no placeholder, as it works fine upon insertion. The default inserted state shows the last 5 posts. +Has no placeholder, as it works immediately upon insertion. The default inserted state shows the last 5 posts. **Selected state:** diff --git a/docs/design/design-patterns.md b/docs/design/design-patterns.md index 80f6d66708af..d6fa0fd30f1e 100644 --- a/docs/design/design-patterns.md +++ b/docs/design/design-patterns.md @@ -2,31 +2,31 @@ ## Basic Editor Interface -Gutenberg’s general layout relies on a bar at the top, with content below. +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** holds document level actions: Editor mode, save status, global actions for undo/redo/insert, the settings toggle, and publish options. +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** holds the document itself. +The **Content Area** contains the document itself. -The **Settings Sidebar** holds additional settings for the document itself (tags, categories, schedule etc.), and also for blocks in the “Block” tab. A cog button in the toolbar can be used to hide the Settings Sidebar, creating a more immersive writing experience. On small screens, the sidebar is hidden by default. +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, block-specific features can be surfaced contextually. This is inspired by the desktop app conventions, and allows for a breadth of advanced features without weighing down the UI. +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 holds basic actions. Gutenberg aims to ensure good, common defaults, so users should be able to get all their creating done without ever having to use the advanced actions in the Settings Sidebar. +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. -Commonly used actions are highlighted in the **Block Toolbar**. The **Block Chip** lives in the block toolbar, and contains high level block 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 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 for 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. +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.” @@ -34,7 +34,7 @@ An unselected block does not show the block toolbar or any other contextual cont ![Unselected Block](https://cldup.com/DH9HZnEgwH-3000x3000.png) -Please note that selection and focus can be different. For example, an image block can be selected but the focus can be on the caption field, exposing extra (caption-specific) UI. +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 @@ -45,13 +45,13 @@ 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 consists of sets of editable fields (**Sidebar Sections**) that can be toggled open or closed. +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. So pick good defaults, and make important actions available in the block toolbar. +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. -Examples of actions that could go in the block tab of the sidebar could be: +Actions that could go in the block tab of the sidebar could be: -- Drop cap for text +- 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 @@ -60,6 +60,6 @@ Examples of actions that could go in the block tab of the sidebar could be: ![Block Library](https://cldup.com/7QoQIoLk-A-3000x3000.png) -The **Block Library** appears when someone inserts a block via the toolbar, or contextually within the content area. Inside, blocks are organized into sections that can be expanded or collapsed. 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**. +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. diff --git a/docs/design/design-resources.md b/docs/design/design-resources.md index c031bb1d32d7..a6abc870dba1 100644 --- a/docs/design/design-resources.md +++ b/docs/design/design-resources.md @@ -6,6 +6,6 @@ The [SketchPress](https://github.com/10up/SketchPress) project includes a librar 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 meant as 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 Gutenberg itself, as development sometimes moves faster than updating of the Sketch files. +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.