Global styles: let plugins register global styles with a plugin.json file

[nickcernis]

The excellent Global Styles proposal assumes that:

1. WordPress sets global style defaults (currently experimental-default-global-styles.json).
2. Theme developers can override and extend the defaults via theme.json in their theme root.
3. Users can override select styles set by WP or the theme via the WP admin.

Plugin developers do not currently fit into this vision, as far as I can see. But global styles will be very useful to them too.

Proposal

1. Let plugins register global styles by including a plugin.json (or similar), in the same format as the existing theme.json for themes.
2. Refactor gutenberg_experimental_global_styles_has_theme_support() to make global styles available to end users if:
   1. theme.json exists in theme (current behavior)
   2. plugin.json exists in any active plugin

Stories

As a plugin developer, I want to add named styles that theme developers can override and users can adjust.

I want to ensure these global styles are available to users even if the theme does not contain a theme.json, because a user might still want to adjust my plugin styles even if the theme developer does not.

As a theme developer, I want to be able to see which styles a plugin developer thinks are public and safe for theme developers to override, and override the styles in an easy way.

As an end user, I want to adjust the appearance of a plugin in a way that feels native to WordPress, without having to learn the plugin developer's styling UI if they even offer one.

Scenario

My goal is to make styling adjustments easier for blocks that my plugin provides.

I add a plugin.json to my plugin root:

{	
	"color": {
		"robots": "#bdbdbd"
		…
	},
	"custom": { 
		"icon-border-radius": "10px",		
		…
	}
}

WordPress loads this between core styles and theme styles, automatically prepending CSS vars with my plugin slug.

Now theme styles can override my plugin styles by:

1. Copying the plugin.json to the theme.json.
2. Wrapping that json with a key for my plugin slug.
3. Removing defaults they don't want to change, and adjusting those they do.

(WP-CLI or other tooling could potentially automate 1 and 2 via wp global-styles import plugin-slug theme-slug or similar.)

And users can override via the admin area.

No-one has to work out how to override my plugin's CSS, which I’m now free to refactor as long as I maintain the global vars I exposed via my plugin.json, which represents my plugin's “public styling API”.

To adjust the vars, I can update plugin.json and ship a new version of the plugin.

If/when global styling is extended to include block properties that relate to visual styling instead of just CSS properties, theme developers will also be able to override default properties for my blocks to suit their theme.

Implementation

The existing global-styles.php loader could be adjusted to import the plugin.json file into the tree for each active plugin.

Alternatively, plugins could be asked to call a function such as register_global_styles() that defaults to plugin.json or specify a path to their JSON file in case they are using a plugin.json file for another purpose already.

[nickcernis]

I'd like to work on a PR for this, but have a few questions about the implementation:

1. Are there any opinions about what the JSON file in the plugin should be called? Some candidates:

   1. plugin.json
   2. global-styles.json
   3. styles.json
   4. globals.json

2. Should plugin devs have to register for global styles and specify their JSON file path? Or should we look for the named JSON file in all active plugins by walking them manually?

3. I envision placing plugin styles in the style tree under a plugins root key, with each plugin under a key for the plugin slug. Does that sound ok? Or do we just use the plugin slug at the root level?

[johnstonphilip]

@nickcernis Personally I like global-styles.json the most, as it helps to explain it without any additional context required.

[oandregal]

Thanks for taking the time and send feedback, Nick. We're in the very early stages, so we're particularly interested in hearing use cases like this. The use case of third-party blocks is definitely in our minds, so ace for commenting on that!

I can share a few of our current operating assumptions that perhaps are relevant for this:

Third-parties (themes, plugins) can't declare new variables. The reason is the potential design fragmentation caused by every block declaring its own different variables would lead to a bad experience for users.

It'd be opt-in. Otherwise, it can potentially break existing themes.

There are other things you touch upon that are on our radar, such as how blocks (core and third-party) would declare their "styling hooks" or "public style API", how they should provide defaults, how would UI controls be bound to block declarations, etc. Those are our current areas of work! We need to solve a few things before being able to commit to a specific format to set things up.

[nickcernis]

Thanks for the feedback, @nosolosw!

Third-parties (themes, plugins) can't declare new variables. The reason is the potential design fragmentation caused by every block declaring its own different variables would lead to a bad experience for users.

Ah, so the current plan is for WP core to “bless” a group of global style settings and hard-code a UI for each setting, without making it filterable or extensible.

…on our radar, such as how blocks (core and third-party) would declare their "styling hooks" or "public style API", how they should provide defaults, how would UI controls be bound to block declarations, etc.

Thanks for highlighting these initiatives.

It seems natural that themes and plugins will want to introduce additional styling controls without having to reinvent the global styles UI and APIs, just as it sounds like blocks will be able to do.

[oandregal]

Ah, so the current plan is for WP core to “bless” a group of global style settings and hard-code a UI for each setting, without making it filterable or extensible.

We are going to consider some extension points. However, before crossing that bridge, we want to stabilize the essential components & mechanics. That's why use cases are super helpful at this moment! They help us to bring clarity around the different pieces we're building.

[bradhogan]

I'd like to follow up on this. It seems odd that a plugin can't define it's own "theme.json" - or plugin.json - to set template parts, templates and other styles. For instance, if I want to register a post type "books" using 5.9+, I should do this in a plugin (and not the theme - per WP public directory requirements you can't have a CPT registered in a theme) but if I register a CPT in my plugin, I have no way to assign template parts nor templates to the CPT. I'm only allowed to use the templates registered in the theme.

CPTs in general have been left out of the recent 5.9 and this is a HUGE issue as tons of us rely on using CPTs for our client sites (portfolios, books, courses, etc.).

[youknowriad]

It seems we made a lot of progress to address this issue lately. The register_block_style function now allows registering a style variation using theme.json syntax. The missing part is being able to register a global style variation. It would be a nice thing to have indeed.