Add: Global styles css variables generation mechanism

[jorgefilipecosta]

Description

Part of: #19611
This PR adds the mechanism that with the default WordPress global styles and a theme.json file generates a set of CSS variables representing these global styles.
Basically, we implement the Resolver concept referred in #19611.

As a follow, we will also retrieve user overwrites for the global styles from the database that will take priority over theme and defaults.

Blocks should consume these global variables as part of their styles by using CSS variables. As a sample, I converted the button in a back-compatible way.

This PR also adds wp-gs to the body of the frontend and the editor if the theme supports global styles (defines a theme.json file).

How has this been tested?

Create a file named experimental-theme.json in the root directory of the currently enabled theme.
Add the following contents to the file:

{
	"global": {
		"color": {
			"primary": "green",
			"background": "red",
			"text": "red"
		}
	},
	"blocks": {
		"core/paragraph": {
			"color": {
				"text": "hotpink"
			}
		},
		"core/button": {
			"color": {
				"background": "pink"
			}
		}
	}
}

Add a button block verify the background by default is pink on the editor and frontend. Verify that when the user selects a color for the button, it is applied.

Delete "core/button" section from theme.json
Reload the post and verify that the button is now green (primary color on the theme.json file).
Delete the primary color from theme.json and verify the button color is now #52accc (default primary color).

[ItsJonQ]

🚀 @jorgefilipecosta This works beautifully! I just tested this locally on Twenty Eleven. The loading of the local theme.json + wp-gs environment bootstrapping works as expected.

The theme.json overrides apply on the instance for multiples views (e.g. homepage, single post page, etc...).

Lastly, setting a local block override works as expected. In this case, it's because you've applied the style if there is no background set (identified by a className). I suspect we'll need to be more.. systemtic about this approach, as I anticipate a lot of variation between blocks. But that's a note for the future.

Spectacular job!! 🙌

[aristath]

A filter here would come in really handy...
I'd like to work on this issue: #19611 (comment) but without a filter it's just going to get messy 😉

[jorgefilipecosta]

We are still in early stages, but I agree filters here make sense. I will propose an experimental filter 👍

[youknowriad]

Shouldn't we hold on adding filters until we're sure about the APIs...

[mtias]

It'd be good to start making a list of which functions (in the non-code sense) make sense to extend.

[youknowriad]

Is $dark-gray-700 the current default background color for this block? Won't this cause a change in existing themes?

[jorgefilipecosta]

Yes, the default is already $dark-gray-700.
https://github.com/WordPress/gutenberg//blob/79d28866952ec3976eafad41d90458aa9d266455/packages/block-library/src/button/style.scss#L17

It will not cause any change in existing themes because they don't use global styles so the class wp-gs is not present.

[youknowriad]

I think we should probably drop $dark-gray-700 from here

[jorgefilipecosta]

Hi @youknowriad, what is the reason for removing $dark-gray-700 from here? It is a fact that the default background color will be $dark-gray-700 because of existing rule even if we don't include $dark-gray-700. But I think setting defaults in this way may open the door to allow tools to easily parse the fallbacks on a given variable and allow the user to easily see the defaults.

[youknowriad]

Today the block doesn't have any default and I feel that's fine. This is changing the behavior of the block for me.

The question is do we want block authors to provide these defaults like or should we just rely on the theme styles? I feel we always choose the theme styles in general.

For example in dark theme, it doesn't make sense to force a dark color on paragraph text color.

[youknowriad]

Can you explain to me why the .wp-gs is necessary? Why can't we just drop it?

[jorgefilipecosta]

If I added the rule .wp-block-button__link:not(.has-background) to the block most existing themes would break. That happens because that selector has a specificity of two classes, so a theme setting the background color using .wp-block-button__link{ background-color: ...} would stop working.

Another case where this problem is even more noticeable is the implementation of global styles in a paragraph. We can not simply set p { background-color: var(--wp-gs-paragraph-color-text, var( --wp-gs-color-text ) ) otherwise paragrapgs would probably change colors in most existing themes.

The wp-gs class offers a block the possibility of keeping existing styles so existing themes styling them still work while at the same time they could provide styles that are used in the presence of a theme compatible with global styles.

The CSS variables with the defaults or user-configured options will be always be loaded even if the theme does not support global styles. So a new block build now may not need to use wp-gs and can just use the global styles all the time.

[youknowriad]

Can these problems be solved if we avoid an explicit value at the last argument. Concretely, if it's something like that

background-color: var(--wp-core-button-color-background, var(--wp-color-primary, initial));

(initial or inherit depending on the property we're setting)

[jorgefilipecosta]

No, this code would not work because --wp-color-primary would always be defined as it is a default that WordPress needs to provide even if themes don't use global styles. If defaults were not provided blocks could never safely rely on a global variable.

[youknowriad]

--wp-color-primary would always be defined as it is a default that WordPress needs

Making sure I'm understanding properly here. Why WordPress need to define defaults for these variables?

[jorgefilipecosta]

I think it would be good to provide a set of defaults to make things consistent even if the theme is not setting global styles.
So, for example, block A and block B created by different authors both use the --wp-gs-color-text, if a default for the variable is not provided both blocks may end up using different text colors while ideally, the text color would be the same.

[youknowriad]

Why not just consider the browser defaults as the defaults? There's something I'm missing here.

If these blocks do support the variables they will have something like that on their styles right?

color: var(--wp-block-something-color-primary, var(--wp-color-primary, initial));

[jorgefilipecosta]

If we set something like p:not(.has-background) { color: var(--wp-block-something-color-primary, var(--wp-color-primary, initial)); } without targetting current themes supporting global styles (having wp-gs class) we make break the styles for example if the current theme has p { color: red } the style will stop working as color will take the default browser value.

[youknowriad]

What happens if we just remove "initial" from that code?

[jorgefilipecosta]

What happens if we just remove "initial" from that code?

In my tests, I think the browser uses the default value for the property when the var is used (it seems the same as including initial).

So I think we can not avoid wp-gs otherwise we may break styles.

[youknowriad]

This is a great start, any thoughts about how to best document this? The CSS variables from block authors, the overall flow...

[jorgefilipecosta]

This is a great start, any thoughts about how to best document this? The CSS variables from block authors, the overall flow...

Hi @youknowriad, regarding the documentation of the overall flow @ItsJonQ is working on that and shared details on #19611 (comment).
Regarding how block authors will expose the customization options they offer, previously, I thought blocks should have their own theme.json where they would define all the styles they support and their default value or the fallback to another variable. I discarded doing that and relying on CSS only from the block authors because doing that would require that we open and parse the theme.json of every block to generate the CSS variables. If the user has 40 blocks opening 40 files on every page load will probably have a huge impact.

So ideally, block authors would provide a theme.md or styles.MD file where they document the variables they support so theme authors can read them.
The variables follow a precise naming format, so I can imagine an awesome WordPress plugin for theme authors that iterates on the loaded stylesheets loaded on the editor parses the CSS variables and assigns variables to block from its name, then for each block shows the styles options the block offers and the context where the option is used (background-color, padding, width etc...) so the developer knows the variable type. Basically from this `background-color: var(--wp-gs-core-button-color-background, var(--wp-gs-color-primary, $dark-gray-700)); we should make sure it is possible to build this { block: 'core/button',
styleName: 'color-background', useIn: 'background-color' } so a plugin for theme developers can add pretty UI on top that practically auto documents every block.

[youknowriad]

So ideally, block authors would provide a theme.md or styles.MD file where they document the variables they support so theme authors can read them.

I'm a little bit concerned about this. I think personally that ideally, the number of these variables should be small and should be consistent across all blocks. That way they can be also supported by third-party blocks. If we allow blocks to define their own custom variables (and these variables not being generated from the default variables), the proposal loses part of its purpose since the theme can not style all blocks (core or third-party) in an agnostic way.

[jorgefilipecosta]

I'm a little bit concerned about this. I think personally that ideally, the number of these variables should be small and should be consistent across all blocks. That way they can be also supported by third-party blocks. If we allow blocks to define their own custom variables (and these variables not being generated from the default variables), the proposal loses part of its purpose since the theme can not style all blocks (core or third-party) in an agnostic way.

Hi @youknowriad, the main objective is that we have a set of global styles and blocks use these styles in their implementations.
We will need to make sure that the global styles we provide cover most of the needs for style definitions blocks may have.
Ideally, changing these global styles changes "all blocks". We thought there are cases where a theme may need to change something in a specific block, so it would be good for blocks to be able to define their own variables. For example, both heading and paragraph may use a global text color. But it would be good if the heading provides its own variable in case a theme wants to change the heading color without affecting the rest of the text.

[youknowriad]

We thought there are cases where a theme may need to change something in a specific block

Agreed, but for me, this doesn't mean that we need to document anything specific for the block. It simply means that we have a naming convention for the block specific variable.

If the option is Global style option is "color-text"

the theme could define something like:

{
	"global": {
		"color": {
			"text": "green",
		}
	},
	"blocks": {
		"core/paragraph": {
			"color": {
				"text": "hotpink"
			}
		},
	}
}

This would generate two variables:

--wp-color-text: green;
--wp-block-core-paragraph-color-text: hotpink

This means we only have to document:

• the global option (color-text) to use in theme.json
• and block authors should only know the naming convention to generate the global and the specific CSS variable. They shouldn't "define" their own variables.

[jorgefilipecosta]

Agreed, but for me, this doesn't mean that we need to document anything specific for the block. It simply means that we have a naming convention for the block specific variable.

But what if the block has a very specific variable and wants to allow themes to change it? E.g: A "WordArt" like block that wants to allow themes to change space between letters and the orientation of the text?

I think there will be always cases where a block was some specific need that will not be covered and if we don't provide a way for blocks to create variable specific to them, themes will end up customizing them by overwriting the CSS instead of relying on previously defined variables.

[jorgefilipecosta]

Agreed, but for me, this doesn't mean that we need to document anything specific for the block. It simply means that we have a naming convention for the block specific variable.

But what if the block has a particular variable and wants to allow themes to change it? E.g.: A "WordArt" like block that wants to allow themes to change space between letters and the orientation of the text?

I think there will always be cases where a block was some specific need that will not be covered, and if we don't provide a way for blocks to create variable specific to them, themes will end up customizing them by overwriting the CSS instead of relying on previously defined variables.

[youknowriad]

I think there will be always cases where a block was some specific need that will not be covered and if we don't provide a way for blocks to create variable specific to them, themes will end up customizing them by overwriting the CSS instead of relying on previously defined variables.

Maybe but overriding a specific CSS variable or overriding a specific style is not that different and is not the main benefit from the global styles work. this proposal shines when it serves as a shared design system. I think this should be considered later and we should focus on the shared design system first. Also for these particular cases, ideally, the block author derives that style from the global variables (transformations, plugins like were shared initially in the prototypes)

[jorgefilipecosta]

I think there will be always cases where a block was some specific need that will not be covered and if we don't provide a way for blocks to create variable specific to them, themes will end up customizing them by overwriting the CSS instead of relying on previously defined variables.

Maybe but overriding a specific CSS variable or overriding a specific style is not that different and is not the main benefit from the global styles work. this proposal shines when it serves as a shared design system. I think this should be considered later and we should focus on the shared design system first. Also for these particular cases, ideally, the block author derives that style from the global variables (transformations, plugins like were shared initially in the prototypes)

Sure I understand the reason behind this. I think for now we can assume blocks don't define their own variables.

In that case, I asked my self if it even makes sense to have variables named --wp-gs-paragraph-color-text, if we wanted to change the color of a paragraph using global styles we could simply do p { --wp-gs-color-text: green; }. But I think using variables like --wp-gs-paragraph-color-text still makes sense the reason being that we don't which selector to use to select the block (in this case is "p" but it could be another thing) blocks would need to configure their selector. It would mean during styles generation on every page load; we would need to load their configuration files. Also, for cases where, for example, we want to change global styles inside a specific group e.g., change headings color inside a group but not the text color, the generated styles would be complex.

So I guess for blocks documentation, a block can specify which global styles affect that block, and from there, we can know the specific names of variables for that block. Of course, programmatically, a plugin could also identify which global styles affect the block.

[ItsJonQ]

@youknowriad Thank you for all of your feedback! After that discussion, it sounds like there we need some of WP global styles "environment flag" of some kind. In this case, in the form of a global wp-gs className.

background-color: var(--wp-core-button-color-background, var(--wp-color-primary, initial));

After seeing your example, the --wp- namespace reads better. It's not as unique, but that may be okay given the rest of the variable name.

If we change that though, there may be a slight disconnect between a --wp variable and the .wp-gs .my-block-style styles (for it's current implementation).

I think that may be okay to start.

@jorgefilipecosta Would love your thoughts! I'm okay either way, as the principle of the implementation seems to be viable 👍 . I feel comfortable landing this as is, or with the modification to the namespace.

Thank you all!

[ItsJonQ]

@jorgefilipecosta Halloo!!! Just wanted to verify! It looks like there are two hyphens after the prefix, example:

--wp-block-core-button--color--background

Note: --color--background

Is this intentional?

[jorgefilipecosta]

Yes, it is intentional to remove ambiguity. If we don't add two hyphens, we don't know if the variable represents this object { ... { color: { background: ... } } } or this one { ...{ 'color-background': ... } }. Having two different object shapes generate the same variables is something that would, for sure, cause problems as an object may overwrite the styles of another object when it is not supposed.

[ItsJonQ]

Cool! I'm down with this approach 👍
Thank you!

[gziolo]

There is one thing that I would like to understand better. How do you envision the future of the theme.json file? In particular, I was wondering what would be the preferred way to create and edit this file? I'm aware that it might be a premature question, but it looks like the current format is optimized for reading by software:

{
	"global": {
		"color": {
			"primary": "green",
			"background": "red",
			"text": "red"
		}
	},
	"blocks": {
		"core/paragraph": {
			"color": {
				"text": "hotpink"
			}
		},
		"core/button": {
			"color": {
				"background": "pink"
			}
		}
	}
}

What I mean by that is, the way it's structured makes it very easy to modify default global styles for all individual blocks. However, it might be not the best approach in terms of maintenance if it would be something that is done manually and need to support modifications on many individual blocks. I It will become more evident once there are examples where people try to apply the same type of overrides for blocks that share similar characteristics, e.g. change text color to pink for all text blocks, or change the background color for all media blocks. In the current shape, all custom blocks couldn't be supported in theme.json with individual overrides because the author doesn't know their name.

It's not that important at the moment but something we should think about in the long term. One thing to consider could be adding theme property to the block definition to make it more fun :)

[aduth]

This file isn't included in the plugin:

https://plugins.trac.wordpress.org/browser/gutenberg/tags/7.7.1

Because we whitelist files to include in the ZIP, and this isn't one of them:

gutenberg/bin/build-plugin-zip.sh

Lines 112 to 125 in 56a12a6

	build_files=$(ls build/*/*.{js,css,asset.php} build/block-library/blocks/*.php build/block-library/blocks/*/block.json)
	# Generate the plugin zip file.
	status "Creating archive... 🎁"
	zip -r gutenberg.zip \
	gutenberg.php \
	lib \
	packages/block-serialization-default-parser/*.php \
	post-content.php \
	$vendor_scripts \
	$build_files \
	readme.txt \
	changelog.txt \
	README.md

We could simply add the pattern there, but I also think we should try to align some convention of where we want these sort of static files to live.

• https://github.com/WordPress/gutenberg/tree/master/lib/demo-block-template-parts
• https://github.com/WordPress/gutenberg/tree/master/lib/demo-block-templates
• https://github.com/WordPress/gutenberg/tree/master/lib/patterns

If we move this into lib or a subfolder, it would be included.

[oandregal]

This PR moves it within lib/global-styles.