Create unified UI for block variants

[mrwweb]

Coming out of #773 and relating to other issues like #317, #728, and especially #522. There seems to be a need for a consistent style for choosing between variations on a type of block (e.g. the two types of blockquotes). I can't find a ticket tackling this across all blocks, so I hope this is an appropriate new ticket.

Right now, the convention appears to be numbered styles:

However, that is really similar to how Heading hierarchical levels are communicated and I also don't think that solution can scale.

If there are 6 blockquote styles, remembering which is which will be very challenging. Nielsen Norman Group's recommendation for interface design is to never use an icon without a text label. That's obviously not feasible for a project like this, but I really think block variations are a moment where the recommendation deserves heeding.

Here's a terrible mockup:

Hopefully that at least communicates the idea. In my experience, naming variations like this also increases consistency of formatting across the site—to the great benefit of the user—since styles are somewhat more semantic (think of "Warning" or "Disclaimer" paragraph styles instead of P1, P2, etc.).

We're building a system here to help people communicate, not just format text in a vacuum. I think this change will improve that experience greatly.

[jasmussen]

Thanks for doing this!

I think there's a good idea here. It might need a little fine tuning, but your point is well made.

[mrwweb]

Glad you think so. The mockup is not good, I just hope it can help clarify the intend of the ticket.

[jasmussen]

Inspired by your mockups, @mrwweb, here are some adjustments to the "style picker":

Can also potentially be applied to headings, though that's less certain:

[mrwweb]

This is way better! I like it, and it seems like a good way forward.

I'm glad you included headings though, because I actually think that's the one thing that shouldn't use this feature (possibly the source of the uncertainty you mention).

Heading hierarchy levels are explicitly not styles and so I worry about displaying them in an identical way. I think this has come up quite a few times in previous discussions. Headings are an admittedly special case, but I'd love for that to mean they get unique handling somehow. (see this core ticket for relevant discussion). Possibly something more like the "merged" layout in the OP screenshot would actually make sense?

To give some other ideas of times where I think stylistic (not semantic!) block variants could be used:

• Gallery variations (tiled, circles, etc.)
• Paragraph variations (warning, aside, disclaimer)
• List variations (no bullets, fancy bullets, two columns)
• Image variations (fancy overlay styles, borders)

All of the above are changing the style of a singular semantic element.

[davewhitley]

Will the user know the difference between blockquote variants and heading variants? They both change the style of the element. The user will probably not know about the semantic meaning of headings, so is it important to differentiate heading variants visually in the UI?

[mrwweb]

@drw158 While user's may not be able to articulate the differences, I still think it's important for the editor to lead user's toward good, semantic formatting decisions. Doing so makes content significantly more accessible, future-proof (theme changes), portable (email, feed readers, "readability" mode, copy & paste), consistent, etc. (I expand on these thoughts in "A WordPress Formatting Manifesto".)

One thing I've experimented with in a plugin is displaying headings with hierarchy-implying dashes:

Any way this editor can encourage technically sound decision—even if the user doesn't understand them!—is a win.

---

Final thought: I also think that making it easy to create and use inline (#773) and block variants (like "warning" and "disclaimer" paragraph styles) will further discourage abuse of headings for formatting!

[karmatosed]

I think things have been iterated on here enough to close this, however if I am mistaken please let me know.

[mrwweb]

@mtias @karmatosed @jasmussen @melchoyce The decision was made in #5360 to reopen this ticket. Could one of you do that? Once that happens, I'm happy to try to post a summary of the conversation there unless someone knows of a way to move the relevant comments.

[melchoyce]

Re-opened!

[mrwweb]

As mentioned above, this ticket was reopened in light of a number of folks pushing for this feature on #5360. Here is a brief (as possible) summary and excerpts of key points made on that thread. (The conversation started with this comment comment.)

This comment tries to summarize the conversation so far so it can be continued here.

Summary of Proposal

A means of applying one or more CSS classes to a specific type of block's wrapper element by selecting a user-friendly name for that class(es). Themes or plugins could register the display name and class(es) with a simple API. No markup changes would be involved.

Why This Would Be Useful

• Shows all possible style options rather than requiring documentation of classes to put in Advanced section's CSS Classes textbox
• Provide a way of semantically identifying styles (e.g. Warning) rather than having users apply a bunch of individual styles (e.g. italic, XL font size, red text) [which are likely to be applied inconsistently and won't look good from theme to theme]
• Provide a very easy way to register styles for blocks compared to creating a completely new block
• Reduce the number of blocks that are nearly identical (ex. 1 quote block with 18 styles rather than 18 blocks for quotes)

Examples of Block Style Variants

• Heading block style with a fancy underline called "Section Title"
• Image Block with options to add a sepia filter ("Old Timey") or a border radius ("Rounded Corners")
• Paragraph could be turned into a "Callout Box", "Footnote", or "Intro Text" (see Consider to rename the "Subhead" block  #5790)
• Ordered list block style to use alpha or greek characters
• Unordered list block style that doesn't use visible bullets ("No Bullet List") or displays a list in multiple columns (Multi-Column List)
• Button block with special styles for "Donation Button", "Volunteering Button", or "Secondary Call to Action"

Code Ideas

Two rough ideas for what registering a style might look like from @mrwweb (heavily inspired by the TinyMCE styleselect API in WordPress):

// basic idea
register_gutenberg_block_styles( $block_type string, $options array );
// basic example
register_gutenberg_block_styles( 'paragraph', array(
  array(
    'label' => __( 'Footnote', 'textdomain' ),
    'class' => 'prefix-footnote',
  ),
  array(
    'label' => __( 'Story Lede', 'textdomain' ),
    'class' => '{prefix}-lede',
  ),
);

and from @felixarntz (more like other Gutenberg theme features):

add_theme_support(
    'block-variants',
    array(
        'wp:button' => array(
            'wp-block-button-primary' => __( 'Primary', 'textdomain' ),
            'wp-block-button-link'        => __( 'Link', 'textdomain' ),
        )
    )
);

Both focus on providing a name/CSS class pairing scoped to a block type. @chrisvanpatten suggested adding a way to register a preview image of the style.

Potential Designs

Beyond what's contained in this thread, @melchoyce and @chrisvanpatten did some research on what other systems use for style variations.

@chrisvanpatten suggested this sidebar layout for selecting variations:

@mrwweb made both an inline and sidebar option for selecting variations:

Concerns/Questions

Current concerns about this idea from @karmatosed:

This seems overly complicated and possibly open to conflicting style issues with the same being used for multiple elements (maybe?). I would caution against this interface. Whilst, I totally understand what you are suggesting, I am not totally sure this is user friendly, for example, a long drop down list isn't for example. The concept of 'block variants' could be explored in a plugin and tested outside, that's how we can explore and iterate the interface.

I really think visual representations is the way forward over names/drop-downs and other interfaces.

and @mtias:

One of the problems is that a design principle has been to allow as much as possible to happen in the block directly, with the sidebar being more about sophisticated attributes.

This poses a problem for how we deal with variants. Where should they fall? If they are considered useful user-friendly additions (and I'd tend to agree with this) then we should see how they could be incorporated to the block body/toolbar instead of the sidebar. But a dropdown list with the names in the block toolbar doesn't scale too well and can complicate the UI. (Issues with mobile, not immediately visual, etc.)

---

So there you have it. Discuss!

[karmatosed]

Thanks for re-opening this. I really don't like adding to the sidebar. I think having it right in the toolbar was the right first path.

[mrwweb]

@karmatosed Any reason for disliking the sidebar displacement? I know you've expressed concern about the sidebar getting cluttered, but maybe there's more specific reasoning on this specific issue.

I've put a fair amount of thought into the two placements I proposed. Many Pros for one are Cons for the other and vice-versa.

Inline Toolbar

• Pros
  • Easily accessible
  • Easily findable
• Cons
  • Takes up space in area without a lot of it to spare
  • It seems unlikely to change frequently once set. Does it deserve such prominent placement if it's a "set it and forget it" type feature?

Sidebar (not necessarily where shown)

• Pros
  • Out of the way but fairly discoverable (progressive disclosure argument)
  • Grouped with other settings for changing the visual appearance of an entire block (as opposed to inline settings, admittedly justification is also a block style)
  • Relatedly, presented as primary (better!) alternative to one-off styling
• Cons
  • Could be "clutter" in sidebar?

---

I hadn't quite every articulated the "inline vs. block styles" distinction before (2nd pro of sidebar above), but I find that personally quite compelling.

What do others think?

[chrisvanpatten]

I'm also not convinced that the sidebar is a bad spot for this (there's a fair amount of prior art where these types of tools fit into a sidebar), but I can appreciate the concern about the sidebar getting to cluttered (a somewhat inevitable situation as plugins start targeting the inspector, but I understand wanting to avoid core contributing to the chaos and setting the example).

Is there a path forward where Block Transforms and this Style Selector (or whatever it gets called) are part of the same tool? I had expressed issue on the other ticket that they're fulfilling different purposes — Block Transforms are changing semantics, while Style Selection is purely aesthetic — but I also suspect that to an end user, they might make sense grouped together.

(As a somewhat-related note, is there any centralised documentation on human-interface guidelines, that helps explain what types of controls and options are appropriate on the block or in the inspector? I think having a sense of the design team's overall philosophy regarding these choices would not only be helpful for this particular ticket, but also more broadly for those of us working on developing plugins to integrate with Gutenberg, and also make it easier to standardise some of these choices in existing core blocks.)

[chrisvanpatten]

Is there a path forward where Block Transforms and this Style Selector (or whatever it gets called) are part of the same tool? I had expressed issue on the other ticket that they're fulfilling different purposes — Block Transforms are changing semantics, while Style Selection is purely aesthetic — but I also suspect that to an end user, they might make sense grouped together.

In response to myself, I remembered that @gziolo posted an interesting screenshot of a combined Heading Size and Transformation dropdown over in #6781 (comment)

In this case, the dropdown would obviously change more than just a CSS class (the <h*> tag) but could be an interesting starting point into exploring how these could be combined.

[felixarntz]

Thanks for pushing this forward @mrwweb!

I think the inline toolbar as placement for the variant control makes sense, mainly for the easy access to it. While most of the controls in the toolbar are not for the entire block, but rather for specific block content marked, the block type selector is also part of the toolbar, and I think it is intuitive to have the variant/style selector right beside this.
Given that the style selector needs to change its contents (or even hide when only the default block style is available) based on which block type is used, the user will see a change reflected when they change the block type, which makes sense. As in: "Hey, you've selected a new block type, now pick how that new block type should be styled."

My only argument for the sidebar is that the Advanced CSS class text input, which technically does the same is also part of the sidebar. However, this is a technical background and not a UX one - plus that CSS field is technical and indeed advanced anyway. So I hardly even consider this a pro argument.

[melchoyce]

Quick idea:

[jasmussen]

Great discussion, solid ideas. It seems clear that we all want the same on a high level:

• A way to transform a block into another
• An interface for showing variants of a block
• An interface that scales from mobile to desktop and is fast, easy, intuitive, accessible

The traditional editor interface for transformations, perhaps, is this dropdown:

From a certain point of view, that interface shows both variants and transformations. It's also _two clicks, one to invoke the dropdown, one to choose it. It's also arrow-keyboardable.

Given we are building a block editor, perhaps it's worth looking at the block insertion interface for inspiration. That's the same two clicks — click top left button, click block to insert. Recently we also added a visual cue for what a block looks like — shown both large and small, gray for core block and optionally brand-colored if a 3rd party block. In the past tickets were opened asking for a more clear "block indicator", so it was easy to see which block you were working with — our solution to that, so far, has been the description in the inspector:

It feels like we have an opportunity here, to tie a bunch of things together at once. What if we:

• Used the interface, largely 1:1, from the Block Library
• Embraced the new optionally colored block design as both a block indicator, and a starting point for transformations and variants?

I've been working out the above in a discussion with @karmatosed based on this thread, she has mockups to post too. But here's one approach that embraces the above.

There's the block chip. It doubles as a block type indicator. We'd also want to use this design in the Block Settings description.

Click it, to open this:

• In this case, it's a Heading Block, and the heading sizes count as "variations", so H2 level is pre-selected.
• Below the list of block variants, there are block transformations. If a block doesn't have variants, you'd only see the transformations.
• It's a modal, but it's still two clicks — one to open it, and one to select the transformations. Or you could use the shortcut key to invoke it, and arrow key to your choice and press enter.
• It's a modal because it's the same interface between mobile and desktop, and because it shows a large window with a lot of content, which would make for a big dropdown if it were a dropdown.

I also made another mockup that takes more direct inspiration from the Block Library design:

• In this one, it's still two clicks and is arrow-keyboardable, but the design is based directly on how the block library looks.
• The variations are shown as large blocks, which preview the end result inside. You can imagine a Blockquote showing a small cropped preview of its end result masked inside.

Thoughts?

[karmatosed]

Some interesting takes to this. As @jasmussen mentioned I also have some ideas on this and have been working through some suggestions - it's kind of interesting to see how we've all taken different approaches here.

I have take a little more unifying route by reusing the library format for blocks. This builds on my work in #7227 where I am suggesting we bring the block library into play for transforms and unify the interface a little.

My suggestion would build on from that unification and have them appear right in the library. I feel this avoids bringing in yet another interface and helps unify the experience a little.

There could be an issue with that extra click to get into the accordion so we in this case could break the model and have it use a scrollbar. I would want proof this is an issue though and if it is maybe we have to consider what we do in library.

The benefits of having one place using the same UI here are consistency but also ease of use. The same thing looks like well the same thing. It also should avoid us having to add more toolbar hooks.

Noting I am also calling them styles as to me that's what they are. I also kept the drop down indicator as without it I felt no call to click or interact.

[chrisvanpatten]

Love love love this!

There could be an issue with that extra click to get into the accordion so we in this case could break the model and have it use a scrollbar. I would want proof this is an issue though and if it is maybe we have to consider what we do in library.

Perhaps the accordion could be used but all the panels default to being open, instead of only the first panel? Fundamentally does the same thing, but still allows people to collapse a panel if they want.

[ZebulanStanphill]

@karmatosed That looks great!

I also kept the drop down indicator as without it I felt no call to click or interact.

Back in #6781 I suggested replacing the transform/style-switcher icon with something like this:

(The "H" being the icon of the Heading block in this case, but would in general be the icon of the current block.) I am not sure that this design would work with the recent additions of background styling for block icons, though.

[hedgefield]

Good designs in here! I would definitely try to stick to existing UI for this yeah, so using the block library feels natural. From a consistency viewpoint it's a little strange that the layout changes between the block changer and block inserter to include the styles. I wonder if we could combine these two?

So style variants would be a 'property' of a block, a coat of paint so to speak, but we could present these in the library as full individual blocks, if you follow me. So instead of inserting Quote and choosing to make it red, white or blue, you have the choice to insert Quote, Quote (red), Quote (white), Quote (blue) etc right from the inserter. I feel like that could save a few clicks. The tradeoff would be that there are multiple variations of a single block in the inserter to choose from.

[mrwweb]

@hedgefield

The tradeoff would be that there are multiple variations of a single block in the inserter to choose from.

I think the other tradeoff is that the user has the opportunity to skip over the default styling more easily. At least as a design in my eyes, I value the ability to add variations, but also think they should be used with a purpose and the default should be the most-frequently used block for consistency's sake. Just a thought.

So style variants would be a 'property' of a block, a coat of paint so to speak,

Good metaphor. That's useful :)

[chrisvanpatten]

The tradeoff would be that there are multiple variations of a single block in the inserter to choose from.

I feel like that could get very crowded very fast. As it is, finding a specific block in the inserter can be a bit overwhelming.

[youknowriad]

closed by #7362