Claude Code skill for choosing between custom blocks, patterns, synced patterns, and template parts on WordPress 7.0+.
Status: authoritative reference. Read before deciding whether a section should be a core block, a block variation, a custom block, a pattern, a synced pattern, or a template part. Established: 2026-05-28, from official WordPress sources plus an empirical test on a WordPress 7.0 install. Revised: 2026-08-07, after a block theme was audited and ten of its twelve custom blocks were found to duplicate core blocks or to edit through Inspector fields. The core-first check, the variation-registration mechanics, the canvas-not-Inspector rule and the block-attribute layer of the styling cascade all come from that audit. Targets: PHP 8.4+, WordPress 7.0, theme.json v3.
wp:pattern references. A wp:pattern reference flattens into inline blocks the moment the page is saved in the editor -- verified on WP 7.0 core (see "Empirical test" below). Content-only editing does NOT keep the reference live.TextControls, a textarea holding HTML or JSON, and a ServerSideRender preview standing in for editable content are all the same anti-pattern. See "Content on the canvas".!important. See "Use core's own attributes first"."role": "content" on the custom blocks that survive the core-first check, so they stay editable in WP 7.0 content-only mode. This is damage control for attributes a block legitimately owns; it is not licence to keep copy in attributes when the copy could be an inner block.is-style-*), which is rebuild-proof because the operator can reapply it by name from the Styles panel; then a custom block that owns its own render and stylesheet.Run this before opening the decision model. It is the cheapest check in the process and the one most often skipped.
ls wp-includes/blocks/
Read the directory in the WordPress version the project actually runs, not a remembered list. Core's library has grown steadily, and a block added two releases ago will not be in an agent's training data. Check the @since line in the block's render.php or its block.json to confirm it exists in the target version.
If core ships it, the section is a core block. The design is then expressed as:
Signals that an agent skipped this step, all of which have appeared in real code:
render.php emits <details>/<summary>, a tab list, a quote with a citation, or an image beside text.accordion, tabs, quote, details, cover) rather than for a domain concept.blocks/ directory where every block is a static arrangement of headings, paragraphs, lists and buttons.A custom block is justified by behaviour or managed data core has no block for. It is never justified by styling, and never by preferring a different editing UI.
Worked example. A design shows a panel of expandable question-and-answer rows. That reads like a bespoke FAQ component, and an earlier version of this document routed it to a custom block. Core has shipped core/accordion, core/accordion-item, core/accordion-heading and core/accordion-panel since 6.9 (@since 6.9.0 in each block's server file). The correct build is a variation of core/accordion plus styles, and the custom block is dead weight that also has to reimplement keyboard operation and ARIA that core already ships.
Counter-example. A design shows a slider that cycles between photographic panels. Core ships no carousel. That is a real custom block, but only for the slider shell: the region and slide roles, the controls and the live region. Each slide should still be a core/group of ordinary blocks, rendered by iterating the block's inner blocks so each can be wrapped in the slide chrome. Split the behaviour core lacks from the content it does not.
"Block Patterns are predefined block layouts available from the patterns tab of the block inserter. Once inserted into content, the blocks are ready for additional or modified content and configuration." -- Block Editor Handbook, Patterns
The lifecycle is: insert -> the pattern's blocks are copied into the page -> edit them there. The pattern is a template/starting point, not a live link. The Theme Handbook recommends the file-based /patterns folder for registration (Patterns -- Theme Handbook).
From Comparing Patterns, Template Parts, and Synced Patterns:
| Mechanism | Type | Syncing | Example |
|---|---|---|---|
| Template Part | Site structure | Synced | Header, Footer |
| Synced Pattern (reusable block) | User content | Synced (one source, updates everywhere) | Business hours |
| Pattern (unsynced) | User content | Un-synced (per-instance copies) | Call to action |
"patterns are best for content that you expect to change across your site... When it's less about content and more about wanting to repeat a design or layout, patterns are best."
Custom blocks are for functionality / managed components (custom rendering, structured data, media handling, interactivity) -- not for static arrangements of core blocks (those are patterns), and not for anything core already ships a block for (Step 0). A fifth mechanism sits alongside these four and is easy to forget: a block variation of a core block, which gives a named starting point in the inserter without any of the ownership cost of a custom block.
From Pattern Editing in WordPress 7.0 and the Call for Testing:
"role": "content" on any attribute that should be editable in content-only mode. Example: message: { type: 'string', default: '...', role: 'content' }.The one thing the official posts do not state is whether an unsynced, file-based wp:pattern reference survives content-only editing without flattening. Tested directly on a WP 7.0 install:
wp:pattern reference block pointing at a registered pattern (47 chars).core/group), and saved via wp.data.dispatch('core/editor').savePost().post_content: over 2,000 chars of expanded inline blocks, zero wp:pattern references. The top block was a core/group carrying metadata.patternName for provenance, but every child block was fully expanded inline.Conclusion: a wp:pattern reference flattens to inline blocks on the first editor save, even in WP 7.0. The reference is not a stable, editable representation. (7.0 does stamp metadata.patternName on the expanded group as provenance, but the content is still inlined.) Therefore: do not rely on bare pattern references for content a human will edit.
Work down this table in order. The first row that matches wins, which is why the core-first row is first.
| Section kind | Mechanism | Why |
|---|---|---|
Core already ships a block for it (check wp-includes/blocks/ first) |
Core block, plus a block variation for the starting shape and theme.json / a block style for appearance | Core owns the markup, the accessibility and the editing experience, and maintains all three for free |
| Behaviour or managed data core has no block for (a carousel, a third-party embed with credentials, a structured record) | Custom block, scoped to the part core lacks; content attrs marked role:"content", media via an imageId attribute, and inner blocks for anything that is really just content |
Block instance persists in content; structure owned by the block and deploys with the theme |
| Plain layout of core blocks, content varies per page | Expanded core blocks in the page content (core/image, core/cover for media); the pattern stays as an inserter starting point only | Core blocks are inherently editable; content-only editing protects structure |
| Identical content reused site-wide (e.g. legal footnote) | Synced pattern, optionally with pattern overrides | One source updates everywhere |
| Site structure (header/footer/nav) | Template part (+ core/navigation for the menu) | Carries semantic meaning in block themes |
| Cross-cutting visual style (color, spacing) | theme.json / CSS | Applies regardless of how content is composed |
A variation is how a theme ships a design as a core block. Two registration routes exist, both official.
PHP, the get_block_type_variations filter. No bundle, no build step. The filter runs in WP_Block_Type::get_variations(); the result reaches the editor through get_block_editor_server_block_settings(), which is inlined as a call to wp.blocks.unstable__bootstrapServerSideBlockDefinitions.
add_filter(
'get_block_type_variations',
function ( array $variations, WP_Block_Type $block_type ): array {
if ( 'core/accordion' !== $block_type->name ) {
return $variations;
}
$item = array(
'core/accordion-item',
array(),
array(
array( 'core/accordion-heading' ),
array( 'core/accordion-panel', array(), array( array( 'core/paragraph' ) ) ),
),
);
$variations[] = array(
'name' => 'faq',
'title' => __( 'FAQ', 'example-theme' ),
'scope' => array( 'inserter' ),
'attributes' => array( 'iconPosition' => 'right' ),
'innerBlocks' => array( $item, $item, $item ),
);
return $variations;
},
10,
2
);
JavaScript, wp.blocks.registerBlockVariation( name, variation ). Needed when the variation wants a live isActive callback or anything else that only exists client side.
Things worth knowing before writing either:
innerBlocks is an array of [ blockName, attributes, innerBlocks ] triplets, nested. In PHP an empty array() for attributes is fine: it JSON-encodes to [] and spreads to {} client side.scope is inserter, block or transform. An inserter-only starting point needs nothing else.isActive (a string array of attribute paths, or a function) is what makes an inserted block report as the variation in the UI. Omit it when the variation sets no attribute that distinguishes it, and do not invent a marker attribute purely to satisfy it.Variation fields, per the Block Editor Handbook: name (required), title, description, category, keywords, icon, attributes, innerBlocks, example, scope, isDefault, isActive.
The operator edits real blocks in the content area, the way core works. The following are all the same mistake wearing different clothes, and all of them have shipped in real themes:
TextControl or TextareaControl in the Inspector.core/list, core/accordion-item), not an array attribute edited as text.ServerSideRender standing in for editable content, which gives the operator a picture of their page instead of their page.Inspector controls are for settings: a tone, an alignment, an icon position, a count. Not for copy.
Two mechanisms remove most of the temptation:
wp.richText.registerFormatType) for a run of differently-styled text inside a heading or quotation. That is the supported way to let an operator mark up part of a string from the toolbar, and it replaces the "type a span into this field" pattern outright. Register one format and let each section decide its size and weight in CSS.Converting a JSON textarea into a nicer repeater UI is not the fix. It is a better Inspector for something that should not be in the Inspector.
Before writing CSS for a core block, check whether core exposes an attribute for it. Common ones that get reimplemented in CSS by mistake: core/columns verticalAlignment, per-column width, spacing.blockGap, dimensions.minHeight, backgroundColor and textColor, style.spacing.padding.
Two reasons this matters beyond tidiness.
Core sometimes defends its own hooks with !important. core/columns ships .wp-block-columns{align-items:normal!important} precisely so that the per-column is-vertically-aligned-* classes its verticalAlignment attribute emits can win via align-self. A theme that sets align-items: center on the columns block gets silently ignored, and the instinct to answer with a louder !important is the wrong lesson. The attribute is the mechanism.
Attributes stay in the operator's sidebar. A value expressed as an attribute is visible and changeable; the same value in a stylesheet is not. Where the design has one answer for every instance, theme.json is right. Where it is per-instance, the attribute is right. CSS is for what neither can express: breakpoints, pseudo-elements, and selectors that reach inside a block's markup.
Equal columns carry no width at all. Omitting the attribute is core's own default for an even split, which is more robust than writing 50% and much more robust than fractional percentages derived from a design's pixel geometry, which have to be recomputed by hand whenever a column's contents change.
Themes that provision page content as code (a seed file, a fixture, an importer) have to produce core's exact save markup, or the editor reports invalid blocks on first load. Hand-writing that markup for core/columns, core/quote, core/image or the accordion family is error-prone: the block comment's attributes and the serialised HTML must agree exactly, including details like a percentage losing its trailing zero between the comment ("51.70%") and the inline style (flex-basis:51.7%).
A reliable way to produce it, rather than hand-write it:
wp.blocks.createBlock.wp.data.dispatch( 'core/block-editor' ).resetBlocks( blocks ).wp.data.dispatch( 'core/editor' ).savePost().wp post get <id> --field=post_content, and re-tokenise any attachment ids and URLs.That produces core's exact output by construction. Verify by re-seeding from the file and confirming the editor reports zero invalid blocks, so what is committed is what was checked rather than the editor session that produced it.
wp-includes/blocks/ before building anything. Core-first is the first question, not a later optimisation. A custom block that duplicates a core block is the most expensive outcome in this document, because it also reimplements the accessibility and keyboard behaviour core maintains.wp:pattern references, for anything a human will edit. References flatten on first save (tested above) and are not editor-stable.TextControl, no HTML in a textarea, no JSON anywhere, no ServerSideRender standing in for editable content. Use inner blocks for structure and a registered inline format for a differently-styled run inside a string.!important; a stylesheet that loses to core is usually a sign the attribute was the intended mechanism."role": "content" on custom-block attributes that hold editable text or media (titles, descriptions, button text/URLs, image IDs/alt). Do NOT mark pure settings (toggles, speeds, overlap px, layout switches). Marking an attribute role: "content" does not make it the right home for copy; prefer an inner block where one will do.imageId attribute on the block and render with wp_get_attachment_image() (a theme-file fallback is fine until one is chosen). If content is provisioned programmatically (a seed script, an import), import assets into the media library rather than hardcoding a theme-file URL, so the result stays editor-swappable.Block-theme styling is a defined cascade, most-global to most-specific (Theme Handbook / Block Editor Handbook). Put each value at the RIGHT layer; the layer is decided by SCOPE, not preference.
styles -- global defaults that "trickle down through the design and are used unless a more specific element or block style overrides them."styles.elements.<element> (e.g. button -> .wp-element-button) -- the site-wide default for that element type.styles.blocks.<block> -- default for a block type..is-style-{name}, registered via register_block_style() or a /styles partial) -- named, selectable variants. The Theme Handbook RECOMMENDS these over custom CSS "because they appear in the Appearance > Editor > Styles interface, and your theme users can make their own changes."style= literal values -- avoid where a design-token layer above could express the same value. A preset-referencing inline value (e.g. padding:var(--wp--preset--spacing--lg)) is fine; a literal value (e.g. border-radius:20px) usually belongs at a layer above instead.A per-instance value sits outside this cascade entirely: it is a block attribute. The cascade above answers "which layer owns this value for a class of blocks". When the value differs per instance and core exposes a control for it, none of these layers is the answer; the block's own attribute is, because it is the only option the operator can see and change. Column widths, vertical alignment, block gap, minimum height and tone are attributes, not stylesheet entries. Note that a block style variation can then style the framing while the attribute carries the instance value, and the two do not conflict.
Decision rule: does the value differ per instance, and does core expose a control for it? -> block attribute. Is it the default for EVERY instance of an element/block? -> global layer (theme.json elements/blocks, set once). Is it a VARIANT (only some instances) that no attribute expresses? -> a block style variation (preferred, editor-visible/user-editable). Does it need a breakpoint or a pseudo-element? -> a stylesheet, attached to a registered block style so it stays reapplicable. Is it already the global default? -> don't restate it.
WordPress 7.0 also supports pseudo-class selectors (:hover, :focus, :active) directly in theme.json on blocks and their variations, so interactive states can avoid custom CSS too.
registerFormatType (Block Editor Handbook): https://developer.wordpress.org/block-editor/reference-guides/richtext/