The initial mockup for this is below, but we don't have some of this data - like WP version compatibility, pattern version, or "tested up to". The preview is also not an editable region, so it won't have the block toolbar. (if someone wants to edit the pattern, we do have the concept of forking, but not for v1 — #17)

We also probably need a more obvious way to add this to your site — the "Add" button exists, but what does it do?

Updated with latest mockup:

We need a way for a user to create their pattern and input the necessary metadata for it (name, description, tags, etc). I suspect this should pretty much just be the Gutenberg editor so, to start, I mocked that up with a pre-submission flow unique to this use case.

Try the prototype.

The pre-submission sidebar gives the user inputs for a pattern name, description, tags (the usual tag interface), and some controls to help them create an ideal pattern preview.

Screenshots

Outstanding questions

1. Should the editor have a different icon/header/something to indicate it's the pattern submission tool and not the regular editor on one of the user's sites?
2. Are there controls we should remove from the editor (like block installation)?
3. What does the user see next? I imagine either a success message on their Submitted Patterns page or a login flow that then leads them there.
4. What are the errors a user might encounter in creating a pattern?

Tasks

• Category bar (All, Header, Sidebar, Footer, Gallery ... )
• Search Bar
• Category dropdown ( Featured, Newest, Popular ) (Lowest priority)

This ticket will not implement the grid list. That is contained in a separate ticket: #62.

Screenshot

When a user goes to submit a pattern, they will get a modal with 3 "steps" (2 + done).

It should be pre-filled with any meta information they entered in the pattern sidebar. Clicking Publish will call the API to save the post. Tracking validation & post-save is in #36

Pulling this out of #48 — the pattern list view should be styled as a grid, and will either have a "load more" button or pagination. We can use JS to load the whole list (something SPA-style that controls the pattern grid), or just use URLs + JS for animation/flair. Probably will land on the JS solution, but will want something that works well across all archive & searching templates.

The preview cards themselves have a separate issue #31 , but there will probably be 1 PR for both issues.

The editor should now be full screen (disable non-fullscreen mode), and have the pattern title visible.

The sidebar will have two sections (like the CPT editor), but instead of Document settings it will be Pattern meta information.

The "View" link functionality is in #29.

As mentioned in #8, workflows and tools are needed to be able to moderate patterns that have been submitted to the directory, whether that moderation happens before or after the pattern is published and available.

Since patterns are a custom post type, the main screen for moderating patterns will probably be the patterns list table screen.

Each of these can probably have their own issue:

• Custom statuses for different parts of a pattern's life cycle (#56, #107)
• A field for adding private notes, possibly connected to status changes (#105)
• A logging mechanism to record who changed the status, and when (#57)
• Email notifications to a pattern author when a status changes (#58)
• A way to collect submissions of flags/reports about a pattern on the front end (#61, #80)
• Columns for the list table, e.g. status, author, reports, ratings, etc. (#63)
• Filter views for the list table, e.g. to show only patterns with a particular status (#63)

The Pattern Directory will need a web-based front end for searching and browsing patterns, broadly similar to the plugin directory or theme directory sub-sites on WordPress.org.

Tentative assumptions:

• This can probably be built as a WordPress theme, in a similar manner to the plugin directory. (#25)
• The design and general structure can initially be based on the plugin directory.
• Some kind of previews or screenshots of patterns will be important.
• Other metadata should be searchable and displayed, such as descriptions, tags, and locale. (partially covered by #28)
• It should be possible for users to rate or vote for patterns.
• Some kind of category structure should be considered.
• Users should be able to easily find their own patterns. #16
• It should be easy for users to take a pattern from the web front-end and use it in a post on their own site.
• There should be a mechanism for users to help translate a pattern.

This is an umbrella task.

Following on from #22 (comment):

It seems like we need something a bit like a lightweight version of the block plugin e2e tests, that would run a few simple server-side JS tests to check a pattern for validity. And perhaps grab screenshots or other info.

How could we do this in a way that uses our own servers, or minimal additional server resources?

Following the validation in #22, we should tell the user that the pattern has been saved & published, or whatever the state is…

• Passed validation, is publicly available at [link]
• Failed validation? show the failures, give info to remediate the pattern (still a draft)
• Pending validation (if we need to do something that takes time, like human review), with indication of place in a queue?

Patterns need to be checked for validity during the submission process. Probably different levels of validation at different points:

Early:

• Is it even a pattern? (Contains blocks, not random binary, etc)
• Does it meet some minimum size/length? (At least one block with non-default attributes or content?)
• Does it contain JS or inline CSS?
• Do the blocks exist?
• Is the markup minimally valid?

Later:

• Does it use permitted blocks? (Core only, or an allow/deny list?)
• Does it contain forbidden links or keywords? (Spam etc)
• Does it have sufficient metadata?

Last:

• Does it have the same name or content as another published block?
• Does the content meet community standards? (Offensive language or images)
• Does it pass a license check (if applicable for images or other media)?
• Is the author following appropriate guidelines?

I imagine the Early checks would be applied before saving a pattern at all. Later checks would need to pass in order to submit a pattern for publication. And the Last checks would be made at least in part by humans, before approving a pattern for inclusion in the public directory.

If we assume that "private" patterns will eventually become a thing, then the Early checks might be sufficient for saving a pattern for private use only.

This issue is pulling out the Front End UI section of #61, and building off the work done in #77.

When viewing a single pattern in the directory, there should be a "Report this pattern" button to click in the case that the pattern is problematic for some reason. Clicking the button should bring up a modal similar to this mockup:

I would suggest that instead of a textarea that only applies to the "Other" category, the textarea should always be present beneath the radio button group, labeled "Details", and perhaps always be a required input. It seems that no matter which reason is chosen for reporting a pattern, more context will be necessary for a moderator to effectively review the report.

Further requirements:

• The options in the radio button group for "Please choose a reason" will be drawn from terms in the wporg-pattern-flag-reason taxonomy.
• When the form in the modal is submitted, it should send a POST request to /wp-json/wp/v2/wporg-pattern-flag. The request must have the following parameters:
  • parent The ID of the pattern post
  • wporg-pattern-flag-reason The ID of the "reason" taxonomy term
  • excerpt The user-input string of text providing details about the problem with the pattern
• The API will send back an error in some cases, which we may want to surface to the end user. Some examples of relevant errors:
  • You have already flagged this pattern.
  • Flags cannot be submitted for this pattern. (if it is not published, for example)
  • You must be logged in to submit a flag.
• Perhaps the "Report this pattern" button shouldn't be shown unless the user is logged in? Or perhaps if they aren't logged in, the modal should instead show an explanatory message and a link to log in that will then bring them back to the pattern page afterwards?
• Ideally the "Report this pattern" button would be aware if the current user has already submitted a flag for the pattern, and would show with a checkmark or something, as well as being unclickable.

Related to #16 , should we send people an email when a pattern is accepted or declined?

I get TypeError: can't access property "tinymce", window.wpEditorL10n is undefined when trying to insert the Classic block

We likely need to introduce the user to the pattern submission process. I think the modal used in the editor might be a good way to do it. Designs TBD.

Questions

What concepts should be covered?

Similar to the plugin directory, it'd be useful for the pattern directory to track stats on which patterns are installed.

That could help the w.org front-end directly display popular patterns, etc.

This could be done by sending a list of installed pattern IDs to api.w.org when Core checks for updates, which is how it's done for plugins.

It's not clear yet how patterns will be "installed", since inserting a pattern into a post could detach it from the canonical version on w.org. The designs might include a way of "favoriting" a w.org pattern, or similar.

We register a wporg-pattern-category which I assume will be assigned to block patterns and used as the sorting mechanism for the pattern grid menu here: #48.

Questions:

• Is that assumption correct? Will we be using those categories?
  • How will we manage localization?
  • How can we control the order of how they appear?
• How will we manage the "context" messaging that appears when a user is looking at a specific category?
  • This PR just adds a temporary object (https://github.com/WordPress/pattern-directory/pull/65/files#diff-e8270c6022d0c897772f5a8dbb27343105f0f5f3d678fa1245176d6c6d17c936)
    • We'll want to make it more dynamic.

We could alternatively hardcode the items for now.

Related PR: #72

Most (all?) text-related blocks can have a font size control. The sizes are passed in via the editor settings, and we're not passing anything right now, so the only option is "default".

Not sure about the color support, so we should also check that.

In core, these descriptions are used as alternative text and are only exposed to screen reader users. From the documentation:

A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does.

For example, "Two columns of text, each with an image on top." or "A large hero section with a bright gradient background, a big heading and a filled button."

When filling out the pattern creator, the description is just called "description", with help text "What is this pattern for?" — this makes it seem like this should be marketing copy, which would not be appropriate as non-visual descriptive text.

Should we change the name of the description field? Or have two separate fields for alternative text (used as description/alt text in pattern lists) and marketing copy (not used in core, but searchable/displayed on wordpress.org/patterns)?

• draft The pattern has not been submitted to the directory yet, or it was submitted but failed automated validation checks. See #36
• awaiting-review (or maybe just use pending?) The automated checks determined that a human review is also needed. This could also be used when a published pattern gets flagged as inappropriate.
• declined The pattern was declined by a human reviewer. See #16
• publish The pattern passed automated checks and/or human review. It is now published in the pattern directory and appears in searches via the API.
• removed The pattern was previously published, but was removed either by the author or a moderator. See #16

There is also some discussion in #16 of having patterns that are only available to the pattern author until the author chooses to publish them. So an additional status might be:

• private The pattern has been submitted, and passed automated checks, but has not been published by the author.

Just hardcode Core patterns for now, so that work on the Core endpoint can start. We can iterate to add dynamic functionality.

https://api.wordpress.org/patterns/1.0/?action=query_patterns&search=header
https://api.wordpress.org/patterns/1.0/?action=pattern_information&slug=large-header

#5 (comment)

The current theme is a very basic stub, and not used on production b/c it doesn't look like the rest of w.org.

The final design isn't clear yet, but it's safe to assume we'll want a child theme of wporg, similar to how the Learn site is setup. We can fork that as a starting point, and remove anything that's specific to Learn.

When the status of a pattern changes (#56), and possibly in some other cases, the pattern author should receive an email notification about the change. This serves to ensure they are informed when e.g. a pattern is removed from the directory by a moderator for some reason, and also to alert them to possible unauthorized access to their account.

Should it be possible for patterns to contain placeholder blocks, such as "your image goes here"?

If so, what's needed to support that?

What kinds of placeholders are needed, besides images?

This is needed for IE8-10 back-compat, but we're targeting IE11+. Since IE11 supports rem sizing, we don't need to add these duplicate fallback rules.

This is in the theme's Gruntfile & package.json.

We have #23 for the idea of setting up asset placeholders (cover block, images, etc) where the end user would add in their own image, but it's also likely that pattern authors will want to add their own assets as part of the pattern (a cover block with a highly designed background image).

• Should we allow asset (image, video, audio, …?) uploads to w.org through the creator?
• Maybe only allow the "Insert from URL", with users uploading media elsewhere?
• Safelist the allowed URLs?
• What if the content at the URL changes/disappears?

Checking for inappropriate material & licensing will be tracked in #22, but could also be part of the upload step here

My prototypes do not include the login flow yet. Ideally, we would want to log in or register the user as late in the flow as possible. Is this something we can do after they have gone through the submission process as a last step?

It's likely that the editor UI will have a flow where users could discover patterns that contain a particular block.

As a hypothetical example, if I'm adding a Buy Now button to content, it should be easy for me to discover that my e-commerce plugin already has some patterns for product layouts that contain the Buy Now button, to save me doing it all manually.

That suggests some things would be required on the back end:

• A way to search both local and remote patterns for an exact match by block slug.
• Possibly a way to retrieve all local patterns grouped by block (if for example the inserter UI was to display blocks and patterns side by side).

This is still a feature idea in progress so it's not clear exactly how it might pan out and what the final flow and requirements might be.

Users should be able to copy patterns. There is a copy button on both the details and list view. When clicked, the button should copy the pattern code (ex: <!-- wp:group...) to the user's clipboard, and show a success notice.

If they click learn more, a modal pops up:

See this codepen, click Modal in the top row.

The pattern list table will primarily be used by people who are reviewing or moderating patterns that have been submitted by users on the front end. Thus the table columns and filters that are present should be optimized for reviewing/moderating tasks.

Columns

• Title (Pattern name)
• Author (User name of pattern creator)
• Date (Date published, or last modified + status)
• Flags (#61)
• Categories?
• Keywords?

Filters

Besides the defaults:

• View by has flags
• Sort by number of flags

Quick Actions & Bulk Edit

When a moderator changes a pattern, they should include a reason so that it's easier to understand later why something changed (#57). So ideally, when a quick action or bulk edit is modifying patterns, it should trigger a field to appear in a modal or something where a comment about the change can be entered.

There should a page a user can see their submitted patterns and the status of those patterns.

• What are the various statuses of the patterns (submitted, reviewed, rejected)?
• How should a user get to this page? Is there something similar for plugins?

Breaking out from #9: "Translations and i18n will need to be solved."

The home page view of the Pattern Directory should feature a masonry-style grid, and a short list of filters/types for refining the view:

Along the top of the patterns grid is a “sort by” dropdown, followed by a list of selected categories, and then a search box. Changing the sorting or selecting a category updates the grid and exposes a secondary UI that indicates the current criteria (category, author, tag, etc) along with space for displaying related information like related categories or an author’s website.

The Patterns site focuses around a masonry-style grid of rendered patterns. The initial designs have a discrete “Load more” button, but infinite scroll could be added in future. Within the grid, Patterns focus on showing there rendered output, unlike the Plugins/Themes directory where a static image is required.

This will be part of #11. We want a "card"-like view for the block patterns for use on list pages (homepage, your own patterns, etc). It would be nice if this could be a reusable component so we could use it for displaying block-plugins on wp.org/plugins, too. There is already a BlockPreview (or similar) component in gutenberg, might be a good starting point if it's publicly exported.

This is one iteration of the design, for reference:

Get rough version working w/ api.w.org, see #2 .

Right now, the pattern CPT endpoint works as long as you're a user on the site, but we're not going to add every wp.org user to the patterns site. We need to update the permissions checks to allow any logged in wp.org user to edit/create a pattern. Any custom validations could also be added in this step, maybe? See #22.

Probably this would be done by subclassing WP_REST_Posts_Controller, adding that as the rest_controller_class for the CPT, and overriding create_item_permissions_check & update_item_permissions_check.

If a user is logged in and has submitted patterns, the callout on the homepage should be updated to show relevant info:

How do we want to organize the front end?

• Do we want to create a front-page.php for the grid?
• We currently have an index.js file in src that pulls in the pattern preview component. Are we going to leverage that index.js and turn it into an app the same way an SPA works?
  • If so, do need a router?
• Alternatively, do we want to load a separate JS payload per page?

@ryelle @iandunn Thoughts?

The back-end for the block pattern directory should be broadly modeled on the plugin directory, and can probably import some of the code.

Tentative assumptions:

• Patterns should be stored in CPTs (#6).
• Each pattern would have metadata such as author, title, description, tags, language, screenshots. Partially done in #6.
• #279
• There should be an API endpoint for searching and fetching patterns. (#6)
• Pattern searching should use ElasticSearch in a similar fashion to the plugin directory (#28).
• Some kind of curation or moderation will needed.
• Some kind of user-submitted ratings or voting will be needed.
• Some kind of popularity stats will be needed. (#24)

This is an umbrella task, separate issues should be created for the various parts.

Allowing users to fork a pattern seems like a pretty cool way for patterns to evolve over time and for users to efficiently create their own patterns. I'm starting to work in this flow as it seems like a rather frictionless entry into the pattern editor.

Try the prototype.

Note: This prototype goes right into editing, but I am planning a pattern submission intro modal to introduce the user to the process. I will address this in another issue.

Screenshot

Questions

What should the action be? Remix? Duplicate? Something else?
Should the forked pattern be referenced by the new pattern in its details page?

Necessary to iterate on #2

There are probably several reasons why we'd want to be able to audit changes made to a pattern. One is so we can see who removed a pattern from the directory, when they did it, and why, if they include a reason.

A log entry should have a date, user name, type of change, and an optional comment. It might look something like this:

Log entries could be added both by automated processes (by "patternbot" or something) or by user-driven actions. In some cases the comment field could get populated automatically with pre-determined values. In other cases, like when a moderator is manually changing the status of a pattern, a textarea field should be available to add a reason, which would then get added to the log's comment field.

Users should be able to favorite patterns from the pattern detail page, and then query for those patterns via the API. Plugins has a similar functionality, can probably look there for how to do the backend. We can create a followup issue for the proxy API http://api.wordpress.org/patterns/, this issue is just for updating the local endpoint.

The UI for marking favorites:

The heart animates when clicked, then turns red & the text is updated.

This is a work in progress. Requirements listed here are up for discussion.

A pattern flagging system will have a few different components:

• Front end UI for flagging a pattern in the directory
• A REST API endpoint to submit the data from the UI
• A schema for storing flags for a pattern in a structured way
• Back end UI for surfacing flags to pattern moderators

Front end UI

The pattern detail page will have a “Report pattern” link which opens a modal with some options to report a pattern:

Rather than a separate "Other" field, it might be worth considering requiring a comment regardless of which reason is selected. I.e. "Trademark Issue" isn't that helpful on its own without additional context provided.

A user should only be able to flag a particular pattern once. If they have already flagged it, the "Report pattern" link should reflect that.

REST API endpoint

• The endpoint might look something like wp/v2/wporg-pattern/(?P<id>[\d]+)/flag
• A request to the endpoint should include the pattern's post ID and a text string reason for the flag.
• In order to flag a pattern, the user should be required to be logged in to their wp.org account so the user name can also be attached to the flag.

Flag schema

• Pattern ID
• Date
• User name
• Reason
• Maybe a flag status? So flags can be differentiated by whether they have been reviewed yet or not.

There are a few different ways flags could be stored:

• As a separate post type, with the pattern post as a parent
• As comments on the pattern post
• As meta fields on the pattern post (one entry would contain all the flag data)

Meta fields would be the easiest to initially implement, but would be more difficult to work with later if we want to be able to query by certain schema fields, e.g. is one user flagging a lot of patterns?

A separate post type would probably be the most flexible to work with, since all of the schema fields would fit into existing post fields and it would have great query support.

Back end UI

• The number of pending flags on a pattern could show in a column on the pattern list table, perhaps similar to pending comments on a post.
• Clicking the number could go to a separate list table showing all pending flags for a specific pattern post.
• A row in the list table could have quick actions to view the pattern and mark the flag as reviewed. Unpublishing a pattern should probably not be a quick action, because we would want the moderator to include a comment/reason when changing a pattern's status (#57)

In the patterns, the creator can add attributes to the blocks, as long as the block supports it (color, font size, padding etc, and soon, borders).
But what if I want to create a pattern that needs CSS that can't be achieved with the block support?
For example, box shadow, or positioning a block so that it overlaps (See for example Twenty Twenty-One).
Or if the pattern needs to have a mobile and a desktop width style.
Then I would need to add a CSS class to the block inside the pattern and register a custom block style.

If I was making a theme or plugin, that style would break when the plugin or theme was switched, only the content and the block markup would remain on the users install. How will this be solved with the patterns?
Are the block patterns from the block pattern directory going to be accompanied with custom block styles that are saved to a global custom CSS field (think, the additional CSS field in the customizer)?
Or something else? Registered when the pattern is placed?
What would happen to that CSS if the block that has that class is deleted from the saved content?

Or are all block patterns going to be limited to the global styles?

Normally Core searches post_content, but that probably won't make sense for most patterns, since that's storing the HTML and demo content. It'd make more sense to search the meta description field instead.

See #11

One way to do this might be to save the description into post_excerpt, instead of a meta field. Then it'd be searched for free. We'd still want to disable searching post_content, though.

That'd also require changing the two APIs that proxy this API, which would be a pain. We might also want to search by other post meta per #11, so we might need that functionality anyway. We'll probably need to update them anyway, as the design evolves, so maybe those updates can be batched together after more are settled.

Pulling this task out of #14.

The mockups have a preview button:

When clicked, it would show a dropdown like post previews #14 (comment)

I added the preview link as a possible location for both desktop/mobile preview as well as maybe theme switching.

Post screen example, probably something like this but instead of "Preview in a new tab", it could have some themes to apply. Maybe just the Twenty*s?

Option from mockups:

The core editor should allow users to search and insert block patterns from the pattern directory, in a similar way to the block directory.

Tentative assumptions:

• Unlike block plugins there is probably no "install" step needed. Patterns from the directory can simply be inserted into a post exactly as core patterns work at present.
• Core patterns might be moved to the Pattern Directory, so they can be improved independent of the core release schedule.
• A local REST API endpoint for searching the pattern directory might be needed, in a similar manner to the block directory endpoint. (#3)
• Patterns from the directory can probably be listed in the same UI as core patterns are at present.

This is an umbrella task, specific issues should be created as needed.

Patterns should be submitted from a purpose-built front-end form based on Gutenberg.

Tentative assumptions:

• Any logged-in user should be able to submit a pattern.
• It will be necessary to preview and edit a pattern during the submission process.
• Submitted patterns will need to pass some kind of validation, curation, moderation process before being published to the world.
• Users might expect to be able to see and use patterns they have submitted even if they're not yet published.
• Users will need to provide some metadata with their patterns, such as description and language.
• Copying or "forking" an existing pattern will probably be a common flow.
• Translations and i18n will need to be solved.

This is an umbrella task, specific issues should be created as needed.