Revisiting / contextualising pattern categories, and default inclusions

[jameskoster]

The Patterns Directory has grown enormously over time, and now could be a good time to consider how patterns are organised (categories), and which patterns are included in those categories by default.

Based on conversation in this issue, here's a proposal for new categories and descriptions.

Patterns

• Call to Action

  Sections whose purpose is to trigger a specific action.
• Team

  A variety of designs to display your team members.
• Testimonials

  Share reviews and feedback about your brand/business.
• Services

  Briefly describe what your business does and how you can help.
• Contact

  Display your contact information.
• About
  
Introduce yourself.
• Portfolio
  
Showcase your latest work.
• Gallery
  
Different layouts for displaying images.
• Media

  Different layouts containing video or audio.
• Posts
  
Display your latest posts in lists, grids or other layouts.
• Products
  
Display your store’s products in lists, grids or other layouts.

Previously a part of the effort, see [details](https://github.com//issues/44501#issuecomment-1397217633)

Site building patterns (Site editor only)

• Footers
  
A variety of footer designs displaying information and site navigation.
• Headers
  
A variety of header designs displaying your site title and navigation.
• Post Content
  
Your post and page content.
• Comments
  Different ways of displaying your post or page's comments.
• Pagination
  
A variety of designs for navigating your posts.
• Comment Pagination

  
A variety of designs to browse through a big list of comments.
• Archive Headings
  
A variety of designs for your archive heading.
• 404
  
A variety of designs for when a page cannot be found.
• Search
  
Different layouts to display search results.

Note: As part of the renaming/creation of new categories, @WordPress/gutenberg-design is happy to assist with the creation/retirement/refreshing of existing patterns, including which categorization. PR #45548 may also provide a jump start.

---

See also #44611 for details on how these categories can be synced up with the pattern directory. For example, "Featured" would contain the patterns from the WordPress.org user:

---

Issue updated Nov 8.

Initial proposal

These are the pattern categories we find in all iterations of the Editor.

• “Featured” seems a bit arbitrary. It's not clear to me what constitutes a Featured pattern.
• “Buttons” – iirc this is a legacy category from before the Buttons block / Row container. There are more convenient ways to insert buttons now.
• “Columns” is a broad category covering any pattern that includes the Columns block. With the expansion of layout tools at users disposal I'm not sure how useful this category is.
• “Gallery” includes image compositions. I only see three patterns here which is very underwhelming. I wonder if a Media category that includes Video and Audio patterns might be better? Or should those also feature at the top level?
• “Footers” and “Headers” should be reserved for template editing only.
• “Text” like Columns is probably too broad to be useful. The vast majority of patterns include text in some form.
• “Query” is patterns for query loops. It to be diversified into post types and have a friendlier name. Improving intuition of the 'Query' pattern category #43427

[beafialho]

Oh, and forgot to mention wireframe patterns. I took the liberty to create a "Wireframe" category as an effort to add those patterns to the directory. We could later subfilter them by use case using tags so that users can find them more effectively.

[beafialho]

“Featured” seems a bit arbitrary. It's not clear to me what constitutes a Featured pattern.

Also coming back to this, I think this could still continue as a category with curated patterns.

[jameskoster]

I think "Wireframe" makes more sense as a category than a tag, mostly because it makes sense that it shows up next to the other categories in the directory

Okay, I reckon this can work fine if patterns are assignable to multiple categories.

It would be good to get some more design feedback on the categories we've discussed cc @WordPress/gutenberg-design.

In terms of how to proceed, do we need to update wp.org and Gutenberg at the same time, or does one inform the other? I'm really not sure how this all works.

[ryelle]

do we need to update wp.org and Gutenberg at the same time, or does one inform the other?

The list in Gutenberg/core is separate from the list on w.org/patterns. We've had to sync them back and forth when something changes. Should it only be one list? The Pattern Directory does provide the list of categories as an API.

There is also this (old) issue WordPress/pattern-directory#190 for updating the categories in the pattern directory — if you're aiming for both lists to be the same, should that be closed in favor of this issue?

Are you only adding new categories, or also removing (or renaming) old ones?

[jameskoster]

Should it only be one list?

In terms of broad UX the categories would ideally always be in sync, so I would tentatively say yes, especially if it makes maintenance more straight-forward. But there are likely technical/performance issues I'm not accounting for. I suppose the answer to that will dictate whether we close WordPress/pattern-directory#190 or not.

Are you only adding new categories, or also removing (or renaming) old ones?

Mostly adding new categories, which I appreciate means that many patterns will need to be re-assigned. Some will be renamed (Query), and a couple will stay the same (Headers / Footers).

One other point to consider here: since some categories should only be visible when editing templates, does that need to be reflected somehow in the category structure? IE have two top-level categories "Template" and "Content", or is there a better way to do that?

[ryelle]

In terms of broad UX the categories would ideally always be in sync, so I would tentatively say yes, especially if it makes maintenance more straight-forward. But there are likely technical/performance issues I'm not accounting for.

Possibly, but that's what the PR process is for :) Right now, since it's not synced, changing names on the Pattern Directory will negatively affect existing sites (even up-to-date ones that aren't using Gutenberg), since the new categories won't exist yet - those patterns will all be uncategorized. I've added an issue to the pattern directory to think about that WordPress/pattern-directory#532

One other point to consider here: since some categories should only be visible when editing templates, does that need to be reflected somehow in the category structure? IE have two top-level categories "Template" and "Content", or is there a better way to do that?

If this is something we should support in the Pattern Directory, can you open an issue and describe it? (We also already have this issue, which is about sorting, but nothing for how to identify a pattern as site-building vs content).

[jameskoster]

can you open an issue and describe it?

I opened WordPress/pattern-directory#534 which hopefully covers the needs here.

[jameskoster]

In WordPress/pattern-directory#534 @ryelle suggested that the Pattern Directory would follow however Gutenberg decides to mark site building patterns.

Perhaps $category_properties could entertain a site_building => true (or similar) value in register_block_pattern_category()?

[jasmussen]

This issue has been updated November 8th with the list of categories we've decided on, so it no longer needs any design feedback, and PR #44501 might provide a jump start.

[mikachan]

This issue has been updated November 8th with the list of categories we've decided on, so it no longer needs any design feedback, and PR #44501 might provide a jump start.

Did you mean this PR #46144? I'm wondering what other pattern categories need to be added, or what needs to be done next here.

[getdave]

If we want certain patterns to appear in particular editor instances (e.g. the Site Editor exclusively) then we're going to need to add some kind of annotation to the categories to indicate where it should be included.

Here is a naive implementation

#47275

[annezazu]

I'm wondering what other pattern categories need to be added, or what needs to be done next here.

From what I understand, what remains is what was shared here by @ntsekouras but perhaps I'm missing some follow up. Is anything else required? Does this follow up PR cover everything #47270 ?

Tied to this, we need to ensure featured patterns are visible in both the Inserter and Pattern Directory: WordPress/pattern-directory#542 (comment) Right now, I can only see a handful of patterns in the Featured section for GB 15.0.

Otherwise, afaik, we are not moving forward with the "site building" category split so that can be removed cc @jasmussen for confirmation.

[mikachan]

Thanks @annezazu, I'm hoping #47270 will cover everything (although the Banner category may need to be reintroduced there).

We did start looking at splitting the patterns into editor-specific categories, so we'll stop working on this if it's no longer needed.

[ntsekouras]

👋 I don't think we should land @getdave 's PR, because it actually kind of reverts the addition of them here: #46144.

In that PR we added some migration of pattern categories and we can't remove them(until for now) because this is something that should be done in sync with Pattern Directory.

'buttons' => 'call-to-action',
'columns' => 'text',
'query'   => 'posts',

If we remove them entirely, patterns fetched from PD with that categories, would fall into the uncategorized panel.

Having said that, I think what is left for this issue is this comment

I noticed you removed all the site building categories. I think Post Content, Pagination, Comments, Comment Pagination, and Archive Headings can remain with the caveat that they only appear when you're editing a compatible template.

Yeah, this can be handled in a follow up and is more tied to @jorgefilipecosta 's work to show patterns based on a template, which also involves an API addition there.

What this means is, we need a new API for differentiating patterns and/or patterns categories between editors(post and site) and after that adding whatever pattern categories needed for site editor/template building.

[getdave]

we need a new API for differentiating patterns and/or patterns categories between editors(post and site)

Just FYI we had a brief look at that in #47275. Don't take that as a PR that is ready to merge. It's just a PoC which more knowledgable folk can take forward if necessary.

[mikachan]

Thanks for the extra context, @ntsekouras, that's really helpful. So does that mean the current state of the categories is correct, and no further changes are needed there? I'll close this PR if so.

Also, @annezazu mentioned above that we may not need the category split above:

Otherwise, afaik, we are not moving forward with the "site building" category split so that can be removed cc @jasmussen for confirmation.

However, from your comment, it sounds like we are going ahead with it. For what it's worth, the category split does sound useful for users inserting patterns. If so, I'll continue picking up the work started in #47275.

[jasmussen]

For what it's worth, the category split does sound useful for users inserting patterns.

We can always revisit. Patterns and the directory are in a suboptimal place at this point, and small steps forward will make a big impact, and don't preclude furthert steps in the future.

[mikachan]

I've closed #47270 as it looks like this was reverting recent category changes and causing additional confusion. However, we noticed when working on this that there were a few pattern categories that didn't have any patterns assigned:

• Buttons
• Columns
• Query (maybe these have been assigned to Posts?)
• Team
• Testimonials
• Services
• Contact
• About
• Portfolio
• Media

These are the numbers of patterns assigned to the remaining categories:

• Banner: 6
• Featured: 15
• Footer: 11
• Posts: 6
• Gallery: 3
• Header: 17
• Text: 11
• Call to Action: 3

I just wanted to highlight this and confirm whether there are plans to add more patterns to the first set of categories. @jasmussen, hoping you might have more insight here!

[jasmussen]

Thanks for the ping. I'd love insights by @annezazu on this as well, she's been closer to the metal on recent developments here.

[annezazu]

However, we noticed when working on this that there were a few pattern categories that didn't have any patterns assigned:

For Query, those were renamed to Posts! Columns were merged into Text. The other categories all fall into the "Site building" groupings essentially (Team, Testimonials, Services, Contact, About, Portfolio, Media). @mtias indicated to me that we shouldn't move forward with the site building groupings though so I'll get some clarity from him at this point. For now, let's expect there are not plans to add to those categories.

For any that are empty that we want to keep, we should simply not show the category as well.

[annezazu]

From what I can see, this can be closed out with the following items merged:

#46005
#46450

We can continue to iterate, especially when the Pattern Directory redesign happens. Unless anyone objects or has some additional items to include, I'll close this out later this week.