Improve discoverability of "Additional CSS", use for editor education

[mrwweb]

What problem does this address?

The "Additional CSS" panel was recently hidden deeper in a menu of the Styles editor.

I think this was both a mistake and a lost opportunity. Instead, I think the Additional CSS feature should be treated as a first-class citizen and used to educate site owners.

The "Additional CSS" Site Editor feature is a feature of "last resort" (h/t @westonruter) in many ways, because custom CSS overriding block styles is clearly a bad editor and developer experience.

However, Additional CSS is likely to also remain a core tool for any site owner that needs to go beyond the subset of CSS supported by the Site Editor. Even though theme.json and the Site Editor continue to increase their support of many choices, they will never come close to supporting everything a developer might need. At this moment that includes (but is far from limited to):

• Anything but the simplest hover/focus styles
• Styles targeting the presences of .has-background, .alignfull, .alignwide, .is-layout-grid, etc.
• Styles targeting blocks in blocks (e.g. .wp-block-column .wp-block-quote)
• @media queries including prefers-reduced-motion and print
• 3rd-party blocks that don't support as much styling as core blocks
• Pseudo elements
• Most form elements
• Any CSS logic with :has(), :not(); :nth-*(), etc.
• Tables
• Many child elements of blocks
• text-wrap: balance and text-wrap: pretty
• CSS mask
• Multiple backgrounds
• background-blend-mode and mix-blend-mode
• CSS transforms
• CSS transitions

The point being: Additional CSS is and will remain a necessary feature for many sites with even just a few small design needs that exceed the Site Editor's capabilities.

What is your proposed solution?

I believe Additional CSS should be pulled out of the hidden menu, places last to emphasize it's intended use, and then provided with a message to educate users. That could look something like this:

Suggested text from screenshot:

Custom CSS is a powerful customization tool. For best results, use existing settings for colors, fonts, block styles, and more before writing custom CSS.

Further thoughts:

• I think that suggested help text could be improved upon further by linking directly to the settings panels mentioned, and including a link to theme.json documentation for developers
• Maybe this should even have a Theme File Editor-style warning the first time it's opened.
• I could imagine a warning that appears if editors write CSS with simple block selectors.

[luminuu]

+1 for the suggested changes. Just today I found myself wanting to go to the additional CSS, not seeing it, getting frustrated and then remembering it was hidden in the menu.

I wouldn't mind if it went back to it's original spot below the Blocks link, but with additional text just like for the Blocks section to educate the user.

[t-hamano]

Thanks for the suggestion.

I remember the current implementation is intentional. There was a lot of discussion, but ultimately we decided to make this feature less prominent.

See:

• https://github.com/WordPress/gutenberg/pull/71537
• https://github.com/WordPress/gutenberg/pull/71550

cc @mtias @tyxla

[mrwweb]

@t-hamano Thanks for the response and context. I hadn't found those prior conversations. From what I'm reading, it looks like:

• Hiding Additional CSS causes a lot of user confusion (and people are very happy when it is more visible)
• Additional CSS is primarily hidden to prevent people from using it, and the many many many valid reasons for using it weren't mentioned in the discussion
• There isn't any communication/help text to teach people when it's the correct tool and when it's not

That's why I recommended making it more prominent but including help text or even a warning when people first use it. Again, thanks for all your work and that extra context. I think I'd still ask that the current location be reconsidered because:

Additional CSS is likely to also remain a core tool for any site owner that needs to go beyond the subset of CSS supported by the Site Editor.

[tyxla]

I remember the current implementation is intentional. There was a lot of discussion, but ultimately we decided to make this feature less prominent.

Yeah, I think this comment summarizes our rationale pretty well.

[mrwweb]

@tyxla Thanks for flagging that specific comment. I certainly agree that including information about custom block CSS would be good if making Additional CSS more visible.

I didn't explicitly mention per-block CSS but I would offer two observations from my experience with it:

• The "developer experience" with it is not great in theme.json or the Site Editor. The way the selectors are scoped to the block and the way the & works is confusing and doesn't seem to support things like selecting that block in the context of others (e.g. .wp-block-column .wp-block-cover) or easily selecting child elements of blocks (e.g. .wp-block-media-text__content), for instance.
• Many of the above CSS needs either don't work in the Block-specific CSS field, are confusing/difficult to use in that context, or are inappropriate in that field because of their context or purpose.

I agree that it's an important tool to use, but I still don't think it comes close to making Additional CSS unnecessary or obsolete.