Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update block design principles with a new section on how to group controls #29816

Merged
merged 2 commits into from
Mar 12, 2021
Merged

Update block design principles with a new section on how to group controls #29816

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd62f94
Update block design principles with a new section on how to group con…
jasmussen Mar 12, 2021
60bae3c
Address feedback.
jasmussen Mar 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion docs/how-to-guides/designers/block-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ Since the block itself represents what will actually appear on the site, interac

Basic block settings won’t always make sense in the context of the placeholder/content UI. As a secondary option, options that are critical to the functionality of a block can live in the block toolbar. The Block Toolbar is still highly contextual and visible on all screen sizes. One notable constraint with the Block Toolbar is that it is icon-based UI, so any controls that live in the Block Toolbar need to be ones that can effectively be communicated via an icon or icon group.

### Group Block Toolbar controls with related items

The Block Toolbar groups controls in segments, hierarchically. The first segment contains block type controls, such as the block switcher, the drag handle, and the mover control. The second group contains common and specific block tools that affect the entire block, followed by inline formatting, and the "More" menu. Optionally "Meta" or "Other" groups can separate some tools in their own segment.

![A screenshot showing examples of block toolbar segment groupings.](https://make.wordpress.org/design/files/2021/03/docs_block-toolbar-structure.png)

### The Settings Sidebar should only be used for advanced, tertiary controls

The Settings Sidebar is not visible by default on a small / mobile screen, and may also be collapsed in a desktop view. Therefore, it should not be relied on for anything that is necessary for the basic operation of the block. Pick good defaults, make important actions available in the block toolbar, and think of the Settings Sidebar as something that most users should not need to open.
Expand All @@ -27,7 +33,7 @@ Each Settings Sidebar comes with an "Advanced" section by default. This area hou

Setup states, sometimes referred to as "placeholders", can be used to walk users through an initial process before showing the live preview state of the block. The setup process gathers information from the user that is needed to render the block. A block’s setup state is indicated with a grey background to provide clear differentiation for the user. Not all blocks have setup states — for example, the Paragraph block.

![An example of a gallery block’s setup state on a grey background](https://make.wordpress.org/design/files/2018/12/gallery-setup.png)
![An example of an image block’s setup state on a grey background](https://make.wordpress.org/design/files/2021/03/docs__gallery-setup-state.png)

A setup state is **not** necessary if:

Expand All @@ -52,6 +58,12 @@ In most cases, a block’s setup state is only shown once and then further custo

## Do's and Don'ts

### Block Toolbar

Group toolbar controls in logical segments. Don't add a segment for each.

![A screenshot comparing a block toolbar with good vs. bad toolbar segment groupings.](https://make.wordpress.org/design/files/2021/03/docs__block-toolbar-do-dont.png)

### Block Identification

A block should have a straightforward, short name so users can easily find it in the block library. A block named "YouTube" is easy to find and understand. The same block, named "Embedded Video (YouTube)", would be less clear and harder to find in the block library.
Expand Down