# Gutenberg Layout

> This skill should be used when the user asks to "build a Gutenberg layout", "create a page layout", "design a WordPress page", "generate block markup", "build a landing page in Gutenberg", "create a block pattern layout", "design a section layout", "generate Gutenberg HTML", or mentions "gutenberg layout", "block layout", "page builder", "block pattern", "WordPress page design", "section layout", "full site editing layout". Provides Gutenberg layout generation by discovering available blocks on a WordPress site (via WordPress MCP), then producing valid block markup.

- Skill: `iwritec0de/gutenberg-layout` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add iwritec0de/gutenberg-layout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iwritec0de/gutenberg-layout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: iwritec0de (https://skillmd.com/u/iwritec0de)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iwritec0de/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:

```php
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:

```php
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