Consider adding a Style Guide category

[colorful-tones]

Current challenge

In the past, as an agency developer, I've created themes; whereas, the first thing I create is a series of basic patterns for a Style Guide, which the client can then use as their baseline and reference point at project handoff. These are usually based on Figma designs from a designer.

Typically there may be customary patterns for:

• all headings: h1, h2, h3, h4, h5, h6
• lists: bulleted ul, numbered ol
• buttons: this is usually the most complex with variations for coverage

Here is a Gist of blocks I've used in the past to populate Style Guide pages in WordPress instances in the past: https://gist.github.com/colorful-tones/2e37d2a33ca426fc6ed0e67f70cdc2df

And this is largely what I used recently when creating my submission for the Twenty Twenty-Three style variation I submitted, as seen here:

Proposed Solution: Style Guide Block Patterns

Style Guide Block Patterns would be a series of patterns:

• Style Guide: headings
• Style Guide: lists
• Style Guide: buttons

These barebones patterns would be useful to all theme developers and builders in conveying the common elements for their site and providing a visual baseline.

Since these patterns may diverge from the initial goals of the Block Pattern Directory (see: Guidelines: Do's and Don'ts). Having a designated category: Style Guide (or other) would help developers to search and insert.

Perhaps a nice Phase II feature would be to allow for the category to be hidden from general public consumption, but shown to developers if there is a constant set in theme (during development), e.g. define( 'WP_THEME_DEBUG', true );. Otherwise, it may confuse everyday creators if these patterns showed up in their Block Pattern searches. Perhaps it is ideal to have them publicly available though and encourage builders to be able to leverage them as well.

It would be advisable to only allow for certain contributors/moderators to be allowed to update these Style Guide block patterns, which may help alleviate some of the Pattern Spam that is initially being encountered (see: #449)

Additional work

Once most of the proposed Style Guide patterns infrastructure is in place in the Block Pattern library. Then additional work will likely be focused on surfacing these patterns with Gutenberg Pattern Inserter (again, related to how it is surfaced for Developers only?). See: Gutenberg: Highlight pattern directory patterns in the initial view of the pattern inserter. Perhaps the patterns can easily be bundled and surfaced in the Pattern Inserter without using a constant approach (mentioned above), but merely via theme.json API.

Related/Overlapping Issues

• Figure out a way to categorize and show "site building" block patterns
• Consider adding additional categories
• Consider separating out Core patterns
• Indicitive check for non-patterns at submission

[colorful-tones]

Further consideration and exploration around translation may be needed here. It is likely that it would be easiest to use Lorem Ipsum for these Style Guides, which may warrant them to not be translated, but then again, it would probably be ideal to not use Lorem Ipsum, so that translation and different writing styles can be covered in these Style Guide patterns.

[colorful-tones]

@joyously helped poke holes in my lack of discovery and my understanding (full Slack thread) of the current state of the Theme Unit Test data project (Github repo).

I misunderstood that parsed Block data does exist in the current Theme Unit Test. However, I do still believe that it maybe be worthwhile revisiting whether the Github Theme Unit Test data project is still adequate for theme developers. That certainly is a larger discussion, which I'll likely bring up in the next bi-weekly #themereview meeting.

My new current focus would be whether there needs to be any specific updates to the Theme Unit Test (XML) to fix any deprecated Core blocks (see Old markup is creating JS errors in the site editor)

@joyously and @carolinan likely have insight on current state of affairs for the Theme Unit Test (besides perusing the current Issues).

The overall goal is to create a single source of truth for FSE and traditional theme developers to have a baseline testing scenario.

Note: this is likely beyond the scope of just the Block Pattern Library and this Issue possibly spans several projects: Gutenberg, Block Pattern Library (this repo) and Theme Unit Test.

I'll leave this open for now for discussion, but maybe close it in the future as I break down specific tasks to chip away at. 👍

[colorful-tones]

I've edited the original proposal and idea and removed the discussion around replacing the Theme Unit Test data as this seemed to confuse the overall goal here and I did not want to distract.

[ryelle]

Would this be a category for a set number of patterns, or do you see a use case for allowing anyone to create Style Guide patterns?

If it's a fixed set, would a "Style Guide" plugin work? That would also take care of some of the "phase II" features, since they wouldn't be available unless you've opted to install the plugin.

[colorful-tones]

Would this be a category for a set number of patterns

Yes, I would see it as a pretty static number of patterns. Likely start with a handful and then have a few more added as we go.

or do you see a use case for allowing anyone to create Style Guide patterns?

I would encourage us to tightly moderate what would be considered for new Style Guide patterns.

If it's a fixed set, would a "Style Guide" plugin work? That would also take care of some of the "phase II" features, since they wouldn't be available unless you've opted to install the plugin.

@ryelle this could totally be plugin territory and great feedback. My only hesitation is that it could be very useful for everyday builders to have the patterns surfaced in themes. So, perhaps a WordPress.org theme might register the core Style Guide patterns in the theme's theme.json and then even create a template with all the patterns surfaced for an auto-populated Style Guide template, which could give them a great overview of what the color palette, typography, buttons look like. This could play nicely with style variations in FSE.

[ryelle]

I would encourage us to tightly moderate what would be considered for new Style Guide patterns.

Who would moderate it? Right now we have very loose moderation in the pattern directory - really anything goes as long as it meets the few guidelines. So if you're looking for something highly moderated, that seems like another point in a plugin's favor.

So, perhaps a WordPress.org theme might register the core Style Guide patterns in the theme's theme.json and then even create a template with all the patterns surfaced for an auto-populated Style Guide template, which could give them a great overview of what the color palette, typography, buttons look like.

Ah, that does make sense. We do technically have an internal keyword taxonomy which we could appropriate for this — it's how the "core" patterns are bundled. So it wouldn't be a public-facing category, but those patterns could still live in the Pattern Directory.

[colorful-tones]

Who would moderate it? Right now we have very loose moderation in the pattern directory - really anything goes as long as it meets the few guidelines. So if you're looking for something highly moderated, that seems like another point in a plugin's favor.

Yes, this is certainly a consideration. I do not want to create a gatekeeper scenario or a maintenance burden. However, I'm concerned that somebody scanning the pattern directory for everyday use might see a Style Guide pattern and lacking context get confused by its purpose. So, I'm trying to balance the different use cases.

Ah, that does make sense. We do technically have an internal keyword taxonomy which we could appropriate for this — it's how the "core" patterns are bundled. So it wouldn't be a public-facing category, but those patterns could still live in the Pattern Directory.

Tell me more! 😄 I feel like this internal taxonomy could be a nice territory for these Style Guides. Is this something more directly related to WordPress core and not necessarily the Patterns Directory? (Probably a bit of both having the APIs, right?)

[ryelle]

The internal taxonomy is used for sending specific patterns in the directory to WordPress. You can see the API request core does here - so any pattern with this term is sent to every WordPress site. Right now it only has the one term, since it's honestly kind of a workaround.

I understand having these patterns in the directory would make it easier for theme developers to register them in theme.json, but I still think this sounds like a plugin. The fact that it would have a different moderation process, and could require special handling in the directory both give me pause. It's also still not clear who would "own" this and do the moderation, the theme team? How would someone submit a Style Guide pattern, would it be different than the existing pattern process?

[carolinan]

I agree that users can benefit from viewing a style guide. But I do not see them adding a list of H1-h6 headings to a page or post. I don't believe it should be a pattern feature.
It would be more suitable either as a theme information page under appearance, or perhaps linked from the Styles sidebar if the theme supports the site editor.

[ryelle]

I'm going to close this issue as the Style Book feature will be available in WP 6.2.