Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
nickcernis opened this issue Feb 25, 2020 · 5 comments
Open

Comments

@nickcernis
Copy link
Contributor

@nickcernis nickcernis commented Feb 25, 2020

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

This comment has been minimized.

Copy link
Contributor Author

@nickcernis nickcernis commented Mar 4, 2020

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

This comment has been minimized.

Copy link
Contributor

@johnstonphilip johnstonphilip commented Mar 4, 2020

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

@nosolosw

This comment has been minimized.

Copy link
Member

@nosolosw nosolosw commented Mar 4, 2020

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

This comment has been minimized.

Copy link
Contributor Author

@nickcernis nickcernis commented Mar 4, 2020

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.

@nosolosw

This comment has been minimized.

Copy link
Member

@nosolosw nosolosw commented Mar 4, 2020

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.