/generateblocks-layouts

GenerateBlocks Patterns

A pattern packages block structure and content for insertion. It is not a substitute for a design system. Patterns can use local styles. Add Pro Global Styles or Design Tokens only when the user opts in under styling-scope.md. Prompt before importing a pattern that would silently add those dependencies.

Choose the Reuse Model

Do not save every finished section as a pattern. A useful pattern has a clear repeat case, safe defaults, and replaceable content.

Existing local patterns: read the stored source

"Local pattern" does not identify its storage or block version. Inspect the page's raw block tree before editing:

• Inline/unsynced content is already a tree of ordinary blocks. Preserve the stored structure and change only the requested attributes/content.
• A core/block with ref points to a pattern record. Read that record's raw content to understand the blocks; do not guess them from the page reference or rendered HTML. Preserve the reference unless detaching/replacing it is requested.
• A core/pattern with slug refers to a registered pattern; resolve its actual content through the site's pattern registry rather than inventing a layout.

Reading a shared source does not authorize changing every consumer. An edit to the synced source requires that scope; a requested page-only variation needs an intentional independent copy. If the pattern source cannot be read, report the missing source rather than reconstructing it from a screenshot.

For icon headings, use the actual block name: V2's editor label Headline is a generateblocks/text variation, while generateblocks/headline is legacy. Keep the icon-bearing Text block's native .gb-shape and .gb-text sibling wrappers, icon order and rich-text formatting. Do not replace it with a generic heading or a different icon composition merely to suppress a recovery warning. See block-types.md under Icon support for native save output.

When inserting an independent copy, let the native inserter handle IDs or remap IDs together with their classes and CSS. During an in-place edit, preserve IDs. Validate the expanded block tree, label/icon content, and serialization after insertion; a successful pattern preview alone is not proof of valid saved blocks.

Before Building

Read:

• recovery-rules.md for block serialization;
• block-types.md for the blocks used;
• css-mode.md for states/selectors/at-rules;
• responsive.md for the destination breakpoint contract;
• design-quality.md when the pattern invents a visual direction.

Inspect the destination's tokens, Global Styles, block availability, and Pro version. A pattern that depends on a missing class or Pro block is incomplete.

Authoring Contract

• Use V2 block names.
• Keep styles and local compiled css aligned.
• Use the destination's native or registered at-rules.
• Keep action links as element <a> wrappers with inner text blocks.
• Use core blocks for prose, lists, tables, and captioned images where simpler.
• Use real sample content that exposes long titles and empty-state behavior; do not ship invented testimonials or metrics.
• Keep image attachments replaceable and document any required media.
• Run preflight.py on the pattern markup before registration/import.

Unique IDs

GenerateBlocks styles are coupled to uniqueId. Before inserting hand-authored markup into a known record, use its numeric post ID for new blocks. If no record exists, use one random four-digit layout scope as described in the authoring contract. Preserve existing IDs unless they collide with the destination.

For patterns inserted through the editor, verify what the installed build does with IDs during insertion/copy. Do not assume an old export's IDs are safe on a new site. After insertion, check for duplicates within the destination record and confirm every compiled selector matches its block.

Registering a PHP Pattern

Use WordPress' pattern API in a theme/plugin that owns the composition:

add_action(
    'init',
    function () {
        register_block_pattern_category(
            'project-sections',
            [ 'label' => __( 'Project Sections', 'project-textdomain' ) ]
        );

        register_block_pattern(
            'project/decision-list',
            [
                'title'       => __( 'Decision List', 'project-textdomain' ),
                'description' => __( 'A divided list for comparing concrete criteria.', 'project-textdomain' ),
                'categories'  => [ 'project-sections' ],
                'content'     => file_get_contents( __DIR__ . '/patterns/decision-list.html' ),
            ]
        );
    }
);

Keep the pattern HTML in a dedicated source file so block comments are not damaged by PHP quoting. Follow the target repo's loading convention and avoid runtime file reads if its build/package process compiles pattern files another way.

File-based patterns in block themes can instead use WordPress pattern headers. Use the target theme's established pattern structure.

Pro Pattern Library and Imports

GenerateBlocks Pro can import remote/local patterns and associated Global Styles. Before importing:

1. inventory required Pro blocks and classes;
2. compare incoming Global Style names with existing contracts;
3. preserve the destination's tokens and breakpoint strategy;
4. remove generic decorative classes that do not belong globally;
5. verify form, condition, overlay, and dynamic-data dependencies separately;
6. inspect the inserted markup, not only the preview image.

A same-named Global Style can still mean something different. Treat selector collisions as semantic conflicts.

Pro 2.8 token-aware imports

Read design-systems-beta.md before moving a token-dependent pattern. The beta can carry recursively referenced registered tokens, including responsive values. A variable that exists only in an external stylesheet is not automatically portable. Full design-system file import was tested across two local sites; a live GenerateCloud provider/consumer flow was not tested.

The bundled ../examples/beta-design-system/ includes six section exports and a native editor builder that remaps page, form, and query IDs. Its raw HTML exports retain their source-site IDs and URLs; regenerate them for a new target.

Synced Patterns

Use synced patterns only when central updates are desired. Do not sync a section whose copy, media, CTA, or query must differ per page.

Before editing a synced pattern:

• enumerate consumers;
• snapshot the pattern and affected records;
• verify every consumer after the change;
• check dynamic CSS/cache invalidation;
• preserve block IDs and dependencies unless the pattern is deliberately rebuilt.

Pattern Design Quality

Patterns amplify both good and bad choices. Reject a pattern that standardizes:

• card soup;
• 2px rounded outlines;
• pill-shaped primary CTAs;
• repeated decorative eyebrows;
• fake logo/testimonial/metric sections;
• generic gradient heroes;
• hover motion on noninteractive content;
• a desktop grid that merely stacks into a long mobile wall;
• wrapper trees with no layout or semantic ownership.

Prefer structural patterns such as:

• a divided definition list;
• a 2-column decision/evidence split;
• an accessible FAQ disclosure group when questions are real;
• a responsive query grid with an empty state;
• a focused CTA with one primary action;
• a content rail and media pair using project tokens.

Responsive Verification

• Use max-width:767px when the pattern means native GenerateBlocks Mobile on 2.4.1.
• Preserve destination custom queries rather than silently changing them.
• Verify 1025, 1024, 768, 767, 375, and one awkward tablet width.
• Confirm logical DOM/focus order, long strings, missing media, and no horizontal overflow at 200% zoom.

Delivery Checklist

• Pattern title and description explain the real use case.
• Required Pro features and Global Styles are explicit.
• All blocks and delimiters balance.
• IDs and selectors are unique in the inserted destination.
• styles and css round-trip through CSS Mode.
• Links, dynamic tags, media, and query parameters are valid.
• No thick rounded surfaces or unsupported proof.
• Pattern works with realistic content and non-ideal states.
• Import/registration source and installed result were both verified.