enhancement: improve how extenders can add global CSS to editor and frontend

[tresorama]

What problem does this address?

While working on a block theme for the first time, i was stuck at loading a global CSS with utilities classes inside.
The Developer experience is a mess currently.
This should be improved because extenders (theme dev /plugin dev) are crucial for Wordpress.

There are various bad "things" currently in place that a dev must fight against to complete a simple task.

I have made a tutorial post to illustrate the process

https://jacopomarrone.netlify.app/blog/load-global-css-in-block-theme-in-wordpress

Main Painponts

Should be easies to inject a simple CSS. With Javascript ??

We should know that iframe receive CSS assets only if some CSS selector are present. This alone is big ALARM that maybe a refactor is necessary.

Inject CSS to the editor iframe should be done with a dedicated hook or similar process, and now is not present.

Core css specificity is high for an extendible system:

• in editor we must fight with a scoped selector and !important
• in frontend we must fight with !important

It difficult to say to wordpress when to inject our custom css relative to the theme.json one. This lead us to increase even more the specificity of CSS selectors.

It impossible to add a medium amount of CSS without a CSS preprocessor that support nesting.

Imagine a child theme that want to overrides ?!?!?

Related

#48437
#41821
#38673 (comment)
#33212

---

What is your proposed solution?

Start discussing about how to improve these, and if necessary :

• exposing a new API
• consider a refactor
• consider a redesign

[VladNov]

There is no need for extra CSS and media queries, use build-in fluid font sizes:

https://make.wordpress.org/core/2022/10/03/fluid-font-sizes-in-wordpress-6-1/

@tresorama Congratulations on working on your first block theme! Super exciting stuff.

I completely understand that the documentation which is work-in-progress might be overwhelming when there's so many new things to learn. That doesn't necessarily mean Gutenberg is a mess right now, just that it takes a bit more effort than what you're already familiar with.

I think this isn't a problem of what's possible, but of the approach you're taking. It's discouraged to overwrite the font size like this, cause it breaks the option to change the font size in the block's settings.

First you define font sizes in your theme.json. If it's an external theme and you're a plugin developer, you can define font sizes in your stylesheets in block.json, one for both front- and backend and one for just the backend.

If you want to alter an existing block, try block variations.

Good luck!

[tresorama]

@tresorama Congratulations on working on your first block theme! Super exciting stuff.

I completely understand that the documentation which is work-in-progress might be overwhelming when there's so many new things to learn. That doesn't necessarily mean Gutenberg is a mess right now, just that it takes a bit more effort than what you're already familiar with.

I think this isn't a problem of what's possible, but of the approach you're taking. It's discouraged to overwrite the font size like this, cause it breaks the option to change the font size in the block's settings.

First you define font sizes in your theme.json. If it's an external theme and you're a plugin developer, you can define font sizes in your stylesheets in block.json, one for both front- and backend and one for just the backend.

If you want to alter an existing block, try block variations.

Good luck!

I explain my block theme workflow to have more context.

I try to do almost everything on theme.json.
So i defined my design tokens in theme.json, the block editor can now expose my tokens under blocks attribute controls (in the sidebar).
So font size, colors, spacing.

This is the design system primitive.

Then i go in the editor and create template parts and templates, extracting these into .html file under theme directory.
Then i slice my templates into block pattern and copy into .php file under theme directory.

While designing/developing templates in the block editor I use core blocks only and adjust font size, padding, color, using tokens defined in theme.json, no custom value.
So i create all my design in desktop view.
So far so good, it looks great.

Then i check my templates and page with tablet and mobile preview and some block need adjustments, (text too large, gap between items too large, and so on...). These responsive adjustment are not high in quantity but they exists.

So i started researching how to compensate for responsiveness, and tried different plugin also. This is what i found.

• Fluid Typography in theme.json, (like @VladNov suggested)

  I used fluid typography in the past but at least for my first attempt i want to try something else, more agnostic of the current project
  What about spacing ? Fluid spacing ?

• Use utility classes in Advanced > Additional CSS Classes to perform overrides in tablet and mobile view, because Gutenberg encourage a desktop-first approach

  like in Editorskit where you add an autocomplete to the with data (array of classes as strings) from PHP
  like in [Redux/Extendify](https://extendify.com/library/ where they did the same of EditorsKit and create a library of block patterns

• Good old CSS in theme directory

  I want my design decision all in the same place, so in the editor because the desktop view is built there. All my website is built there.
  I don't like context switching between CSS and editor
  In future, if user wants to change something he should first find how to read these files and also understand the CSS flow created by me.

• Use Gutenberg blocks from third-party plugins, that expose responsive control

  Last resort, i want to avoid for if i can.
  Instead i'm ok to use plugin for blocks not provided by core, accordions, forms, ...

Other key aspect ,at least for me, that made me prefer CSS utilities classes:

• These classes can be used for little fix while gutenberg add features (position: sticky or fixed, width: auto, width: 100%, ... ) that sometimes are required (rare but exists)
• These classes can be added on third party blocks (created by plugins) without writing new CSS files. You just fill the "Additional CSS Classes"
• When, in future core Gutenberg make some utilities classes you applied unnecessary, it is easy to refactor. You don't have to go through CSS file to understand what can be removed and what not (orphan css)
• personal preference 😁

So I tried to adopt this "way" to deal with responsiveness.
At least for current sperimentation.

This mens that i "design" the desktop version with the UI, and apply overrides with CSS utilities only for tablet and mobile, only if it's required.

---

Coming back to original question, that was "how hard is to add a global CSS file, that will be loaded both in frontend, both in editor iframe", there is a better solution than what i describe in the blogpost attached in this issue.

I was not aware that add_editor_style injects css in iframe of block editor at time of writing.
More #48437.
I created a "documentation" issue for posterity #48497.

[tresorama]

For 2025 solution on how to add a global CSS file in the frontend and/or on the Gutenberg Editor Iframe see this