Style Book: Iterate on presentation and design

[jameskoster]

Brief

The main goal of this refresh is to better organize the blocks that make up your site into a representation of the book of style for your site. Organize into what could have been a design manual. This work includes:

Requirements

• A “Landing” tab that would serve as the landing page of the stylebook: a page displaying only blocks that more commonly and immediately are able to represent the theme.
• Rearrange blocks into each category based on  relevancy that makes the most sense when editing a website.
• Consider adding subcategories that would organize blocks better within each tab. For example the “Theme” tab would contain “Site Identity”, “Posts” and “Comments”.
• Update block examples for a more cohesive connection between them.
• Reorganize blocks into the proposed categories.

Visual

Landing page

The landing page would be useful for the current iteration of the Site View, which does not currently feature tabs. It serves as a quick glanceable "poster view" for the site style guide:

Finally it would serve to have deep-links to the other tabs, e.g. clicking "Headings" would take you to the Text tab:

Reorganizing blocks

To afford this structure, the new categories, Color and Theme would benefit orientation. Here is a suggestion how we could reorganize existing blocks, as well as include all the site-specific blocks in those taxonomies:

Designs in this issue are created by @beafialho. Figma.

[jasmussen]

Thanks to beautiful work by @beafialho, I've updated this issue with designs attached. There's a lot to dive into, you can explore the linked Figma, but for now the main focus has been on updating the book itself, what's inside the frame. Especially on that, please share your thoughts. CC: @WordPress/gutenberg-design

[vcanales]

I've been looking into these designs and I have a few questions and thoughts:

A “Landing” tab that would serve as the landing page of the stylebook. A short page, displaying only blocks that more commonly and immediately are able to represent the theme.

How are we going to define which blocks comprise this list?
Should we build a static page that displays these blocks, or will we use block.json to feature the blocks in the Landing page somehow? Currently, the Style Book renders blocks into each tab according to the category attribute in block.json, and only if they include an example attribute as well.

• Rearranging the order of the blocks by level of relevancy: seek out an order that makes the most sense when editing a website.

How and where are we going to define this hierarchy? Blocks in the styles book are currently rendered in the order in which they are registered, if I'm not mistaken.
I'm thinking that the Landing Page might become outdated if we rely on a static list of blocks ie. if we add future important blocks, we'd also have to update the landing page manually.

• Adding subcategories that would organize blocks better within each tab. For example the “Theme” tab would contain “Site Identity”, “Posts” and “Comments”.

This might be an answer to the first question; we could add a subcategory which the Landing Page compiles blocks from. The keywords attribute is another candidate.

• Updating demo content, mostly images and media maintaining a more cohesive connection between them, but also headings, paragraphs and quotes.

Demo content is mostly the placeholders for each block, currently. I think we could be taking further advantage of the example metadata attribute to create richer previews.

[jasmussen]

Thank you for looking, @vcanales!

How are we going to define which blocks comprise this list?

We'd manually curate this list according to the suggestions in the mockups.

How and where are we going to define this hierarchy? Blocks in the styles book are currently rendered in the order in which they are registered, if I'm not mistaken.

How are we curating these?

Essentially we only need a few of the blocks to be "prioritized" in a particular order, and after those, anything else can show up.

I'm thinking that the Landing Page might become outdated if we rely on a static list of blocks ie. if we add future important blocks, we'd also have to update the landing page manually.

The landing page should specifically have a goal of giving you a sense of the site design. To that end, this can be thought of more like a highly curated and stylized "style card", like this:

It wouldn't need to be updated that often, in part because we don't often add new blocks, in part also because it is intentially a subset. If you want to see all the blocks, you have to dive into the tabs.

Demo content is mostly the placeholders for each block, currently. I think we could be taking further advantage of the example metadata attribute to create richer previews.

This is likely fine to separate out exactly as you suggest, and not make part of this particular task. We definitely need to enrich the demo content across the board, update the current preview images, etc.

[mtias]

@jasmussen @beafialho this is looking wonderful. I agree we should focus an iteration on the contents and landing screen, and then revise navigation and frame, which is in need of a deeper look now that the design of the site editor has continued to evolve.

[ramonjd]

we should focus an iteration on the contents and landing screen

I've started looking at reorganizing the style book categories.

I'm thinking a first pass will be to refactor the way the style book displays categories and blocks, to make it flexible and easy to update, and then refine in follow ups.

Most of the following points are for later, but I'm just jotting down some notes/questions:

Layout category/Landing tag

I gather initially, there'd be a static list of blocks or even a pattern or two to display here.

It's mentioned that these will be blocks that show off the theme style. Down the line, should the theme be able to include their own?

Blocks that contain other blocks / Patterns

Some blocks normally live in other blocks, some are:

• Buttons > Button
• Navigation. > Navigation link
• Query pagination > Next and Previous.
• Comments pagination. Next and previous, and page numbers, etc

Not sure how it would affect navigation yet, but maybe these blocks could be displayed in mini patterns. Examples already exist for some, but others have none. Perhaps there are some custom Core patterns we could create/borrow to highlight blocks that go together, e.g., a comments pattern, to avoid displaying individual blocks just as comments next link.

Custom blocks/categories

What about custom categories and blocks from plugins and themes? We should append the categories to the tab list?

Where there are too many categories for a single row of tabs, off-canvas category tabs could be converted into a drop down, or scroll arrows. This could be dynamic, e.g., checking for element visibility or something.

By the way, what is the Text > Custom link block? 🤔 I can't seem to find it.

[jasmussen]

Buttons > Button
Navigation. > Navigation link

Worth here connecting dots with mockups shown here that expand on what gets shown for navigation items. Notably, it explodes the navigation item into one unit for each state, hover, focus, current, etc.

That's not to necessarily to block this work, just important to keep in mind. There are some mockups that potentially affect this work too, in this Figma.

By the way, what is the Text > Custom link block? 🤔 I can't seem to find it.

@beafialho in case you have a moment. Ramon is referring to this one.

[ramonjd]

Worth here connecting dots with #38277 (comment) that expand on what gets shown for navigation items. Notably, it explodes the navigation item into one unit for each state, hover, focus, current, etc.

Nice! Thanks for cross-linking that work.

I can work with reasonably little detail initially - I think it's a good opportunity to set the style book up for flexibility. By that I mean, create a component that can consume some sort of map or config, which folks can tweak to determine categories/blocks etc. And then concentrate more on the content.

That's the theory anyway 😄

[beafialho]

By the way, what is the Text > Custom link block? 🤔 I can't seem to find it.

@ramonjd I'm currently seeing "Custom Link" under the Design tab:

[vcanales]

@ramonjd By that I mean, create a component that can consume some sort of map or config, which folks can tweak to determine categories/blocks etc. And then concentrate more on the content.

Are you thinking of including this config in the block.json definition? A not-so-flexible approach I thought of was adding a subcategory attribute, but we could also consider further categorization or customization to improve discoverability with a broader config schema. Here's the PR with the subcategory attribute suggestion, by the way.

[vcanales]

@ramonjd By the way, what is the Text > Custom link block? 🤔 I can't seem to find it.

It's the navigation link block, isn't it?

gutenberg/packages/block-library/src/navigation-link/block.json

Line 5 in 7dcb38c

"title": "Custom Link",

[ramonjd]

not-so-flexible approach I thought of was adding a subcategory attribute

@vcanales Thanks for the suggestion.

I had the same thought, but wasn't sure if it warranted updating the block.json schema (and every block.json file) just yet when things could be hard-coded for the first iteration.

I hadn't seen your PR yet however, and I think it's a good idea to allow deeper categorization in general, for example, to make things more discoverable and sortable. I haven't looked closely yet, but do you think some of the existing Core filters and other functionality would also need to be aware of sub-categories?

It's the navigation link block, isn't it?

Oh yeah, thanks for pointing that out 🤦🏻

Custom link doesn't really mean much out of context, at least to me.

[vcanales]

(and every block.json file)

We could get away with adding them incrementally; I think a potential subcategory attribute should remain optional.

I haven't looked closely yet, but do you think some of the existing Core filters and other functionality would also need to be aware of sub-categories?

Yes, in my proposal for the schema, subcategories would be children of an existing category, so we'd have to add this awareness.

Custom link doesn't really mean much out of context, at least to me.

Agreed. I don't think the block's title describes it in a way that makes it easy to find.

[ramonjd]

Related:

• Style Book: Add item to represent global Typography and Color settings #57323

Proposed also a "typography" tab.

[andrewserong]

Update: work is underway on this one so I've updated this to "In Progress" from "Needs Dev". A couple of the PRs for this that have landed so far include:

• Style book: create static categories #65430
• Style Book: Add color tab #65692

Here's how the Colors tab is looking on trunk:

2024-10-25.14.15.33.mp4

Also, discussion is happening over in #66376 on where the Styles screen (and therefore Style Book) will live in the future.

[ramonjd]

I attached a sub issue for the landing page:

• Style book: creating landing page view #66517

However given the following:

• Site editor: integrate global styles controls and style book preview into the styles panel  #65619 in the works
• Dedicated Styles Screen #66376

I don't really understand the case for implementing it yet.

My current impression is that we won't know until the dedicated style screen is defined. There are several open questions, namely:

• what's on the landing page
• how should users interact with it, particularly if it's integrated into a global styles view
• how theme developers can customize it