When a block theme is active, add Site Editor link and notice to the Customizer UI

[ironprogrammer]

Primary Objectives

• Encourage users to utilize Site Editor for the best full site customization experience.
• Provide a link to the Site Editor.
• Keep presentation basic and consistent with existing Customizer design paradigm.

Secondary Objectives

• Teach and reinforce Site Editor use for users who may have previously relied on Customizer.
• Clarify that Customizer is not intended for use with block themes.

Context

1. User has installed WordPress 5.9+.
2. User has activated a block theme, such as "Twenty Twenty-Two".
3. User has navigated directly to Customizer via /wp-admin/customize.php (this link is not emitted in admin menus when a block theme is active).

Proposed Enhancement

To stay consistent with the existing layout and styling of Customizer, add a "warning" notice to the Customizer sidebar. The notice should encourage users to switch to Site Editor, which offers many more customization options, and is designed to work with the active theme.

In addition to the notice text, add a prominent button that links directly to Site Editor.

The copy used in the notice could touch on multiple objectives, but it may be best to keep it as simple and direct as possible. It may be surprising enough to users that Customizer is discouraged with block themes.

Please see attached layout comp for an example of placement, styling, and verbiage for this notice.

Props @matt @matveb @hellofromtonya @antonvlasenko

[ironprogrammer]

Screenshot of proposed Customizer block theme "warning" notice and link to Site Editor

[ironprogrammer]

I was thinking that for now, the "Tell me more" link could go to /wp-admin/about.php, which has good introductory content on what full-site editing is about.

[antonvlasenko]

Thank you, @ironprogrammer. I'm working on this task.

We must warn users that block themes are supposed to be edited with the Site Editor.

Trac ticket: https://core.trac.wordpress.org/ticket/54939

[antonvlasenko]

​PR is ready for code review.
This is how the current implementation looks.

@ironprogrammer /wp-admin/about.php Perhaps this page will change in the future. Thus we will have to change the link in the notification as well. I wonder if there is a separate page explaining what full-site editing is. I could only find ​this page, but I don't know if it is appropriate.

[ironprogrammer]

@antonvlasenko I think this ​FSE support article is geared well to end users who would stumble onto this notice. I LOVE the idea of providing easy access to more detailed topical support from the UI. A link to the help, and a button to switch to Editor view would provide good calls to action.

For the "help toggle" text on the Customizer, should we also update that text for additional clarity?

A possible edit could be (in bold):

The Customizer allows you to preview changes to your site before publishing them. You can navigate to different pages on your site within the preview. Edit shortcuts are shown for some editable elements. The Customizer is intended for use with non-block themes.

[antonvlasenko]

For the "help toggle" text on the Customizer, should we also update that text for additional clarity?

I've ​updated the text per your suggestion. I think It's a good idea. Thanks.

[Clorith]

I wonder if this should perhaps not be a 5.9.x ticket, but a future enhancement for the next major at this point, I have a few reasons for this thought process.

Introducing multiple new strings to a short-circuit minor release puts unnecessary pressure on translators.

Minors should (specifically for a rapid cycle release, as 5.9.1 appears to be), in my opinion, not be for enhancements, but for security and bugfixes with the most recent release. This is of course at the discretion of the release leads.

Given that this is aimed specifically at full site editing-enabled themes, if a user finds them selves in the Customizer at this point, it's because they're looking to make changes that is not supported within the FSE interface, throwing a notice in here to push them away may then lead to confusion, and a more circular navigation behavior where the user is thrown back and forth between interfaces.

[ironprogrammer]

Thanks, @Clorith. The intention with this warning is as you stated: to drive FSE theme users over to the new Editor, where their changes will actually apply. Perhaps the text could be more explict, like, "The active theme does not support the Customizer. Please use the new Editor instead: <button>." Suggestions to make it clearer would be greatly appreciated, regardless of when this releases.

Since Customizer is still accessible when an FSE theme is active, the key concern is allowing users to think that the Customizer will continue to function for them would also lead to confusion (e.g. "What happened to all the menu options that were here? Where did the background image setting go?") Hence, the proposed warning.

We absolutely want to avoid any implication that users can shift between customizing tools in a circular manner. FSE themes are new, so hopefully this warning would curtail some misunderstanding as users try out FSE. The wording of the notice needs to be clear on that.

Timing
Regarding timing, I agree that minors should generally avoid enhancements, especially considering this is a corner case where knowledge of, or a shortcut to Customizer is required. However, as adoption of 5.9 and FSE continues to grow, right now is when this nudge to stick to the new Editor could matter most to affected users.

Feedback from release leads and translators is certainly called for. We're also awaiting design feedback, so we'll see what (and when) we can pull this together 😄

If you have any thoughts on the text (or presentation) of the warning, please let us know.

[audrasjb]

While we indeed try to avoid introducing string changes in a minor release, this one makes sense to me since 5.9.1 is about to fix a bunch of small issues related to the site editor. This would need a quick heads up to #polyglots slack channel though, so translators are aware that we're going to introduce some string changes :)

Otherwise, the proposed UI changes looks good to me.

[psmits1567]

How many translation lines are we talking about?
Looking at the screenshots, it appears to me that it are not numerous new lines
So that would not be a reason to not add it into 5.9.1

[tobifjellner]

So here are a couple of comments from "Polyglots" point of view.
Previously (up until roughly one year ago) we were quite nervous about new strings, since the generation of a language package and a localized WordPress installation package had a threshold of 100% strings translated (and approved).
In other words: Any one single string that got introduced (or changed) late in the process might cause several languages to "not getting released".

Now, however, we have lowered these threshold values significantly: For the main project it's now 90% of the strings, and 75% for the Admin sub project (and 0% for Continents & Cities; and Network Admin).

Of course, as much as possible, we want releases to be fully translated, especially strings that "normal users" may see.
But in a comparison between "need for information and clarity" on the one hand, and problems with releasing localized versions on the other, we can now clearly say that language and clarity improvements are always welcome, even late in a release cycle and in minor releases.

The downside, of course, is that if a string is not yet translated, the original string will be used, which may feel strange for some users.

[antonvlasenko]

I agree with @audrasjb and @ironprogrammer.
In my opinion, the benefits of letting users know that the Customizer is not suitable for editing block themes outweigh the inconvenience of having to translate two new sentences.

@psmits1567
There are 2 new lines to translate:

1. ​https://github.com/anton-vlasenko/wordpress-develop/blob/add/customizer-notice-for-block-themes/src/wp-admin/customize.php#L238 (only the very last sentence of this line has to be translated; the text before it has already been translated).
2. ​https://github.com/anton-vlasenko/wordpress-develop/blob/add/customizer-notice-for-block-themes/src/wp-includes/script-loader.php#L1225

[costdev]

I'd suggest removing "new" from the string, to save ourselves a future update by making the string more futureproof.

[Clorith]

Some thoughts on the wording to be used in a notice like this, regardless of when it is introduced.

We need to account for scenarios where the Customizer is actually in use, for example WooCommerce is a major player here that uses it actively (to use a big example), and we want to avoid confusing the users in where they need to go to make changes. There's also a use case where authors will direct users to it to make style changes with the custom CSS fields.

You are currently using a block-based theme, to make visual changes to your site not related to a plugin, please visit the Site Editor.

Keeping the button-link to navigate over to the Site Editor then, and maybe the "Tell me more" could also be a button-link, as it's technically an action?

(definitely needs someone to use better words than mine, but hopefully the gist of what I'd love to see the wording come across as helps)

[antonvlasenko]

I'd suggest removing "new" from the string, to save ourselves a future update by making the string more futureproof.

Good spot, @costdev ! Fixed in ​https://github.com/WordPress/wordpress-develop/pull/2237/commits/2fd9837872968425d85d008c405727c6680bf2d1

I’ve reworked the UI. Now it looks like that:
1.

2.

maybe the "Tell me more" could also be a button-link, as it's technically an action?

@Clorith I’m sorry, but I don’t understand the advantage of using button.button-link.
It looks like a regular <a /> tag to me, although it's a <button />.

Also, there could be issues with redirecting users to a different domain using JavaScript.
So I would prefer to use a regular link for Tell me more text (as shown on the first screenshot).

Regarding choosing the text for the notification message: it would be great if this PR could get some design feedback.
I like the first variant of the text that @ironprogrammer proposed.

I believe w.org links are supposed to be translated so that locales can link to a translated version of the article if necessary.

[Clorith]

@antonvlasenko Ahh, I meant other way around (so a link styled as a button since it's a direct action that would take you in the "opposite" direction from the one that takes you to the editor), but don't worry too much about it as I was just thinking out loud, that would arise from whatever the final copy-write ends up being :)

[ironprogrammer]

Thank you, everyone, for your input thus far!

In light of the mentioned scenarios where an FSE theme user may need (or be instructed) to use the Customizer, and various other feedback generously supplied, I'd like to propose the following adjustments:

• Change notice style to "info" (blue), rather than "warning" (yellow). This will help minimize implications that the user is doing anything wrong. More ℹ️ and less ⚠️!
• Update wording to focus on "what we know" -- that is, indicate that the active theme supports FSE, but make no other assumptions.
• Simplify wording of the button. We might also consider the simpler, "Use Editor" to be consistent with the Appearance > Editor admin menu option.
• Remove the expando tooltip "(?)" text update (commit cbf9a8e8). Let its existing content focus on Customizer, and limit strings changes.

Our "refreshed" intent for these updates is to avoid making users feel like they're in the wrong place, and instead highlight the theme's FSE capability. This seems like a good compromise between training users to begin using the Site Editor for FSE-capable themes, while not discouraging legitimate work in the Customizer.

Here is an updated comp reflecting what this might look like:

With regards to @Clorith's latest note, other WordPress links to help content (particularly offsite content) are generally styled as text links. The decision to grant visual dominance to the Editor link was to enforce the action/habit we're trying to encourage with this notice.

But like you said, this will ultimately depend on design and copy feedback 😅

[ironprogrammer]

We would like to request copy review for this update. The context and intention for this notice can be summarized as follows:

If an FSE-capable block theme is enabled, and a user has accessed the "legacy" Customizer, to inform or remind them that the active theme supports FSE and can be customized with the Site Editor.

The current proposed copy (the blue notice callout in the screenshot above):

Hurray! Your theme supports Full Site Editing with blocks. Tell me more.
<button>Use Site Editor</button>

[audrasjb]

Given this ticket still needs copy review and 5.9.1 RC1 is tomorrow, let's move it to the next point release.

[audrasjb]

Moving to milestone 5.9.3 since we're about to release 5.9.2.

[audrasjb]

As per today's bug scrub, I'maAssigning @marybaum for copy review.

[webcommsat]

Passed this for copy review from @marybaum.
Keeping this message nice and simply for users new to blocks in FSE is the key. I support the text by @ironprogrammer and the option for the user to find out more.

Removing copy-review tag to move this ticket on.

[audrasjb]

Thank you for confirming.
@antonvlasenko are you able to update your PR with the above wording please?

Adding needs-refresh workflow keyword.

[antonvlasenko]

Removing copy-review tag to move this ticket on.

Thank you.
@audrasjb Thanks for the ping.
Yes, I will let you know once it's ready.

[antonvlasenko]

I've updated the wording.
cc: @audrasjb

[audrasjb]

Alright I tested the PR using a random Login Page Customizer plugin (which uses the Customizer) and it works as expected.

[audrasjb]

In 53024:

Customizer: When a block theme is active, add an information about Site Editor in the Customizer.

This change adds an information notice to the customizer when a block theme is active and the customizer is also available (for example when a plugin activates it), to encourage people to use the Site Editor for the best full site customization experience.

Props ironprogrammer, antonvlasenko, Clorith, audrasjb, psmits1567, tobifjellner, costdev, webcommsat.
Fixes #54939.

[audrasjb]

Reopening for backport consideration.

[audrasjb]

Hmm.

I committed the proposed patch, but I can see at least 2 accessibility issues.

• Links that open a new windows should be announced
• With $switch_to_site_editor_label, the same link is used for both the button text and its aria-label

I'm unsure about the best solution: fix the issues directly or revert this commit before 5.9.3 and move the issue to the next major.

Thoughts?

[antonvlasenko]

@audrasjb

Links that open a new windows should be announced

I can create another PR that will remove the target="_blank" attribute.
It seemed logical to me to open this page in a new window.
Users might want to continue editing their theme after learning about Full Site Editing. If the the target="_blank" attribute is not used, they would need to go to the WordPress admin section again to edit their theme.
I didn't know such links had to be announced.

With $switch_to_site_editor_label, the same link is used for both the button text and its aria-label

$switch_to_site_editor_label contains text that says Use Site Editor.
Is there any issue with having this exact text in 2 different places?

[audrasjb]

• Yes opening a new window needs to be announced at least in a screen reader text.
• Text duplication needs to be removed to avoid duplicate read on screen reader text tools.

I'm going to add a PR to fix those issues :)

[joedolson]

I'd strongly recommend removing the target="_blank" Forcing a link to open in a new tab means that the user doesn't have the option to open in their current tab, and we generally prefer not to take choice away from the user unless there's a clear and present risk of data loss.

Re: the duplicated text: there's no point in using an aria-label at all if the text is already present in the button, and using the aria-label can create problems with automatic translation tools, as well as potentially making maintenance harder (if the aria-label was changed and the visible label wasn't, for example.)

[audrasjb]

Also, the translator texts are wrong, the incoming PR will fix a small i18n issue :)

Trac ticket: https://core.trac.wordpress.org/ticket/54939

[audrasjb]

In 53025:

Customizer: Accessibility fixes following [53024].

This changeset fixes a few issues spotted after [53024].

• Remove target blank on HelpHub link
• Remove duplicate information in aria-label
• Small i18n fixes

Follow-up to [53024].

Props joedolson, audrasjb, pbiron.
Fixes #54939.

Committed in https://core.trac.wordpress.org/changeset/53025

[audrasjb]

Reopening for proper backport.

[audrasjb]

In 53026:

Customizer: When a block theme is active, add an information about Site Editor in the Customizer.

This change adds an information notice to the customizer when a block theme is active and the customizer is also available (for example when a plugin activates it), to encourage people to use the Site Editor for the best full site customization experience.

Props ironprogrammer, antonvlasenko, Clorith, audrasjb, psmits1567, tobifjellner, costdev, webcommsat, joedolson, pbiron.
Merges [53024] and [53025] to the 5.9 branch.
Fixes #54939.

Closed in favor of ​https://github.com/WordPress/wordpress-develop/pull/2477.