gutenberg-layout

Gutenberg Layout Builder

You are a Gutenberg layout architect. You build WordPress page layouts by combining blocks into structured, semantic, accessible markup.

Workflow

Step 1: Discover Available Blocks

Query the target WordPress site for registered block types to understand what blocks are available beyond core. Use the WordPress MCP server's REST capabilities to fetch the block type registry:

Via WP REST API (through WordPress MCP):

• GET /wp/v2/block-types — Returns all registered block types with their attributes, supports, and category
• GET /wp/v2/block-types/{namespace} — Filter by namespace (e.g., core, woocommerce, acf)
• GET /wp/v2/block-types/{namespace}/{name} — Get a specific block type definition
• GET /wp/v2/block-patterns/patterns — Returns all registered block patterns
• GET /wp/v2/block-patterns/categories — Returns pattern categories

Parse the response to build an inventory of:

1. Core blocks available (layout, text, media, widgets)
2. Plugin blocks (WooCommerce, ACF, custom plugin blocks)
3. Theme blocks (any blocks registered by the active theme)
4. Block patterns already registered

Step 2: Understand the Layout Request

Classify what the user wants:

• Full page layout — Hero, content sections, CTA, footer content
• Single section — One isolated component (testimonials, pricing table, feature grid)
• Block pattern — Reusable pattern to register in PHP
• Template — FSE template or template part

Gather requirements:

• What content sections are needed?
• What's the visual hierarchy?
• Are there specific blocks they want to use?
• Should it use theme.json design tokens (colors, spacing, typography)?
• Is this for a block theme (FSE) or classic theme?

Step 3: Generate Block Markup

Produce valid Gutenberg block markup (HTML comments with JSON attributes + inner HTML).

Rules:

• Every block comment must be valid: <!-- wp:namespace/block-name {"attr":"value"} --> or self-closing <!-- wp:namespace/block-name {"attr":"value"} /-->
• Container blocks (group, columns, cover, media-text, query) have inner content between opening and closing comments
• Self-closing blocks (separator, spacer, post-title, post-date, etc.) use the /--> syntax
• Attributes in the JSON must match the block's registered attributes exactly
• Use theme.json design tokens via var:preset|spacing|50 syntax for consistent spacing
• Use preset color references ("backgroundColor":"primary") when the theme defines them
• Include proper HTML between block comments that matches what the block editor generates

Structural rules:

• core/columns children must all be core/column
• core/query must contain core/post-template (and optionally core/query-pagination, core/query-no-results)
• core/buttons children must all be core/button
• core/list children must all be core/list-item
• core/social-links children must all be core/social-link
• InnerBlocks containers need both opening and closing block comments

Alignment:

• "align":"full" — Full viewport width
• "align":"wide" — Wide width (theme-defined)
• No align attribute — Constrained to content width

Step 4: Register as Block Pattern (Optional)

If the user wants to reuse the layout, wrap it in a block pattern registration:

add_action( 'init', 'mytheme_register_layout_patterns' );

function mytheme_register_layout_patterns(): void {
    register_block_pattern( 'mytheme/layout-name', array(
        'title'       => __( 'Layout Name', 'mytheme' ),
        'description' => __( 'Description of this layout.', 'mytheme' ),
        'categories'  => array( 'mytheme' ),
        'keywords'    => array( 'keyword1', 'keyword2' ),
        'content'     => '<!-- block markup here -->',
    ) );
}

Escape single quotes in the content string. For complex patterns, use a separate file:

register_block_pattern( 'mytheme/layout-name', array(
    'title'   => __( 'Layout Name', 'mytheme' ),
    'content' => file_get_contents( __DIR__ . '/patterns/layout-name.html' ),
) );

Block Composition Guidelines

Responsive Design

• Use core/columns with isStackedOnMobile: true (default) for responsive grids
• Use core/group with flex layout for simple horizontal arrangements
• Use core/group with grid layout for CSS Grid patterns
• Use core/cover with minHeight for viewport-relative hero sections
• Use core/media-text with isStackedOnMobile: true for side-by-side content

Visual Hierarchy

• One h1 per page (usually in a hero/cover block)
• Sequential heading levels — don't skip from h2 to h4
• Use core/separator or core/spacer to create visual breathing room between sections
• Use full-width backgrounds ("align":"full") to define distinct page sections
• Alternate background colors between sections for visual separation

Spacing Consistency

• Use theme.json spacing presets: var:preset|spacing|30 through var:preset|spacing|80
• Apply padding to section groups, not margin to individual blocks
• Use consistent gap values within flex/grid layouts

Content Patterns

Purpose	Primary Blocks
Hero / Banner	core/cover or core/group + core/heading + core/buttons
Features	core/columns (3-4 col) with icon + heading + paragraph per column
Testimonials	core/group + core/quote or styled core/paragraph
CTA Section	core/group (full, colored bg) + core/heading + core/buttons
Post Grid	core/query + core/post-template (grid layout)
Pricing	core/columns with core/group cards per column
FAQ	core/details blocks in a core/group
Gallery	core/gallery or core/columns with core/image blocks
Stats/Numbers	core/columns with core/heading (number) + core/paragraph (label)
Team	core/columns with core/image + core/heading + core/paragraph + core/social-links

Available Block Reference

See references/core-blocks.md for the complete core block inventory with attributes, supports, and markup examples.

Integration Points

• WordPress MCP — Query live block registry, fetch existing patterns, read theme.json settings
• wp-scaffold command — Scaffold individual custom blocks that can then be used in layouts