Global Styles: consider loading user styles after theme styles

[jffng]

Description

Currently styles load in the following order:

1. Block library styles
2. Global styles — core + theme.json + user styles set via the site editor. All of these are combined into global-styles-inline-css
3. Theme styles

For example, this is from emptytheme:

This loading order can cause unexpected behavior when the theme wants to specify some defaults that are not entirely possible via theme.json, but still allow for user styles to take precedence. For an example of where this can create unexpected behavior, see Automattic/themes#4435

What is your proposed solution?

Within global styles, it could be useful to separate user styles from the core + theme.json styles. This way, the loading order could be:

1. Block library styles
2. Global styles — core + theme.json
3. Theme styles
4. Global styles — user styles

[creativecoder]

Potential fix for this issue in #34147

[oandregal]

👋 Would like to understand what's the issue you're experiencing.

The styles are enqueued as they are expected: first the core styles (block-library, global styles), then the theme styles. This has been always like this and the introduction of global styles respected this order. It's intentional, so the theme can overwrite the core styles just by being enqueued later (no extra specificity required).

[oandregal]

It'd be helpful if "how to reproduce" instructions were posted in this issue for people that are not aware of how to work with a theme like BlockBase. I've struggled a bit to make it work. For reference, this is what I've done after some trial&error:

• Clone the https://github.com/Automattic/themes repo.
• cd blockbase && npm run build
• Use and activate the BlockBase theme in your WordPress setup.

Now, the testing instructions:

• Go to the site editor.
• Add a button block.
• Via the global styles sidebar, select text & background colors for the button (via "By Block Type" menu tab, "Button" section).

The expected result is that user-provided styles should be reflected in the site editor & front-end. They're not.

---

This is what I see: the reason why the user styles are not applied is that the theme overrides them. This is what BlockBase is doing:

1. Uses theme.json to provide button styles. These will be used by the site editor to consolidate with user styles, if there's some, only outputting theme or user styles.
2. The theme enqueues a stylesheet that overwrites the same colors provided via global styles, including future user choices as well:

.wp-block-button.wp-block-button__link, .wp-block-button .wp-block-button__link {
  color: var(--wp--custom--button--color--text);
  background-color: var(--wp--custom--button--color--background);
}

Why does BlockBase need to provide a stylesheet that overrides the styles already set via its own theme.json?

[jffng]

@nosolosw thank you for the thoughtful reply. Apologies for not providing better testing instructions or rationale for why this change could be useful. My general assumption was that if a user makes a customization via global styles UI, it should always win / override the theme's preferences.

Why does BlockBase need to provide a stylesheet that overrides the styles already set via its own theme.json?

The short answer is, we shouldn't be. The principle behind blockbase is that CSS should only exist where theme.json does not supply a way to style the block or element. But in the case of the button block, there are a few places that rule falls apart a bit:

• Not all buttons are button blocks e.g. comments, forms, search block, file block. In Blockbase and its children, we sought to provide a simple way to customize the color of all buttons using the existing design tools. To do this, we used a semantic color system that maps a color preset to a custom variable that is used in both theme.json and CSS where there is not yet an existing mechanism to target the button. That way, if the user changes the primary color of the palette, buttons everywhere would update accordingly. We applied this patch CSS to button blocks too, but as demonstrated in Blockbase: Ponyfill css overrides block-level global styles for Button block Automattic/themes#4435, we need to be more selective about this.
• To provide button hover styles according to a theme design target we're aiming to achieve, we need more specific control over and access to the padding and border values (since the design of the button hover states use an outline / border effect, we can't just rely on the theme.json padding value otherwise the size of the button will look different between hover/non-hover states).

All that said, I think we can close this issue; it can be resolved mostly in Blockbase by removing the theme.json configurable CSS for the button block, and I don't think the use cases described above justify changing the loading order.

[oandregal]

Thanks for sharing the extra context, it's very valuable to me: it shows me practical cases in which the theme.json is not yet fully functional.

This is what I hear:

1. There're components of the design for which we don't have a way to change all "components of a type" at once. Example: the button block, the button within search, etc. should be addressable at once.

2. There're components of the design that can't be addressed yet. Example: the button in the search block.

3. Some designs require coordination across properties for different states (rest vs hover). Example: maintaining spacing while changing padding&border values.

I don't have answers yet, but distilling this feedback for our future selves will help us get there.

[oandregal]

I keep thinking about the order of styles. I do think the current order of styles is correct as far as core and theme styles go:

1. Block styles: block-library, 3rd party block styles, global-styles-inline-css (core and theme).
2. Theme stylesheets.

However, there's the gray area of user styles that will be introduced with the site editor. I've been operating under the assumption that user styles provided via the GS sidebar would also be part of the global-styles-inline-css stylesheet, as they work today. However, it can be argued that it should work like this:

1. Block styles: block-library, 3rd party block styles, global-styles-inline-css (core and theme).
2. Theme stylesheets.
3. User styles: global-styles-user-inline-css.

@jffng Would this approach help address the issue with padding & border? Or would it be more problematic as user styles would have higher priority by being later in the chain?

[oandregal]

At #34196 I've shared an idea that could be helpful for the issue with buttons.

[MaggieCabrera]

However, it can be argued that it should work like this:

1. Block styles: block-library, 3rd party block styles, `global-styles-inline-css` (core and theme).

2. Theme stylesheets.

3. User styles: `global-styles-user-inline-css`.

Yes! I think this is what was happening exactly in this case. Whatever the user changes should take precedence over what the theme initially offers.