Block Pattern Creation

Overview

Block patterns are pre-configured arrangements of blocks that users can insert as a starting point. Patterns enable rapid page building while maintaining design consistency and best practices.

Core Principle: Patterns are registered code (PHP or block.json), composed of block markup, with metadata for discovery. They must be accessible, flexible through InnerBlocks, and use theme.json tokens.

When to Use

Use this skill when:

• Creating reusable UI components (hero sections, CTAs, testimonials)
• Registering block patterns in a theme or plugin
• Organizing patterns into categories
• Building flexible patterns with InnerBlocks
• Creating pattern transformations
• Making patterns discoverable with keywords

Symptoms that trigger this skill:

• "create pattern"
• "register pattern"
• "block pattern"
• "pattern category"
• "reusable section"
• "hero pattern"
• "CTA pattern"

When NOT to use:

• Creating individual blocks (use block development instead)
• Simple template modifications (use fse-block-theme-development)
• Reusable blocks (user-created, not registered patterns)

Pattern Registration Methods

Method 1: PHP Registration (Recommended for Themes)

File: patterns/hero.php

<?php
/**
 * Title: Hero Section
 * Slug: mytheme/hero
 * Categories: featured
 * Keywords: hero, banner, header, call to action
 * Description: A prominent hero section with heading, description, and call-to-action button.
 * Viewport Width: 1200
 */
?>

<!-- wp:cover {"url":"<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/hero-bg.jpg","dimRatio":50,"overlayColor":"primary","align":"full"} -->
<div class="wp-block-cover alignfull">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color has-background-dim"></span>
    <img class="wp-block-cover__image-background" alt="" src="<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/hero-bg.jpg" data-object-fit="cover"/>

    <div class="wp-block-cover__inner-container">
        <!-- wp:group {"layout":{"type":"constrained","contentSize":"800px"}} -->
        <div class="wp-block-group">
            <!-- wp:heading {"textAlign":"center","level":1,"fontSize":"x-large"} -->
            <h1 class="has-text-align-center has-x-large-font-size">Welcome to Our Site</h1>
            <!-- /wp:heading -->

            <!-- wp:paragraph {"align":"center"} -->
            <p class="has-text-align-center">Discover amazing content and transform your digital presence with our innovative solutions.</p>
            <!-- /wp:paragraph -->

            <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
            <div class="wp-block-buttons">
                <!-- wp:button {"backgroundColor":"secondary"} -->
                <div class="wp-block-button">
                    <a class="wp-block-button__link has-secondary-background-color has-background wp-element-button">Get Started</a>
                </div>
                <!-- /wp:button -->
            </div>
            <!-- /wp:buttons -->
        </div>
        <!-- /wp:group -->
    </div>
</div>
<!-- /wp:cover -->

File: functions.php

<?php
/**
 * Register block patterns
 */
function mytheme_register_patterns() {
    // Auto-register patterns from patterns/ directory
    // WordPress 6.0+ automatically loads PHP files from patterns/ directory
    // No additional code needed for basic registration

    // Optional: Register pattern categories
    register_block_pattern_category(
        'mytheme-featured',
        array(
            'label' => __( 'Featured', 'mytheme' ),
            'description' => __( 'Featured content patterns', 'mytheme' ),
        )
    );
}
add_action( 'init', 'mytheme_register_patterns' );

Method 2: Manual PHP Registration

For more control over registration:

<?php
function mytheme_register_hero_pattern() {
    register_block_pattern(
        'mytheme/hero',
        array(
            'title'       => __( 'Hero Section', 'mytheme' ),
            'description' => __( 'A prominent hero section with heading and CTA.', 'mytheme' ),
            'categories'  => array( 'featured', 'call-to-action' ),
            'keywords'    => array( 'hero', 'banner', 'header', 'cta' ),
            'viewportWidth' => 1200,
            'content'     => '<!-- Pattern markup here -->',
        )
    );
}
add_action( 'init', 'mytheme_register_hero_pattern' );
?>

Method 3: block.json Registration (Plugins)

File: patterns/hero/block.json

{
    "name": "myplugin/hero",
    "title": "Hero Section",
    "description": "A prominent hero section with heading and CTA.",
    "categories": ["featured"],
    "keywords": ["hero", "banner", "header"],
    "viewportWidth": 1200,
    "content": "<!-- Pattern markup in separate file -->"
}

Quick Reference

Pattern Header Fields (PHP Method)

Common Pattern Categories

Implementation Patterns

Pattern 1: Flexible Hero with InnerBlocks

Allows users to customize content:

<?php
/**
 * Title: Flexible Hero Section
 * Slug: mytheme/hero-flexible
 * Categories: featured
 * Keywords: hero, customizable, flexible
 */
?>

<!-- wp:cover {"dimRatio":50,"overlayColor":"primary","align":"full","className":"hero-pattern"} -->
<div class="wp-block-cover alignfull hero-pattern">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color has-background-dim"></span>

    <div class="wp-block-cover__inner-container">
        <!-- wp:group {"layout":{"type":"constrained","contentSize":"800px"}} -->
        <div class="wp-block-group">
            <!-- wp:heading {"textAlign":"center","level":1,"placeholder":"Add your heading..."} -->
            <h1 class="has-text-align-center">Your Heading Here</h1>
            <!-- /wp:heading -->

            <!-- wp:paragraph {"align":"center","placeholder":"Add your description..."} -->
            <p class="has-text-align-center">Add your description here.</p>
            <!-- /wp:paragraph -->

            <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
            <div class="wp-block-buttons">
                <!-- wp:button -->
                <div class="wp-block-button">
                    <a class="wp-block-button__link wp-element-button">Button Text</a>
                </div>
                <!-- /wp:button -->
            </div>
            <!-- /wp:buttons -->
        </div>
        <!-- /wp:group -->
    </div>
</div>
<!-- /wp:cover -->

Pattern 2: Two Column Feature Section

<?php
/**
 * Title: Two Column Features
 * Slug: mytheme/features-two-column
 * Categories: columns, featured
 * Keywords: features, columns, benefits
 */
?>

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"var(--wp--preset--spacing--large)","bottom":"var(--wp--preset--spacing--large)"}}},"backgroundColor":"background"} -->
<div class="wp-block-group alignfull has-background-background-color has-background" style="padding-top:var(--wp--preset--spacing--large);padding-bottom:var(--wp--preset--spacing--large)">

    <!-- wp:heading {"textAlign":"center","level":2} -->
    <h2 class="has-text-align-center">Our Features</h2>
    <!-- /wp:heading -->

    <!-- wp:columns {"align":"wide"} -->
    <div class="wp-block-columns alignwide">
        <!-- wp:column -->
        <div class="wp-block-column">
            <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
            <figure class="wp-block-image size-large">
                <img src="<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/feature-1.jpg" alt=""/>
            </figure>
            <!-- /wp:image -->

            <!-- wp:heading {"level":3} -->
            <h3>Feature One</h3>
            <!-- /wp:heading -->

            <!-- wp:paragraph -->
            <p>Description of your first amazing feature goes here.</p>
            <!-- /wp:paragraph -->
        </div>
        <!-- /wp:column -->

        <!-- wp:column -->
        <div class="wp-block-column">
            <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
            <figure class="wp-block-image size-large">
                <img src="<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/feature-2.jpg" alt=""/>
            </figure>
            <!-- /wp:image -->

            <!-- wp:heading {"level":3} -->
            <h3>Feature Two</h3>
            <!-- /wp:heading -->

            <!-- wp:paragraph -->
            <p>Description of your second amazing feature goes here.</p>
            <!-- /wp:paragraph -->
        </div>
        <!-- /wp:column -->
    </div>
    <!-- /wp:columns -->
</div>
<!-- /wp:group -->

Pattern 3: Testimonial with Quote

<?php
/**
 * Title: Testimonial Quote
 * Slug: mytheme/testimonial
 * Categories: testimonials, text
 * Keywords: testimonial, quote, review
 */
?>

<!-- wp:group {"style":{"spacing":{"padding":{"top":"var(--wp--preset--spacing--medium)","bottom":"var(--wp--preset--spacing--medium)","left":"var(--wp--preset--spacing--medium)","right":"var(--wp--preset--spacing--medium)"}},"border":{"left":{"color":"var(--wp--preset--color--primary)","width":"4px"}}},"backgroundColor":"background"} -->
<div class="wp-block-group has-background-background-color has-background" style="border-left-color:var(--wp--preset--color--primary);border-left-width:4px;padding-top:var(--wp--preset--spacing--medium);padding-right:var(--wp--preset--spacing--medium);padding-bottom:var(--wp--preset--spacing--medium);padding-left:var(--wp--preset--spacing--medium)">

    <!-- wp:quote {"className":"is-style-plain"} -->
    <blockquote class="wp-block-quote is-style-plain">
        <!-- wp:paragraph {"fontSize":"large"} -->
        <p class="has-large-font-size">"This product completely transformed how we work. Highly recommended!"</p>
        <!-- /wp:paragraph -->
        <cite>Jane Doe, CEO of Example Corp</cite>
    </blockquote>
    <!-- /wp:quote -->
</div>
<!-- /wp:group -->

Pattern 4: Call to Action Section

<?php
/**
 * Title: Call to Action
 * Slug: mytheme/cta
 * Categories: call-to-action
 * Keywords: cta, call to action, conversion, button
 */
?>

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"var(--wp--preset--spacing--large)","bottom":"var(--wp--preset--spacing--large)"}}},"backgroundColor":"primary","textColor":"background"} -->
<div class="wp-block-group alignfull has-background-color has-primary-background-color has-text-color has-background" style="padding-top:var(--wp--preset--spacing--large);padding-bottom:var(--wp--preset--spacing--large)">

    <!-- wp:group {"layout":{"type":"constrained","contentSize":"600px"}} -->
    <div class="wp-block-group">
        <!-- wp:heading {"textAlign":"center","level":2,"textColor":"background"} -->
        <h2 class="has-text-align-center has-background-color has-text-color">Ready to Get Started?</h2>
        <!-- /wp:heading -->

        <!-- wp:paragraph {"align":"center","textColor":"background"} -->
        <p class="has-text-align-center has-background-color has-text-color">Join thousands of satisfied customers today.</p>
        <!-- /wp:paragraph -->

        <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
        <div class="wp-block-buttons">
            <!-- wp:button {"backgroundColor":"background","textColor":"primary","className":"is-style-fill"} -->
            <div class="wp-block-button is-style-fill">
                <a class="wp-block-button__link has-primary-color has-background-background-color has-text-color has-background wp-element-button">Start Free Trial</a>
            </div>
            <!-- /wp:button -->
        </div>
        <!-- /wp:buttons -->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->

Common Mistakes

1. Hardcoding Colors and Spacing

WRONG:

<!-- wp:group {"style":{"spacing":{"padding":"4rem"},"color":{"background":"#0073aa"}}} -->

WHY THIS FAILS:

• Ignores theme.json design system
• Cannot be customized by users
• Breaks when theme colors change
• Not responsive to theme variations

CORRECT:

<!-- wp:group {"style":{"spacing":{"padding":"var(--wp--preset--spacing--large)"}},"backgroundColor":"primary"} -->

2. Missing Accessibility Features

WRONG:

<!-- wp:image -->
<figure class="wp-block-image">
    <img src="image.jpg"/>
</figure>
<!-- /wp:image -->

WHY THIS FAILS:

• Missing alt text for screen readers
• No semantic context
• WCAG compliance failure

CORRECT:

<!-- wp:image {"alt":"Person using laptop at modern workspace"} -->
<figure class="wp-block-image">
    <img src="image.jpg" alt="Person using laptop at modern workspace"/>
</figure>
<!-- /wp:image -->

3. Not Using Placeholder Text

WRONG:

<!-- wp:heading -->
<h1></h1>
<!-- /wp:heading -->

WHY THIS FAILS:

• Users don't know what to add
• Empty patterns look broken
• Poor user experience

CORRECT:

<!-- wp:heading {"placeholder":"Add your heading..."} -->
<h1>Your Heading Here</h1>
<!-- /wp:heading -->

4. Inflexible Patterns (No User Customization)

WRONG: Creating patterns with all content hardcoded and no way to customize.

WHY THIS FAILS:

• Users cannot adapt to their needs
• Defeats purpose of patterns (rapid customization)
• Forces users to edit markup manually

CORRECT: Use placeholder text, allow block customization, provide clear structure that's easy to modify.

5. Wrong Pattern Category

WRONG: Categorizing a hero section as "text" category.

WHY THIS FAILS:

• Users cannot find pattern
• Poor discoverability
• Inconsistent with WordPress conventions

CORRECT: Use appropriate categories:

• Hero → featured or header
• CTA → call-to-action
• Testimonials → testimonials

6. Missing Keywords

WRONG:

/**
 * Title: Hero Section
 * Slug: mytheme/hero
 */

WHY THIS FAILS:

• Poor search discoverability
• Users won't find pattern
• Relies only on title match

CORRECT:

/**
 * Title: Hero Section
 * Slug: mytheme/hero
 * Keywords: hero, banner, header, call to action, cta, featured
 */

7. Not Testing Pattern Insertion

WRONG: Creating pattern without testing in block editor.

WHY THIS FAILS:

• Markup errors not caught
• Layout breaks in editor
• Pattern won't insert

CORRECT: Test pattern insertion in:

• Block editor (post/page editor)
• Site editor (template editor)
• Different screen sizes
• Different themes (if plugin pattern)

Red Flags - Rationalization Detection

No Exceptions

NEVER skip these requirements:

1. ✅ Use theme.json tokens - Colors, spacing, typography from theme.json
2. ✅ Add alt text to images - Accessibility requirement, not optional
3. ✅ Include keywords - Minimum 3-5 relevant search terms
4. ✅ Categorize correctly - Use appropriate WordPress categories
5. ✅ Test pattern insertion - Verify it works in block editor
6. ✅ Add placeholder text - Guide users on customization
7. ✅ Use semantic HTML - Headings, lists, landmarks

Pattern Organization

Directory Structure

theme-name/
└── patterns/
    ├── hero.php
    ├── hero-video.php
    ├── features-two-column.php
    ├── features-three-column.php
    ├── testimonial.php
    ├── testimonial-grid.php
    ├── cta.php
    ├── cta-boxed.php
    ├── gallery-masonry.php
    └── footer-newsletter.php

Naming Conventions

• File names: component-variation.php (e.g., hero-video.php)
• Slugs: themename/component-variation (e.g., mytheme/hero-video)
• Titles: Human-readable with capital case (e.g., "Hero with Video Background")

Integration with This Template

This skill works with:

• fse-block-theme-development skill - Patterns are part of FSE themes
• ui-designer agent - Designing pattern layouts
• frontend-developer agent - Building advanced patterns with custom CSS/JS
• wordpress-security-hardening skill - Sanitizing pattern output

Complements:

• wp-cli-workflows skill - Automating pattern generation
• wordpress-internationalization skill - Translating pattern text

Testing Checklist

Before registering a pattern:

• Pattern inserts without errors in block editor
• Pattern uses theme.json color tokens (no hardcoded hex)
• Pattern uses theme.json spacing tokens
• All images have meaningful alt text
• Pattern has 3-5 relevant keywords
• Pattern is in appropriate category
• Placeholder text guides users on customization
• Pattern works at mobile, tablet, desktop sizes
• Semantic HTML used throughout
• Pattern maintains accessibility (keyboard nav, ARIA when needed)
• Pattern looks correct in Site Editor
• Pattern renders correctly on frontend
• Pattern works with different theme variations (if applicable)

Resources

• WordPress Block Pattern Directory
• Block Pattern Reference
• register_block_pattern() Function
• Pattern Categories
• Block Markup Reference

Skill Version: 1.0.0 Last Updated: 2026-01-18 Tested Against: WordPress 6.7+ Testing Methodology: RED-GREEN-REFACTOR (TDD for documentation)