Global styles: Offer a way to view a document containing all blocks and styles

[jameskoster]

It's not uncommon to find yourself styling a block in Global Styles without that block being present on the canvas. Consequently you're left unsure as to whether the desired outcome is achieved.

One solution to this could be providing a dedicated document containing all blocks, that users can observe on demand. Here's a crude example:

Such document could be interactive so that clicking a block would take you to the styles panel for that block. Vice versa, navigating to style a block could scroll you to that block on the canvas. In the future you could possibly drill in to one block to view and manage its states and styles.

[dannyreaktiv]

Could be a block pattern or part of the Theme Unit Test, unless you mean it to be something dynamic that loads everything available to the editor.

[annezazu]

Noting that this feels very similar to this prior issue: #32682

[jameskoster]

I think #32682 is more architectural / high level.

unless you mean it to be something dynamic that loads everything available to the editor

That's the sort of thing I had in mind. Blocks added by plugins etc should be included.

[carolinan]

This seems related to the suggestion to add a "style guide": Block pattern directory: Consider adding a Style Guide category
@colorful-tones

[carolinan]

Also related is that the accessibility team is asking for a post with all the blocks -but they need it to be published, available on the front for testing.
Perhaps it could be an actual post that can be published, like the Gutenberg demo ( wp-admin/post-new.php?gutenberg-demo)

[javierarce]

I love this idea! And I know that the image above is a concept but if users can interact with the right sidebar, showcasing the examples on a modal could be weird since, in any other context, modals get closed when clicking outside.

I can see this working more similarly to a focus mode, where the example document is embedded in the canvas.

In any case, this will be super helpful.

[jameskoster]

Absolutely, the focus mode would work much better. It could even trigger automatically when you open the Styles panel and offer a switcher UI in the dark canvas area.

[annezazu]

@javierarce are you still planning to jump in here to share some designs? We're coming up on a few weeks since you commented and I remember seeing that you would be so wanted to check in :)

[mtias]

Approaching it from a demo post perspective makes sense to me, though I'd also consider it being a virtual page using the example definition from blocks.

[fabiankaegy]

I love the idea of this and it would be very useful for thinks like VRT testing and also client demos where they have one "Kitchensynk" that contains everything that is available to them.

I really liked the blockbook exploration @youknowriad did a few years ago. Especially the concept of "Block Stories"

Some block have very different visual appearances depending on the settings provided. And I worry that limiting this to only showing the example of each blocks will not really represent the breath of options users have.

Having a system such as the "Block Stories" in blockbook would allow you as the theme author to define additional configurations on top of the example that should get shown in this design guide page.

[javierarce]

@annezazu I've been a bit busy with other things lately, but I'll take a stab at this. Thanks for the ping.

[ramonjd]

I hacked something together using example content in packages/edit-site/src/components/block-editor/index.js, just to explore possibilities.

2022-11-18.15.55.43.mp4

It temporarily replaces the blocks value in BlockEditorProvider

It assumes there's a better UI control somewhere to "toggle" example preview on. 😄

Code here: #45929

For Global styles there could be a default template using some base blocks, but I was thinking that, for individual blocks, it would be great to be able to fetch the navigation context from GlobalStylesNavigationScreen.

That way, maybe, it would be possible to render an example block on the fly based on the global styles menu position, e.g., /blocks/menu-block-core-audio

There are inline previews planned over in:

• Global Styles: display inline preview on per-block settings #42919

An example/demo page would rather demonstrate how styled blocks behave in the context of a page, so I see usefulness in both approaches.

[javierarce]

Here's a first idea for this functionality:

style.book.mov

• The functionality could be called "style book" (typographers usually call this type of guide Specimen book, but that's a name too obscure to use)
• I'm not sure what's the best placement to invoke this functionality from, but I considered several places including the site header at the top of the screen. The ellipsis menu, like in @ramonjd's prototype, could be a good spot. Ultimately I decided to try the sidebar because this could be an important customization feature.
• In terms of functionality, the video shows how you can pick a block and customize it on the right sidebar or go the other way around: pick a block from the list and highlight it on the canvas.
• The labels next to each block shouldn't be affected by the customization.
• Blocks use the content from their internal examples.
• The tabs on top of the screen follow this categorization.
• I haven't addressed the demo post idea, but I imagine this could be a post users would publish once through a button in the sidebar.

Here's a list of unanswered questions I have:

• Where should we display the blocks added by plugins? Should they appear in a different category or could we place them inside the 6 categories? Should we display them differently?
• Should we allow modifying the content of the block? In that case, what happens if a user wants to reset their changes?

Figma file with the designs and the prototype from the video.

[noisysocks]

I can work on this.

Should we allow modifying the content of the block? In that case, what happens if a user wants to reset their changes?

In my mind the style book would be powered via the existing example content that each block specifies and so modifying the content isn't allowed. Clicking on a block would open up the appropriate panel in Global Styles, not select the block or insert a cursor.

Where should we display the blocks added by plugins? Should they appear in a different category or could we place them inside the 6 categories? Should we display them differently?

The simplest thing to do I think is to completely mirror the block inserter. Whatever categories appear in the block inserter would appear as tabs in the style book. For example if you activate the Jetpack plugin you'd see Earn, Grow and Jetpack tabs.

[carolinan]

Follow up on that, is there a list of blocks that needs examples added?

[jameskoster]

The simplest thing to do I think is to completely mirror the block inserter.

+1.

@javierarce I'm not sure about the switch – with this appearance it kind of looks like a setting. An alternative idea (feel free to disregard) could be to have the document title + Style Book act as tabs when the Styles panel is open:

That way we can avoid the <- Back button which is always a bit awkward, and the Style Book can be toggled regardless of how far you drill into styles.

For the empty space around the Style Book, should we use the same dark grey as focus mode?

[javierarce]

@javierarce I'm not sure about the switch – with this appearance it kind of looks like a setting. An alternative idea (feel free to disregard) could be to have the document title + Style Book act as tabs when the Styles panel is open:

Thanks! That would definitely solve the issue with the back button… my only doubt is how to render the different states when you have an area selected so that it's clear that you can switch between modes:

For the empty space around the Style Book, should we use the same dark grey as focus mode?

I discarded that idea because it would make it difficult to see which tab is selected. We could solve that by integrating the navigation inside the panel as you did in your original design… the only issue would be that if we allow resizing the canvas, it could break the navigation.

[javierarce]

Thanks! That would definitely solve the issue with the back button… my only doubt is how to render the different states when you have an area selected so that it's clear that you can switch between modes:

Maybe instead of tabs it could be a button that launches this special view 🤔

Screen.Recording.2022-11-22.at.12.39.46.mov

[jameskoster]

My thinking was that since the focus shifts to styles, things like block selection and document meta/actions can take a back seat. That's why I removed the chevron. Maybe there are other appearance options to explore 🤔

One other consideration here is mobile, where it's not possible to view the canvas and the styles panel simultaneously. Should it be possible to invoke the Style Book in that context? If not, that may be another argument for placing the button in the top toolbar because it will inherently be hidden on small screens.

[noisysocks]

I think I would miss the Style Book button if it were in the editor toolbar because I'd be looking at the Global Styles panel in order to complete my task of "change the styles".

[jameskoster]

One other option might be to zoom out slightly when you enter Styles, and place the tabs on the empty space. Prettier than this, but you get the idea:

style.book.mp4

Figuring out how we want this to work on mobile will likely be pivoltal in getting the entry-point right.

[noisysocks]

Figuring out how we want this to work on mobile will likely be pivoltal in getting the entry-point right.

That's a good point. On mobile, the Global Styles panel fills the entire screen. If the Story Book button were in the block editor toolbar you wouldn't see it on mobile as it would be beneath the Global Styles panel.

On mobile I imagine the Story Book would be modal. One would make changes, open the story book, close, make more changes, open the story book, close, and so on.

This makes me think that the Story Book button needs to live in a persistent part of the Global Styles panel. Perhaps the toolbar? Maybe we steal the eye 👁️ icon in #42919? Just spitballing 😀

[jameskoster]

On mobile I imagine the Story Book would be modal. One would make changes, open the story book, close, make more changes, open the story book, close, and so on.

It's an option, but that flow sounds a bit convoluted to me. Especially once #42919 lands and a visual preview of the block is already present within the panel itself.

The main benefits of the Style Book seem to be the interactions (clicking a block to go directly to its associated panel), and the ability to see changes in 'real time' as you manipulate the controls – particularly foundational things like typography, colors, and spacing / layout. Neither of these are going to work very well on mobile, so it might be worth considering it a desktop-only feature?

None of this prohibits placing the button in the panel, I suppose we'd just need to hide it on mobile.

[mtias]

We had included it here in the global styles design from a couple years ago:

The top of the panel also seems fine given the ellipsis menu sits there.

[noisysocks]

I'm not quite finished with #45960 yet but it's probably ready enough for some early design feedback. There's a video in the PR description.

[javierarce]

One other option might be to zoom out slightly when you enter Styles, and place the tabs on the empty space. Prettier than this, but you get the idea:

I prefer this solution to the use of the eye icon (which, to me, feels a bit obscure to decipher in this context).

In case we can consider other ways to present this feature, I've tried a variation that keeps the tabs on top and uses a dropdown to select the block categories.

style.book.mov

[noisysocks]

I like the "zoom out when Styles is open" behaviour. It illustrates the strong relationship between Style Book and Styles. Not sure about the dropdown. It looks a little out of place. Could a vertical tab bar on the left similar to the pattern inserter work?

[noisysocks]

I'm just about ready to put final touches on #45960 so need to know what the decision is re. design. Could you confirm what design I should implement as a first iteration? We can always change things later 🙂

[jameskoster]

Thinking a bit more long term, I think the tabs make more sense. When Styles become a discrete feature, the Style Book / Template tabs can be more literal UI elements that update the 'frame':

For more context see #44770