Theme.json schema block properties: valid vs supported

[ryanwelcher]

The theme.json schema indicates that each block supports all of the valid properties that are enabled globally for color, spacing, and typography. While these entries are technically valid they do not reflect whether or not the individual block supports or respects the value.

There are some blocks that either a) don't opt-in to using the control or b) don't actually respect the setting. In these cases, would it be beneficial to have the schema reflect these cases and only include valid and supported items for each block?

Having the schema be more verbose and actually represent the functionality as well as what is valid would go along way for the developer experience and reduce confusion.

[ryanwelcher]

cc @mkaz @ajlende @fabiankaegy

[mkaz]

Yes, I think only having the properties the block actually supports as valid entries in the schema is best.

Agree, it will save some headache if someone updates their theme.json and shows as valid but then the setting doesn't show on the site for them.

[carolinan]

I am not sure I understand correctly.
Theme authors use theme.json to set defaults for blocks -including defaults for block styles that do not have a control.

Are you suggesting that setting a default value will not be valid unless there is also a user facing control in the editor?

If that is the case, I disagree. For example I may need to set a default font family to a block that does not have a font family setting.

[ryanwelcher]

Are you suggesting that setting a default value will not be valid unless there is also a user-facing control in the editor?

Not at all and perhaps my use-case was too strict 😄 What I am suggesting is that if a block setting doesn't actually have an effect on a block, then it should be removed from the Schema.

For example according to the schema, the core/button should support borders.width but setting that value doesn't actually do anything. Given that when other blocks use that setting, core/code for example, that the associated controls appear it is a very confusing developer experience as to why one works and the other does not.

For example I may need to set a default font family to a block that does not have a font family setting.

Is there a block that supports that property that doesn't show the font selector? If so, then I think that would remain in the schema although that would also be a strange experience as to why that setting in a different block would produce controls.

[ajlende]

One thing that should be noted is that some settings still generate CSS variables in the scope of the block that can be used by themes even if they don't have the UI in the block editor.

For example, this JSON generates this css for the core/button block.

{
	"settings": {
		"blocks": {
			"core/button": {
				"color": {
					"palette": [
						{
							"color": "#000",
							"name": "black",
							"slug": "black"
						},
						{
							"color": "#FFF",
							"name": "white",
							"slug": "white"
						}
					]
				}
			}
		}
	}
}

.wp-block-button__link {
	--wp--preset--color--black: #000;
	--wp--preset--color--white: #FFF;
}

[ryanwelcher]

@ajlende that makes sense and in this case, we'd obviously leave that in for the core/button block and perhaps all blocks as I assume color.palette has the same effect for all blocks.

[carolinan]

Thank you for explaining, it is clearer now and I agree :)

a strange experience as to why that setting in a different block would produce controls.

Yes, I have experienced that confusion myself, as there is no longer a list of which block supports which control.
I believe this will be remedied by planned improvements to the documentation.

[ryanwelcher]

Yes, I have experienced that confusion myself, as there is no longer a list of which block supports which control. I believe this will be remedied by planned improvements to the documentation.

These proposed updates could also help here as well.

[ryanwelcher]

Now that #36746 has been merged, I'd like to use this ticket to track which blocks need updates in the schema in order to properly reflect what properties are actually supported.