Blocks and Theme Styling Overview

[mtias]

This is an overview of theme related considerations for Gutenberg as gathered after several months of testing and feedback.

WordPress Block Styles vs Theme Styles

During the evolution of Gutenberg we have introduced several blocks with somewhat opinionated styles (quote, pullquote, separator, etc). We have seen how some themes really don't want these — they might conflict with their base styles — while other themes really want to build on top of them (particularly new themes). We have opted to disable the opinionated styles for some of the blocks that map to HTML primitives, like blockquote, because almost every theme defines those for themselves and would be tough to accommodate all conflicts. This has meant we have prevented new themes from reusing the styles that appear on the editor for all these elements. We are seeing some vanilla themes that do want these styles and would rather just customize on top of them.

This means we are looking at a split between themes that don't want any visual style (not considering structural ones here, like columns, galleries, etc) coming from core blocks and themes that do want these styles as their base. It seems we should figure out a way to accommodate both needs.

Anatomy of a Block's Style

Currently we define block styles in two stylesheets: "style" and "edit". The main problem is that if we want to supply visual styles to some themes, we cannot split them from structural styles that should come for all themes easily. So I am proposing we look at establishing three separations for block styles:

• style.scss are the shared structural styles.
• edit.scss are the editor specific styles.
• theme.scss are opinionated visual styles.

With these separations we can always include the base styles for all themes, but make theme styles optional. A theme would have to do something like add_theme_support( 'wp_block_styles ' ) to load these if they want to. (Bonus points if through the structure of theme.scss we could find easier ways for a theme to supply their own styles to the editor. Imagine having a blocks folder under your theme where you can add a css/scss file per block which is used to concatenate into the editor, but I digress.) During build, we should include the visual styles in a separate stylesheet.

Previous: #2905

Classes vs Inline Styles

A similar split exists between basic and advanced customization options. We have a couple blocks that have a fair degree of styling possibilities around colors and font sizes. We allow themes to disable custom colors and to register their own already. We are also looking at providing an array of font sizes that would map to classes is-small-text, is-regular-text, is-large-text, etc, so themes can dynamically set these values. The ability to set custom values is still welcomed for various contexts, so it's looking like the best separation is:

• Basic: Classes for the predefined sets (colors and fonts).
• Advanced: Inline for custom values.

For basic we avoid all saved inline styles, and advanced is something that could be disabled by a theme or plugin if necessary.

Colors

Would be registered assigning a name to each color value. The name would be used to construct a .has-color-{name} class as well as show a tooltip for accessibility.

$colors = array(
	'Blue' => '#00B1D4',
	'Violet' => '#934ED4'
);

Applying one of these colors won't generate any inline style. See #5273

Fonts

In the case of fonts, there'll be a set of predefined sizes that would map to classes. The set would be provided as an array of values which would be used to generate the value in the editor, while the only thing saved would be the corresponding class (i.e is-small-text, is-regular-text, is-large-text, is-larger-text).

The UI would be close to this proposal:

See #5269

This issue will be updated with further details as they come by.

[StaggerLeee]

Please don't forget what value it is in GUI, for font-size: em, px, pt, percent.

[bordoni]

It would be incredibly useful for plugins too, having the information if a given theme chose to style the blocks, in one method from WP core.

[karmatosed]

I really like the three separations (style, edit, theme) for style files. This feels like a robust pattern going forward.

On the font UI, lets iterate a little on styling with the reset being the same, but that's a minor issue.

[aristath]

About the font-sizes controls: I've seen a number of tickets here that all use a numeric field (slider etc) for font-size. However that assumes that the user wants to use pixels... and that's just wrong. I haven't used pixels for typography sizes in years, I prefer using em or rem depending on the use-case. Others prefer using % values, WCAG uses pt for its calculations so in some sites it's more convenient to use that unit and so on.
There are many valid scenarios for each CSS unit, px is only good for a subset of those scenarios. We should not restrict our users to using px.

[mtias]

The value doesn't currently have a unit on purpose.

[samikeijonen]

Seems like a great approach! Will ask questions later on.

[delucks1]

Hi, I just found your discussion on editor / block styles (typo and color) and wonder, if and when you plan to roll out the function in the plugin. Else is there a possibility for me as a beginner in theme development to try that already?

[kanishkdudeja]

I've been thinking about this and had a few questions:

• theme.scss are opinionated visual styles.

  With these separations we can always include the base styles for all themes, but make theme styles optional. A theme would have to do something like add_theme_support( 'wp_block_styles ' ) to load these if they want to.

  These opinionated visual styles will only apply to the front-end or the editor as well?

• I had a general question about theme-supplied styles for core blocks (supplied by WordPress by default). Regardless of the way we choose for themes to supply styles for core blocks (either a extendBlockType function or a blocks/ subdirectory in the theme folder which contains css files for each block or a filter on the block-specific enqueue), will those theme-supplied styles only augment block styles supplied by WordPress core?

  Or will those theme-supplied styles be the only source of truth (meaning block styles supplied by WordPress will be discarded) ?

[mtias]

These opinionated visual styles will only apply to the front-end or the editor as well?

Both. An example is the quote style, that has a left border and some color choices. This currently don't apply on the front-end equally.

will those theme-supplied styles only augment block styles supplied by WordPress core?

Probably should be generic enough to apply to any block.

Or will those theme-supplied styles be the only source of truth (meaning block styles supplied by WordPress will be discarded) ?

If the theme doesn't opt in into having the default block styles, these won't be loaded. Shouldn't matter what we do with theme-supplied styles in that case.

[mapk]

I like the separation of stylesheets. My only suggestion would be changing the name of edit.scss to editor.scss. The first sounds like a verb while the second is the noun.

A theme would have to do something like add_theme_support( 'wp_block_styles ' ) to load these if they want to.

This makes sense, but my concern is that when G merges into Core, there will be a lot of themes that don't initially inject their styles into the Editor. This will be a big disconnect for users, I think. Is it too difficult to inject the theme styles automatically? I'm sure there's already discussion around this, I'll look for it.

[davidakennedy]

I wanted to drop some thoughts here since I've been thinking about this lately, and testing some themes with Gutenberg in mind...

The separated approach laid out by @mtias seems like a nice balanced way ahead. Theme authors will have the choice as to whether to opt in, or go their own way. That's very WordPress-friendly, in terms of what everyone is used to having. It also lets both the type of themes exist: custom ones, and ones that build on existing Gutenberg structure, styles, etc.

I'd also +1 the font and color approach mentioned. It strikes and good balance and gives authors a lot of flexibility.

[jjchrisdiehl]

I agree that conflict can happen between default styling and plugins/themes that do not quite account for the styling.

For instance, I am using the Gutenberg starter theme (and also tried with Fashion Blog theme by Automattic) and noticed that a custom 'spacer' block by Array Themes has this weird gray styling on the front end:

https://cloudup.com/cnJovnhpegf

It seems like they use hr's to create these spacers, then dynamically adjust the height of the hr. In theory, this works great, but in practice, the default hr gray styling is applied and creates this odd gray bar.

So as @davidakennedy mentioned, allowing a plugin or theme to override these default stylings could be preferable to avoid these conflicts.

[BinaryMoon]

I’m really pleased that this is being looked at. Thanks to @karmatosed for pointing the ticket out to me.

I think that splitting the styles into more files is a good approach that would alleviate a lot of my concerns with the defaults overriding already existing styles.

Thinking further - is there was a way for the proposed theme.css to work in both editor AND the on the front end? If this were possible then perhaps the theme.css could be filtered within the theme (or as a property in add_theme_support), which would provide a simple way for themes to add their custom styles to the editor.

I appreciate that there would probably be specificity issues here so don’t know if it would be possible to do with a single stylesheet. Otherwise using SASS a second stylesheet could be made quite easily that achieves the same thing.

Regarding the fonts - I really like this as well. It’d be great for themes to be able to select font sizes that fit their modular scale. I love a bit of consistency.

I would suggest removing the number and slider. In the demo the number shows 24 - which means 24 pixels. It was mentioned that the numbers are unitless but if you made something 24 rems it would be obscenely large. This could potentially cause issues when switching between themes that use different units.

Again, regarding the numbers, users may learn to use a specific number scale (24, 36, 48 for example) with their current theme, and then get confused when they switch to a theme that uses percentages/ rems where the scales are wildly different. If we hide the numbers and stick to the buttons then it will be a simple interface that is more easily transferable between themes.

Regarding sizes, I would suggest having a fixed number of sizes. I don’t know what the plan is here, but if you allowed themers to define the number of sizes (eg one theme may define s, m, and l, and another may define x, s, m , l, xl ) then we will have the same issues with theme transferability.

As an aside - is there a way to just subscribe to theme related tickets here?

[felixarntz]

@karmatosed

This seems overly complicated and possibly open to conflicting style issues with the same being used for multiple elements (maybe?).

I don't think that is technically overly complicated as it's de-facto exactly the same what the existing "CSS Class" text input field does.

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

I do agree with this concern - dropdowns are certainly more user-friendly than an input field for a CSS class, but what you're outlining would still be a lot better. Investigating an approach for block variants in a plugin first appears like a good solution to me.

[melchoyce]

I'm having some trouble visualizing this approach — @mrwweb @felixarntz could either of you sketch out what you're thinking?

[chrisvanpatten]

A little late to the issue but I agree with a lot of the above commentary. Block transforms feel appropriate for semantic changes, not simple visual changes. The transform API also requires you to know exactly which blocks a block can be transformed into, which is putting a huge burden on plugin developers to test and develop interop with other plugins for something that might just be a simple visual tweak.

I also haven't fully tested it, but I imagine there will be additional issues if I have Third Party Quote Block Plugin used on a few posts, but then delete the plugin — does Gutenberg still know how to transform the instances of the Third Party Quote Block in my post_content? Or do I get an error message? Or is it transformed to a generic paragraph or classic block? None of those experiences are really ideal.

(And none of this is factoring in block overload… what happens when third party plugins and themes start supporting Gutenberg en masse? Block discoverability is going to be a major issue as more blocks become available, and asking users to keep track of all the variants of a block type in the inserter is just a nightmare.)

The sidebar may not be the best place for this, but here's one idea:

Themes could register their own "block designs", which consists of a name, a CSS class, and a preview image.

[karmatosed]

@chrisvanpatten thanks for that visual, this really plays to my bigger concern of that being in the sidebar. If you think of scale that easily breaks. What other options are there? Are there any applications doing something like this right now we can learn from?

[chrisvanpatten]

@karmatosed I'm not sure where else to put it, but I'm certainly open to ideas.

[chrisvanpatten]

(To elaborate, I think there will be an issue of scale anywhere it goes — and that's applicable to any point in the UI where plugins can add additional options. I'm not sure if putting it behind a toolbar button is better or worse but I'm certainly open to experimenting with that!)

[chrisvanpatten]

Here's an interesting example from Squarespace, on how you can select alternate layouts for their Instagram block.

For them, they place the options behind a separate Design tab.

Another interesting take, in Excel of all places… alternate table designs in a dropdown:

[melchoyce]

Thanks @chrisvanpatten, that visualization helps.

Some more examples from other sources:

Slideshow block in Weebly

Layout blocks in Weebly

Section Designs in Wix ADI

More design settings in Squarespace

[chrisvanpatten]

Here's another take, from Pages:

[mrwweb]

As promised, here's a couple concepts. I think I like this first one best, placing the drop down with the block definition in the sidebar. It's kind of subtle and prominent at the same time:

No Style Selected

Select an option

Class added

I also think this is a great example of how powerful something like this can be! It applies 4 styles (background, padding, border, box-shadow) that would be hard to apply any other way but also way overkill for creating unique blocks for. Any interface that allowed setting padding and creating box shadows wouldn't be easy to replicate like this and would be both tedious to use and likely to be used inconsistently from page to page.

Another option would be to put the variant selection menu in the inline toolbar:

[mtias]

I think the ideas being presented here (specifically offering/ selecting block variants) are really nice and will be very helpful however I would be interested in looking back at the original ticket and finding out if that is something that's going to happen?

@BinaryMoon yes, the original intention of the issue is unrelated to variants and is being worked on — initial implementation should land for 3.0. @mrwweb let's reopen #783 for this conversation, as it's getting a bit away from the purpose of the current issue, and make out a plan before deciding if we can make it into 5.0 or not.

but the concept of a variant as I envision it would just be a more user-friendly way of the current "Additional CSS Class" field (not as a replacement of course, just as user-friendly alternative that essentially does something similar)

To be clear, I totally agree with this, and I think it's something we should pursue. :) I'm not entirely sure how we would present it — perhaps starting by having the dropdown within the "Advanced" panel is a safe start. 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.)

Also, even if technically this is trivial to do, we should look at how we could facilitate the usage of it longer term, because I think it's a good feature to have.

@chrisvanpatten I totally agree on the semantic distinction being relevant here. I'd actually use that to make the case that "subheading" should be a separate block, because it's not a purely visual change, it has semantic value to the user.

[samikeijonen]

Quick note about theme.css. It would make sense that themers could dequeue or opt out theme.css also from the editor.

I tried it with wp_dequeue_style( 'wp-core-blocks-theme' ); with hooks enqueue_block_editor_assets and enqueue_block_assets but no luck. Could be something to do with depencies.

[mtias]

@brandonpayton when you have a moment could you look at the above? Thanks!

[BinaryMoon]

I agree with @samikeijonen - I want to include my styles in the editor but I'm having a hard time overriding the default ones.

[brandonpayton]

I tried it with wp_dequeue_style( 'wp-core-blocks-theme' ); with hooks enqueue_block_editor_assets and enqueue_block_assets but no luck. Could be something to do with depencies.

Hi @samikeijonen, you're right that it has to do with dependencies. The 'wp-edit-blocks' styles depend on the 'wp-core-blocks-theme' styles. Because of this, we cannot simply dequeue the theme styles, but we can replace them for 'wp-core-blocks-theme' by using wp_deregister_style and wp_register_style. enqueue_block_editor_assets looks like the right hook to use for this. Does that help?

@mtias do you want us to do anything more to support overriding theme CSS in the editor?

[samikeijonen]

Thanks @brandonpayton! I opened new issue in #7776 just in case. I feel like replacing the original theme.css with empty one is not the best practise.