Explore block style variations as packages of style attributes

[oandregal]

This stems from #33157 and older threads such as #22208 (comment)

Example: tt1-blocks theme

I've looked at what the TT1-blocks theme needs for styling in CSS. A large part of its styles is block style variations. This is what the theme has to do to set up the block style variations it wants.

Register its own block style variations:

1. In block-styles.php: register its own block style variations.
2. In blocks.css: define the CSS for those block style variations.
3. In functions.php enqueues the CSS for the block styles variatons for the editor (via hooking into after_setup_theme) and for the front-end (via hooking into wp_enqueue_scripts).

Unregister existing block styles variations it doesn't want active:

1. In unregister-block-style.js: unregister the block style variations it doesn't want to be shown.
2. In functions.php: enqueue the above script via enqueue_block_editor_assets so it takes effect.

[oandregal]

Thinking block style variations as packages of style attributes

At the moment, when the user selects a block style variation what ends up happening is that a new class is attached to the block markup:

<my-block class="is-my-style-variation" />

Then, the theme needs to provide the styles for the class. For example:

.wp-block-my-block.is-my-style-variation {
  font-size: 23px;
  line-height: 1.2;
  color: blue;
}

This is what I understand by thinking of style variations as "packages of style attributes": the block markup doesn't get attached the style variation class but the underlying design units:

<my-block class="has-blue-color has-font-size-small" style="line-heght: 1.2"/>

has-blue-color and has-font-size-small would be classes if the style variation uses one of the existing preset values, otherwise, they'd be inline styles.

We'd provide a mechanism via theme.json to change the underlying design units of the style variations, so it becomes easier and they don't have to register/unregister style variations to the same.

Question: what if the style variation includes some style property that we don't support? I presume this needs to be answered on a case-by-case basis: there may be style properties we need to support and add UI controls for them, others we may need to support but don't any UI, and there's always the ability to keep using the existing mechanism (wp.blocks.registerBlockStyle) for more complex use cases.

[oandregal]

How does it look to migrate an existing block style variation to this?

The quote block has the default and large style variations, that generate the corresponding is-default and is-large classes. The default style variation adds no CSS. Let's look at the large style variation.

Existing

block markup:

<blockquote class="is-large" />

CSS:

.wp-block-quote.is-large {
 	margin-bottom: 1em;
	padding: 0 1em;
}

.wp-block-quote.is-large p {
	font-size: 1.5em;
	font-style: italic;
	line-height: 1.6;
}

.wp-block-quote.is-large cite,
.wp-block-quote.is-large footer {
	font-size: 1.125em;
	text-align: right;
}

New

Block markup:

<blockquote class="style-variation-UUID" style="margin-bottom: 1em; padding-top: 0; padding-right: 1em; padding-bottom: 0; padding-left: 1em" />

CSS:

.style-variation-UUID p { /* same as above */ }
.style-variation-UUID cite,
.style-variation-UUID footer { /* same as above */ }

Note: style-variation-UUID follows what we do for layout and duotone (injecting a generated class name that we enqueue from the server).

[oandregal]

How do we define block style variations via theme.json?

Following with the is-large example for the quote block, the target CSS we need to be able to replicate is:

.wp-block-quote.is-large {
 	margin-bottom: 1em;
	padding: 0 1em;
}

.wp-block-quote.is-large p {
	font-size: 1.5em;
	font-style: italic;
	line-height: 1.6;
}

.wp-block-quote.is-large cite,
.wp-block-quote.is-large footer {
	font-size: 1.125em;
	text-align: right;
}

We could have a new styleVariations section within settings that looked like this:

{
"settings.styleVariations": {
	"core/quote": {
		"spacing": {
			"margin": {
				"bottom": "1em"
			},
			"padding": {
				"top": "0",
				"right": "1em",
				"bottom": "0",
				"left": "1em"
			}
		},
		"elements": {
			"p": {
				"typography": {
					"fontSize": "1.5em",
					"fontStyle": "italic",
					"lineHeight": "1.6"
				}
			},
			"cite": {
				"typography": {
					"fontSize": "1.125em"
				}
			},
			"footer": {
				"typography": {
					"fontSize": "1.125em"
				}
			}
		}
	}
}

Note a few things:

• We need to target HTML that is not part of the wrapper. I've used elements.p, elements.cite, elements.footer and these would need to be registered per block if they don't use the general elements (link, h1-h6).
• Additionally, we need to clarify what to do with the text-align CSS property: we don't have UI controls for it and it's not one of the allowed style properties to use via theme.json.

[jorgefilipecosta]

I agree with the proposal by @nosolosw to include block style support as part of theme.json. I think the shape proposed makes sense we would only need to include a translatable name property per block style so the block style picker correctly displays the name of the style.

[aristath]

We could have a new styleVariations section within settings that looked like this:

I don't understand how the proposed schema would support multiple style variations... The current implementation allows users to define as many block-styles as they want, and then users just select one.
So maybe we should define them using something like this? (just nesting the definition 1 level deeper)

"settings.styleVariations": {
	"large": {
		"core/quote": { ... }
	}
}

And if we allow multiple styles to be defined, then why bother generating a UUID instead of using the key that the user provides for their block-style (in the case above, large)?

[jorgefilipecosta]

I agree with what @aristath said I don't think we need UUID's and I think block styles should be consistent with presets so I imagine the following schema:

"styles": {
		...
		"blocks": {
			...
			"core/button": {
			...
			styleVariations: [
				{
					name: "Translatable name Large"
					slug: "large"
					style: {
					  "typography": {
						  "fontSize": "var(--wp--preset--font-size--normal)",
						  "fontWeight": 500
					  }
					}
				}
			],
			}
		}
	}
}

[oandregal]

I've updated the issue description with the steps a theme such as TT1-blocks has to set up the block variations it wants active. It takes a few steps to do so in three different languages (CSS, PHP, JS) through a number of different files.