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.

[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

[jasmussen]

Working with @tellthemachines and @matiasbenedetto on #67541, #67546 and #66545, and especially #65619, it's become clear that a few aspects of the initial issue here are now slightly out of date, and can benefit from some clarity. So I worked to add some clarity in this Figma, to outline new categories that work well with Styles in the site view of the site editor. Mockup:

A few changes here, including some small tweaks to make spacings and metrics unified.

Two heading styles: major heading (16px font size) and subheading (13px font size):

Color swatch size has been clarified. On the landing page, they are small, 4 columns, 32px height:

On the Colors drilldown page, they are 2 colummns and bigger (52px, should that be 64? CC: @WordPress/gutenberg-design ):

Speaking of drilldowns, in order for the style book to be contextual to Global Style sections (Typography, Colors, Background, Shadows, Layout, Blocks, and individual blocks), the categories initially outlined here I've revisited. Tentatively, with this suggestion:

Main Styles section: show the Landing category:

Styles → Typography: Show the Typography category:

Styles → Colors: show the Colors category:

Styles → Blocks: Show all remaining Style book categories in one long list, subdivided by headings:

That absorbs categories Site Identity, Design, Posts, Media, Widgets, and any sections plugins add.

Styles → Blocks → Button: Show just the Buton block:

Styles → Blocks → Navigation:

Here are some more contextual examples:

CC: @beafialho @ramonjd @annezazu