I'm not sure appearanceTools in theme.json is the right idea.

[johnstonphilip]

I am seeing a new setting for theme.json called appearanceTools that turns on a bunch of things with a single setting. While I can see the appeal in reducing the size of a theme.json file, I feel like this might cause more confusion than it's worth.

The goal of the setting is purely to reduce the size of theme.json, is that correct?

This is ultimately an abstraction that makes theme.json less clear and less verbose; less easy to understand. It essentially hides options, making it harder to understand what is happening when editing a theme.json file.

If the only advantage to this is to reduce the size of theme.json, I would like to suggest that it's not worth the loss in understanding and clarity.

Is there another advantage to having appearanceTools that I'm not seeing?

[johnstonphilip]

Wondering if you might have more insight @carolinan

[jffng]

Here is some related background on how this flag came about: #36187 #36246

The goal of the setting is purely to reduce the size of theme.json, is that correct?

In general, I think this flag exists to make it simple to opt-in to new design tools as they are added, rather than having to opt in to each one individually, especially since new features get added frequently.

[mtias]

Correct, it's less about the reduced size of declarations and more about defining what the default behaviour should be for new design tools added to blocks (if they should be enabled by default, even if the theme doesn't explicitly toggle them on, or if they should require an explicit opt-in).

[ALJ]

it's less about the reduced size of declarations and more about defining what the default behaviour should be for new design tools added to blocks

@mtias If this is the main intention (which I think is great), then it's not communicated via the documentation. Reading the docs, I would come to the same conclusion @johnstonphilip did.

The What's new in Gutenberg 12.1 post gives better context and guidance on why appearanceTools is useful:

... opt-in into ... any appearance tool that might be added in the future. Generic block themes in the repository may consider enabling this flag automatically to avoid having to keep track of all the additions that come over time.

What's the best way to suggest edits to the docs?

[mtias]

That'd be good. You can edit and suggest a PR directly on the file: https://github.com/WordPress/gutenberg/blob/trunk/docs/how-to-guides/themes/theme-json.md

[ALJ]

Done: #40333 thanks for the quick reply!

[mtias]

Thank you for contributing :)

[mtias]

The context for this flag is that new design tools are generally added in an opt-in way, since site maintainers, custom themes, etc, usually don't want to be on the lookout for things they might need to disable from new WordPress releases to provide a controlled experience.

At the same time, there are many themes (in a sense, most of the .org theme directory) for which it's desirable that all new tools are made available as soon as they are introduced without having to release a new update of the theme. This means users of the theme get to benefit from updates to the core editor experience without requiring the theme itself to keep updating its json file.

This flag is meant to capture both use cases.

[theking2]

a flag to (dis)allow random changes for color, font, size etc. would be more helpful. Editors should be able to edit text and select from basic styles like emphasis or strong but not to change color .

[carolinan]

It is already possible to disable the color picker by adding

"settings": {
		"color": {
			"custom": false
		}
	}

[theking2]

I didn't know and that is awesome. Is this in the documentation?

[carolinan]

Yes it is in the reference:
https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#color

[tedw]

FWIW setting "appearanceTools": false and "position": { "sticky": false } in WP 6.3.2 will throw a JSON syntax error:

ErrorException (E_USER_NOTICE)
Error when decoding a JSON file at path /app/web/wp-content/themes/my-theme/theme.json: Syntax error

I realize position isn’t necessary when disabling appearanceTools but getting a JSON syntax error is very confusing, especially since the JSON is valid.

@carolinan Huge fan of your site (https://fullsiteediting.com) been referencing it for years—thank so much for maintaining that! 🙏

Currently, if I use the theme.json reset on https://fullsiteediting.com/lessons/remove-settings-in-theme-json/ I get the error above.

[talldan]

JSON doesn't support trailing commas, so you may have to remove them from the example. The error is correct in that it's invalid JSON.

[carolinan]

Thanks, those are typos yes 👍