Global styles: add custom CSS panel to site editor

[glendaviesnz]

What?

Adds a custom CSS input option to global styles in the site editor.

Why?

Because this option was available to users in customizer, but there is no option to add arbitrary CSS via the site editor.
Part of: #30142

How?

• Adds a css property to theme.json styles - styles.css
• Saves the global custom CSS to the wp_global_styles CPT
• In the site editor the content of styles.css is added to a separate style sheet. Initially, it was just appended to the end of the existing global styles style sheet, but the issue with this approach was that any invalid CSS entered caused all global styles to stop working as the styles are parsed with js. Having a separate style sheet means any invalid CSS entered only breaks the custom CSS and all other global styles work as expected. It seems like just appending it to the end of the global styles style sheet works for the post editor and frontend though.

Testing Instructions

• In the site editor open the global styles panel
• Go to Custom CSS option at the bottom of the panel
• Enter your favorite CSS and save
• Check the CSS is applied in site editor, post editor and front end
• Add a styles.css property to your theme.json file and make sure that it displays as expected. Then add some user custom CSS, and make sure the theme.json setting displays in the input box and make sure that this can be removed or overriden in site and page editor and front end
• Add a styles.css property to the core theme.json, and make sure this is correctly overridden by the themes theme.json setting and also the user custom CSS

Known issue

Currently, any changes to the custom CSS that are not valid CSS will cause all the custom CSS to stop applying until the CSS is made valid again. Because of the way that CSS is parsed and rewritten for the site editor this is going to be difficult to fix so will be handled in a follow up.

Screenshots or screencast

customcss3.mp4

[Mamaduka]

The custom CSS also needs to be added to the get_block_editor_settings, probably as one of the global styles.

@oandregal, would it make sense to add customCSS as one of the type variations for the wp_get_global_stylesheet?

[glendaviesnz]

The custom CSS also needs to be added to the get_block_editor_settings, probably as one of the global styles.
@oandregal, would it make sense to add customCSS as one of the type variations for the wp_get_global_stylesheet?

Have done this by adding the extra type variation as suggested and all seems to work, but would still be good to get your view on whether this is a good approach @oandregal

[glendaviesnz]

@Mamaduka I have copied across the basic CSS validation from customizer

[talldan]

It looks really good so far, I'm impressed by what this PR achieves. Only very minor comments, though I haven't looked too deeply into the global styles and REST API code, which isn't my strongest area.

In using it there were a few things I noticed:

• The textarea could be taller when initially opened
• The textarea could use a monospaced font
• When there are invalid styles, the entire editor styles seem to no longer be applied to the editor. It'd be nice only the custom styles are not applied.

[aaronrobertshaw]

Nice work @glendaviesnz, it’s awesome to see this greatly anticipated addition in Global Styles coming together 🎉

Overall this tests nicely:

✅ Custom CSS is applied in the editors and frontend
✅ PHP unit tests pass
❔ Clearing custom CSS isn't immediately reflected in the editor as noted

@talldan beat me to suggesting a few UI tweaks. I think his list covers most of what I noted while testing. The only addition I had might be more a personal preference.

On the main Global Styles screen the help text for both “Blocks” and “Custom” start in an identical way which makes things feel a bit harder to scan at a glance. That probably isn’t helped by the two nearly having the same shape as well. So I was wondering if this is something we might tweak in a follow-up to potentially help users with different visual needs or dyslexia?

it is tricky to find a workaround

Indeed.

I'm not sure I have the full history on the Custom CSS work so likely have a bunch of false assumptions.

In #46255 we added the css property to the theme.json schema. Does this mean we are officially supporting that property in actual theme.json files? Or, was it only added to cover the custom CSS added by users via the Global Styles UI?

If it is the latter reasoning, would it be possible to make the css property only conditionally allowed depending on the "origin" for the theme.json? I don't think that is something currently represented in the schema so perhaps not.

The reason I'm querying if the styles.css property is only to be supported with the user origin is that we might be able to add a slightly different hack to force the user's clearing of the custom CSS to take effect.

Example tweak to `global-styles-provider.js`

diff --git a/packages/edit-site/src/components/global-styles/global-styles-provider.js b/packages/edit-site/src/components/global-styles/global-styles-provider.js
index 0ae154c11b..2e923772cc 100644
--- a/packages/edit-site/src/components/global-styles/global-styles-provider.js
+++ b/packages/edit-site/src/components/global-styles/global-styles-provider.js
@@ -44,6 +44,10 @@ const cleanEmptyObject = ( object ) => {
 	return isEmpty( cleanedNestedObjects ) ? undefined : cleanedNestedObjects;
 };
 
+const cleanObjectWithCustomCSS = ( object ) => {
+	return { ...cleanEmptyObject( object ), css: object?.css };
+};
+
 function useGlobalStylesUserConfig() {
 	const { globalStylesId, isReady, settings, styles } = useSelect(
 		( select ) => {
@@ -106,7 +110,7 @@ function useGlobalStylesUserConfig() {
 			};
 			const updatedConfig = callback( currentConfig );
 			editEntityRecord( 'root', 'globalStyles', globalStylesId, {
-				styles: cleanEmptyObject( updatedConfig.styles ) || {},
+				styles: cleanObjectWithCustomCSS( updatedConfig.styles ),
 				settings: cleanEmptyObject( updatedConfig.settings ) || {},
 			} );
 		},

The above change at least achieves the desired behaviour as I understand it. Maybe it can help spark new ideas and a better solution.

Demo video of tweaked behaviour

Screen.Recording.2022-12-07.at.4.53.09.pm.mp4

[glendaviesnz]

Details for Dev Note

A custom CSS input box has been added to the Global Styles settings in the site editor. This provides similar functionality to the custom CSS input available in Customizer for classic themes. This option appears under the global styles actions menu:

Ideally, this input should be seen as a last resort fallback to add styling that can't yet be implemented with the other editor design tools. Some other important things to note are:

• This custom CSS does not use the same custom_css CPT as the Customizer custom CSS, but instead is part of the existing Global Styles wp_global_styles CPT
• As with the other user custom global styles the custom CSS is specific to the current theme
• In order to support custom CSS as part of Global Styles a new property has been added to theme.json - styles.css
• While the addition of the styles.css property to theme.json does allow theme authors to use it to include custom CSS strings in their themes, as with the user input for this property ideally themes should only use this as a last resort fallback to add styling that can't yet be implemented with the other editor design tools
• Theme authors should note that users’ custom CSS can completely override or remove any theme custom CSS set in the theme.json, so in cases where theme authors do not want users to easily wipe custom CSS they should consider including it via the existing style sheet enqueuing methods
• Because the standard global styles flow is for user data to override theme data, it would be possible for users to inadvertently override a key theme custom CSS setting, eg. add a custom image background to a group and in the process wipe a background that the theme was adding to headings. For this reason, when a user first edits the custom CSS the theme CSS is shown in the input box to allow the user to selectively and knowingly override/remove any theme custom CSS

[Slals]

Hi,

I'm building a website using Gutenberg. It's a very nice feature that I want to use. I'm building on top for "Twenty Twenty-Three" theme.

How can I activate this feature?

[glendaviesnz]

How can I activate this feature?

@Slals currently you need to have the Gutenberg plugin installed and then enable the Custom CSS experiment under the Gutenberg Experiments menu in WP admin:

[bph]

@glendaviesnz could you do me a favor and review the above Dev Note?
It's been a few weeks since you wrote it and there might have been changes to the feature after that. Would you have time to combine your Dev Note with @carolinan's into a "Custom CSS for Global Styles and per block in theme.json" stand-alone post on the Make Core Blog by Thursday? I know it's short-term notice, so please notify me if that doesn't work and I will handle it.

[glendaviesnz]

@bph was still accurate, but I added a note about the location of the feature under the global styles action menu.

[porg]

Thanks for this feature!

• I already teased it as a Q & A on wordpress.stackexchange.com.

Usability Feedback:

• My initial thought process regarding need→solution was the exact same analogy to the Theme Customizer that you stated in your What? and Why?
• So as a professional UX designer I can say in terms of information architecture and consistency this will reach existing users perfectly.
• But overally, especially for new users, I support the usability analysis and subsequent proposals of James Koster, that the Styles section as the n°1 area of customization is hidden too deep in the IA of the Site Editor, and very much appreciate what James Koster worked out in https://jameskoster.design/2022/08/24/revising-the-presentation-of-key-site-editor-features/
  • In that spirit "Custom CSS" for Block Themes will move its UI position accordingly.
  • But function wise it is just a text area.
  • Possibly with syntax highlighting and code completion as in the Theme Customizer.
• Near the text area offer an adequate link to how the Modular CSS of Block Themes (aka Style Engine) works. As this differs much from classical themes and currently develops very rapidly. Helpful links like:
  • https://developer.wordpress.org/block-editor/explanations/architecture/styles/#global-styles
  • https://developer.wordpress.org/block-editor/reference-guides/packages/packages-style-engine/

[youknowriad]

Hi there! I was trying to refactor this control to be like all the other "style" UI components and stumbled upon this specific behavior for custom CSS, where it seems that we need to be aware of "base" styles and have some custom behavior tied to it. Can you explain it a bit further and also why it has to be this way, why don't we treat the "css" theme.json property like any other property?

[glendaviesnz]

Some initial testing showed that it was confusing that any theme.json custom CSS was overridden completely by any custom CSS added as initially it took the same approach as other global styles in that user styles override the theme.json settings. For example, the theme.json CSS might set a heading font color, and the user may add a paragraph font family which will wipe the heading font color.

So a decision was made to include the theme.json CSS in the global styles input box to allow the user to make a conscious choice about which ones to keep.

[youknowriad]

Some initial testing showed that it was confusing that any theme.json custom CSS was overridden completely by any custom CSS added as initially it took the same approach as other global styles in that user styles override the theme.json settings. For example, the theme.json CSS might set a heading font color, and the user may add a paragraph font family which will wipe the heading font color.

For me this is only confusing, if the CSS is not shown initially in the box.

[youknowriad]

So a decision was made to include the theme.json CSS in the global styles input box to allow the user to make a conscious choice about which ones to keep.

Re-reading this, it seems like you're saying that we're already showing the theme.json CSS in the box, which is what I would expect as well, but I guess the different maybe when we edit that CSS.

For me, after editing, we should only show the edited CSS (which may or may not contain some parts of the original theme.json CSS).

[glendaviesnz]

For me, after editing, we should only show the edited CSS (which may or may not contain some parts of the original theme.json CSS)

Sorry for the confusion. This is correct, this is what happens, after editing only the edited CSS shows in the input, and the original CSS from the theme.json shows above the input in case the user wants to reinstate it:

custom-css.mp4