Display style variations for block themes in the theme directory

[poena]

From Gutenberg version 12.5 and presumably WordPress 6.0, themes built for full site editing can have style variations by adding additional .json files.

It would be a nice feature to show screenshots of or some other type of preview of the style variations in the theme directory.

Also see
​https://github.com/WordPress/gutenberg/pull/35619
​https://developer.wordpress.org/block-editor/how-to-guides/themes/create-block-theme/#global-styles-presets

[dufresnesteven]

#6453 was marked as a duplicate.

[dufresnesteven]

I have some working code that adds style variations to the theme page, similar to how we show patterns. I don't think its the best experience yet, I think there's plenty more to do, but I do think it's far enough to merit discussions and consider whether it's good enough to launch and iterate:

Screenshots

See Image Added above
Watch Demo: ​https://d.pr/i/X4yxV2

How it works

• It uses wp-themes.com and applies the style variation based on a query string (IE: ​https://wp-themes.com/twentytwentytwo?style_variation=blue)
• Theme Directory leverages image snapshots and displays a snapshot of the theme style variation
• When a user clicks on the variation, we load the variation in the theme preview

Discussion/Improvements

Preview Tile

• Same with pattern previews, it's not clear that you can click on the preview to open the Theme preview. We should add more affordance.
• It uses a screen shot of the default homepage, for some themes that looks good, for others, not so much
• I considered using the same variation preview as the one found in the site editor but the control is not exported and therefore we would need to rebuild it. Seems out of scope.... for now.

Customizer

• Theres no way to change variations in the customizer (same for patterns)
• We could add a visual indication in the customizer sidebar letting the users know that they are viewing a style variation.

Although these limitations exist and improvements could be made, I personally think it's good enough to launch the feature as a beta and make the necessary updates in quick iterations.

I'm hoping to agree on the initial feature set as soon as possible. Please share with anyone you think would be interested :). Ultimately with a growing desire to redesign .org pages & directories, I'm hoping we can agree on the smallest amount of work that will have the greatest impact.

[dufresnesteven]

Example

[Joen]

Nice to see work moving forward! Surfacing style variations in the theme directory is pretty crucial for block themes, as it's a major aspect that isn't sufficiently surfaced by the thumbnail alone.

I would love for the design group to be able to provide some designs here, that shows style variations closer to the context of the thumbnail itself, and perhaps used the style card from Global Styles to flip through a series of thumbnails. That could allow each variation to have as much weight as the default thumbnail itself, without making already long theme pages longer still.

Style card from Global Styles:

On another note, invoking the customizer on the thumbnail preview doesn't seem appropriate, since the customizer is not used to for style variations in the first place. If we do need to link to a separate demo site, we could just link directly to the URL. But this may be moot if we can flip through generated style thumbnails instead.

A challenge to consider especially is when a theme (such as TwentyTwenty-Three) comes with a whole slew of variations. One theme might even provide hundreds (which would not be a good practice and should probably be discouraged) — but the right amount is still to be found, and the interface should probably scale in that direction. I'll see if I can't get a design shared here soon!

[Joen]

Thumbnail and style variations

[Joen]

I just added https://meta.trac.wordpress.org/timeline?from=2022-09-22T12%3A32%3A09Z&precision=second as an example of a thumbnail that could be switched out per style variations. Would something like that work?

[dufresnesteven]

Replying to Joen:

I just added https://meta.trac.wordpress.org/timeline?from=2022-09-22T12%3A32%3A09Z&precision=second as an example of a thumbnail that could be switched out per style variations. Would something like that work?

I'm assuming you meant to link the image above your comment.

I like the idea of not needing the preview window. The image attachment only shows a small portion of the page so to make sure I understand correctly, the style variations show up below the main theme thumbnail, and clicking on the style variation changes the thumbnail to a preview of the site with the style variation applied. Is that correct?

If I have that right, the only drawback is how different the theme thumbnail can be from the actual site. This is the result of how a theme is built and how wp-themes.com configures themes (See references for ticket about better preview data). It could be a confusing experience to go from a nice-looking thumbnail to a sparse-looking blog layout (See examples below). With that being said, that problem will exist regardless of the approach we take and I would say that experience is probably the exception and not the rule for block themes. We could lessen the "surprise" by instead of using the style variation preview square with the colors and the "A" but instead, use the preview snapshot. I think it could work and would require the least amount of work to get this out the door but I'm not opposed to implementing the "A" color square to keep it in sync with the site editor experience.

Examples:
Look at the theme thumbnail, click "Preview". Notice how they differ.

​https://wordpress.org/themes/taina/
​https://wordpress.org/themes/categorical/
​https://wordpress.org/themes/hello-elementor/ (no style variations, but same effect)

References:
https://meta.trac.wordpress.org/ticket/30

[poena]

If it is a problem that the theme page becomes too large, I would much rather have tabs than a slider, even if that means that the styles are hidden from the first glance.

[poena]

Theme developers are known for submitting screenshots that doesn't look anything at all like the installed theme, that is a separate related problem that can only be solved by .org providing the screenshot.

[dufresnesteven]

Another question would be, if I apply a style variation to the thumbnail area and then click the "preview" button, would I be previewing the default style or the applied style variation? I guess I would expect to see the style variation but, I can see how there is a disconnect between the interactions with the thumbnail and the "preview" button.

[dufresnesteven]

I roughed in the slider experience using the theme previews to see how it feels.

Demo:
​https://d.pr/i/iOpS6E

Thoughts:

• I personally don't mind the slider since style variations don't change the theme so dramatically that I need to see them all for me to make my mind up on the theme. With that being said, there is something exciting about seeing a lot at once.
• I think the large thumbnail image should get an overlay state that also prompts opening the theme in preview mode since it now draws in a lot of user attention.
• Again, I kind of like the actual preview of the theme as opposed to the "A" color square but could be convinced otherwise. I'll defer to whatever the design team suggests.
• We'll need to figure out whether to inject the original thumbnail into the slider to represent the default state so users can get back to the original thumbnail, or give the style variations a toggle on/off behavior.
• One of the most requested features is to allow themes to upload multiple thumbnail images.
  • If/When we support that, this experience probably won't work well as-is.
• If we don't like the slider, a drawer-type experience could work.

[Joen]

Style cards in Global Styles

[Joen]

Fast work, and the demo looks great Steve, thank you. I think that demo gets us very close: a row of style variation buttons which when clicked preview the variation in the area above. It’s especially useful that those previews are generated, per Carolina’s commment on theme developers often submitting wildly varying screenshots otherwise.

However I do think it’s important that we seek out a way to generate a style card for the row of buttons, as it’s an important branding element for global styles, and it’s arguably more legible (showing spot colors and typography) than a squished thumbnail. Mostly, it’s about setting expectations for how it already looks inside the editor, that this is the same interface, just in the directory. I shared a GIF above showing the style cards.

If extracting those properties and generating the style card as it’s done in global styles turns into a technical challenge, it’s probably fine to go with a small thumbnail for now. However we should then separately ticket an effort to follow up and add the style cards later on. What do you think?

[dufresnesteven]

I agree with you, the global style cards are important.

I found some time this week to move this along. I'm pretty happy with how it's working, it's not ready for a critical review, there are spacing and some UX quirks that need improving but I'm hoping that early next week I'll add a patch or find a way to preview that to a wider audience.

Current State:
​https://d.pr/i/d6zvRZ

Must Do:

• Improve the "back" view of the card layout
  • Some of the fonts appear really thin when previewing the card "back". Hard to read.
  • Padding/Layout needs improvements
• Improve the initial page loading state of slider (it jumps downwards)
• Add active/focus state to global card style (when we are viewing one)
• Add overlay on large thumbnail that prompts user to preview theme in customizer
• Correct card w/h aspect ratio

Should Do:

• Improve the loading state for screenshots
• Add "srcset" to provide better resolutions

[Joen]

Fast work, wow! For what it's worth, I think we can do without the hover state on the card. I think the hover state in the block editor itself may evolve in the future as well, so it's probably fine to just consider the main card as a static portrayal. We can always revisit if need be.

Let me know if/when you can use more specific feedback. Thanks for working on this 🙏

[dufresnesteven]

I added a patch attachment:6059.diff​ which along with the pull request referenced below will add style variations to theme views. Once the pull request is complete, I will deploy the diff which will add the functionality and can be triggered via a query string parameter so we can test in production and iterate on feedback before the official rollout of the feature.

On page load, the control does all-of-a-sudden push content down once the ajax request completes. We currently don't have a way on page load to determine if there are style variations in the theme. I have asked in the slack #themereview channel if there will be a tag added for style variations. If we had a tag, we could display the control while loading the variations and avoid the jump. The alternative is to add some metadata on theme upload which will work, but it's currently very cumbersome to add a new property to the theme API and backfill all the data. The tag approach would put the onus on the theme developer, but we would probably have style variations in themes where the developer has not added the tag. That's obviously not ideal.

Regardless, I will push to find a solution here but it's currently not in place. I don't think it should block some live testing.

References:
Component Pull Request: ​https://github.com/WordPress/wporg-mu-plugins/pull/289
Slack msg about style-variation tag: ​https://wordpress.slack.com/archives/C02RP4Y3K/p1664949151352129

[dufresnesteven]

Here's a little context around the pushing down of content:

Demo: ​https://d.pr/i/0Unajt

[Joen]

Downwards push or not, this is looking like a very solid first iteration. Very nice!

Almost certainly a separate discussion/effort, but it would be nice to refine the demo content that gets loaded on clicking each style variation. Still, the fact that it shows up in the same thumbnail space feels great.

[dufresnesteven]

I have deployed this feature in https://meta.trac.wordpress.org/changeset/12106.

It's currently behind a feature flag so we can iron out a few things before a meta post that shares it with the community.

Here are some examples:
​https://wordpress.org/themes/twentytwentytwo/?beta=style_variations
​https://wordpress.org/themes/raft/?beta=style_variations
​https://wordpress.org/themes/beaumont/?beta=style_variations
​https://wordpress.org/themes/aeonium/?beta=style_variations
​https://wordpress.org/themes/poe/?beta=style_variations

In order to turn on the feature, add ?beta=style_variations to the URL. The URL gets updated when you browse themes so you'll need to re-add it for each theme page and reload. If nothing loads, there are most likely no style variations for that theme—your best chance of finding them is in the "Block theme" category.

There are still a few things I'm not sure about:

• Do we need a state on the global styles card that denotes it's the one being previewed?
• Should we append the name of the style variation somewhere? ... they are kind of neat.
  • Maybe overlayed on the thumbnail?
• You can't get back to the original thumbnail, is that a problem?

Feedback and bugs can be added here, I'll get to them. Thanks!!!

[Joen]

Excellent work, this is a substantial step forward. If it launches as is, it will showcase the diversity and community contributions to TwentyTwentyThree in a substantially better way, and it is a strength for all block themes. Thank you!

Do we need a state on the global styles card that denotes it's the one being previewed?

Yes, good catch. Can you just show the border in black? Focus remains the thicker blue, but the resting 1px goes from light gray to black which should be sufficient contrast to show an active state. See also the gif I'll add after this comment for what the block editor does.

Should we append the name of the style variation somewhere? ... they are kind of neat.
Maybe overlayed on the thumbnail?

After this comment I'll upload the most recent trunk version of how variations are shown in the block editor, which changed just recently to show the name on hover and select. I think we can probably mimic this here as well, what do you think?

You can't get back to the original thumbnail, is that a problem?

Can you show the thumbnail when you click the default style variation card? Otherwise, no strong opinion.

---

In the category of nitpicks — not blockers, but good to address at some point:

• Instead of "Loading..." can we show a spinner? Whichever spinner is used across the site at this point, but eventually can update that spinner across the site with the simple half-circle used in the block editor.
• The metrics of the style card are slightly off. I've attached a comparison card between the block editor and what's shipping here, it's little things: 118x74px dimensions, 18px gap between text and dots, 30px font size, 8px gap between the two dots. The card in the block editor is actually scaled down from original metrics so the numbers are a bit fuzzy and it doesn't have to be perfect, but we can probably get a bit closer with a tiny bit of massaging.

Hope that was useful!

[Joen]

Style variations shown on card hover

[Joen]

A few metric differences in the style cards

[ben.greeley]

This is great, Steve! Something that was a little confusing to me was when I went to ​https://wordpress.org/themes/twentytwentytwo/?beta=style_variations I saw the arrows in the 'Style variations' section was disabled, but it wasn't clear to me what they would do unless I was on a theme that actually had the pagination such as ​https://wordpress.org/themes/raft/?beta=style_variations

What do you think about hiding those arrows rather than disabling them if there isn't anything to paginate?

[bph]

This is so cool! I truly love it, especially the switch in the screenshot that goes along with clicking on the variation card! Very slick. The growing interactivity on the Theme directory makes it great fun to browse through the themes, and spend some more time on it, fascinated by all the creativity.

@bengreeley beat me to it, mentioning the grayed-out arrows on a theme that doesn't have enough style variations to fill up the space and make the arrows necessary.
I also see a horizontal scroll bar when looking the Twenty-Twenty-Two style variations without anywhere to go. All grayed-out. Could those be removed?

Fabulous first iteration!

[bph]

Screenshot Twenty-Twenty-Two

[ryelle]

Moving over some comments from ​a related github discussion where I asked about the keyboard/screen reader interactions for these cards. Currently they are links that only update the image preview.

What would you suggest the caption be for something that changes the preview image? It's kind of weird because it's a visual change so users using screen readers don't see the change...

There are sighted users who use screen readers - people with low vision, or who use it to help with attention/focus, so I wouldn't assume they won't see the change.

You could use speak() to announce that something changed? Maybe move focus over to the preview button? That sounds unexpected though 🤔

Also, in this case, would it be more ideal if it weren't a link since it doesn't navigate anymore?

Yeah, I think this is a case for a button… but honestly, I'd bring this up in the #accessibility channel on Making WP slack, see if the team there has any recommendations, because I don't know what would be the expected interaction here.

[dufresnesteven]

I pushed some recent changes that did the following:

• Hide the scrollbar (via CSS, supports most modern browsers)
• Add a black border to the active card
• Switch the thumbnail back when users select the "default" style.
• Update the card styles to match designs better
• Hide navigation arrows if users can go left & right (less cards than container width)

Remaining tasks:

• Improve accessibility
• Improve the loading state of screenshots

Discussion:
Showing style variations, new card hover state

@Joen

Should we append the name of the style variation somewhere? ... they are kind of neat.
Maybe overlayed on the thumbnail?

After this comment I'll upload the most recent trunk version of how variations are shown in the block editor, which changed just recently to show the name on hover and select. I think we can probably mimic this here as well, what do you think?

We can mimic the 2 states, but since we use screenshots, we won't be able to do the animation in the GIF you added. I think it may be a better long-term strategy to get @wordpress/edit-site to export the components. Otherwise, we'll probably need to update this code to match perpetually. I would vote that we leave it as-is, just the one state, no hover. Since we plan to update the directory, we could re-consider then.

[Joen]

Nice, fast work!

We can mimic the 2 states, but since we use screenshots, we won't be able to do the animation in the GIF you added.

This feels a good start. I think we can do without the name, otherwise we can, at least in the interim, do something around the "Style variations" subheading, perhaps it could say "Style variations: Default", "Style variations: Canary", etc. — not an action item, just thinking out loud.

I think it may be a better long-term strategy to get @wordpress/edit-site to export the components. Otherwise, we'll probably need to update this code to match perpetually

Yep, that sounds right. I could see this card being used in a slew of places. Would you mind opening an issue about that? ​https://github.com/WordPress/gutenberg/issues

See: https://meta.trac.wordpress.org/ticket/6059#comment:18

This PR adds a CSS loader to the ScreenShot preview block. Since we are still choosing to keep the theme page light and exclude extra @wordpress dependencies, I chose to attempt to recreate the @wordpress/components/Spinner component.

When the theme directory undergoes _blockification_, we should lean towards using more @wordpress controls, but until then it think this is a fair approach.

## Screenshots

### Comparing of the two loaders
Left: This implementation
Right: @wordpress/components/spinner

The circle outline width is not reproducible with CSS. It can either be thicker or thinner than the <svg/>.

[dufresnesteven]

Yep, that sounds right. I could see this card being used in a slew of places. Would you mind opening an issue about that? ​https://github.com/WordPress/gutenberg/issues

Logged: ​https://github.com/WordPress/gutenberg/issues/44886

[dufresnesteven]

I pushed some updates to loaders and waiting on some feedback on accessibility (​https://wordpress.slack.com/archives/C02RP4X03/p1665538927860869).

With the support of everyone here, I would like to share this work with the community via a meta post after an accessibility feedback iteration. I'm thinking that we can just remove the beta=style_variations flag and show it as default. I would prefer more people see the feature as soon as possible now and it's relatively low risk.

[joyously]

It seems biased to block themes. My 4 year old theme has style variations built-in, but it can't participate even though the Customizer could do this way back then.
I think the Theme Previewer would benefit from showing the Customizer, so the user could really see the theme options for the majority of themes.

[dufresnesteven]

In 12137:

wporg-themes: Remove style variation feature flag.

See #6059.

[dufresnesteven]

This has been turned on for all:

​https://make.wordpress.org/meta/2022/10/20/displaying-style-variations-for-supporting-themes/

[ryelle]

@dufresnesteven Is there anything to follow up on for this ticket, or can it be closed?

[dufresnesteven]

I think we can close it as the feature seems to cover the original request.

We can reopen more specific tickets for any other changes we want.