Documentation

Pattern Builder is a free, open-source WordPress plugin for creating, editing, organizing and managing block patterns from inside wp-admin. It treats the patterns that ship in your theme and the patterns you save in the editor as one library, opens every one of them in the WordPress editor itself, and gives an AI agent the same access through WordPress’s Abilities API.

What it does

• One library for every pattern. Theme patterns (PHP files in your theme) and user patterns (saved in the database) sit side by side under Appearance → Pattern Builder, with live previews, search and categories.
• The real editor. Patterns open in the block editor you already use, with undo, dirty tracking and the normal save flow. Pattern Builder never invents a canvas of its own.
• Files stay the truth. A theme pattern is read from its file and written back to its file. Nothing is mirrored into the database, so what is in git is what is on the site.
• Every kind of pattern. Design patterns, synced design patterns, and the starter patterns WordPress offers for new pages, empty blocks, templates and template parts, each created from a form that asks only for what that kind needs.
• Full metadata. Name, slug, description, categories, keywords, block types, post types, template types, viewport width, inserter visibility and synced status all round-trip through the pattern file header.
• Conversion both ways. Turn a user pattern into a theme file, or a theme pattern into a user pattern, with the images moved and rewritten for you.
• A cloud library and a directory. Connect a patternbuilderwp.com account and carry patterns between the sites you build, or install from the collections Twenty Bellows and partner studios publish.
• Abilities for agents. Ten abilities under pattern-builder/* let any agent that can sign in read your design system, list your blocks and patterns, and store finished markup.

Get the plugin

Pattern Builder is on the WordPress.org plugin directory. Search for Pattern Builder under Plugins → Add New, or download it from wordpress.org/plugins/pattern-builder. It needs WordPress 6.8 or later and PHP 7.4 or later, and it works with any theme, though it is at its best with a block theme.

The plugin is GPL-2.0 software and its source is on GitHub at Twenty-Bellows/pattern-builder. Bug reports, feature requests and pull requests are all welcome there; the Contributing page says how.

Two plugins, one runtime

Some of what Pattern Builder does at edit time needs support at render time. A synced theme pattern (one whose file says Synced: yes) and a pattern that fills another pattern’s content slots both rely on a small runtime that WordPress core does not have. Pattern Builder ships that runtime, and so does its companion plugin, Synced Patterns for Themes.

How these docs are organized

1. Getting started — install the plugin and take a tour of the Pattern Builder screen and the editor.
2. Kinds of pattern — theme and user, synced and unsynced: where a pattern lives and whether its copies stay linked.
3. Creating patterns — the six kinds in the Create Pattern dialog, what each one asks for, and the metadata panels afterwards.
4. Synced theme patterns — Synced: yes, content slots, the design/content split, and the runtime they need.
5. The cloud library — connecting an account, uploading into a collection, and what travels with a pattern: its images, its design tokens, its block styles, and the other patterns it is built from.
6. Collections — the unit of organising, publishing and installing: Personal, private, public and premium, the free and Pro tiers, who publishes, and what an agent may do.
7. Abilities and agents — the twenty-six abilities, how to connect an agent, and how to validate markup before storing it.
8. Contributing — reporting issues, the development setup, and the licence.