Page & Block Structure Guide

This guide outlines the core principles for structuring pages and creating Advanced Custom Fields (ACF) blocks within this WordPress kit. Following these standards is crucial for creating flexible, reusable, and consistent components.

Core Philosophy: Blocks are Self-Contained

The fundamental principle of this theme is that every ACF block must be a self-contained unit. This means a block should not depend on any external wrappers or containers within the main page template to control its layout, width, or spacing.

Why is this important?

• Reusability: A self-contained block can be placed on any page, in any order, without breaking its layout.
• Flexibility: It allows some blocks to be full-width (like a hero banner) while others are contained, all on the same page.
• Maintainability: Styles and logic are scoped to the block, making them easier to debug and update.

1. Page Template Structure (page.php)

Page templates like page.php should be extremely simple. Their only job is to provide the main document structure (<header>, <main>, <footer>) and render the WordPress content.

The container class (.theme-block__container) should NOT be used in the page template.

Example: page.php

<?php get_header(); ?>

<main class="main-content page">
    <?php 
    // The_content() renders the Gutenberg editor content, 
    // which is where all our ACF blocks live.
    // Notice there is NO .theme-block__container wrapping it.
    the_content(); 
    ?>
</main>

<?php get_footer(); ?>

By omitting the container here, we give each individual block the power to decide its own width.

2. ACF Block Structure

Every ACF block must include its own container. The block's outermost element (usually a <section>) will be full-width by default, and the .theme-block__container inside it will constrain the content.

The Container Utility Classes

The theme provides a flexible container system. The base class is .theme-block__container, with modifiers for different widths.

.theme-block__container {
    box-sizing: border-box;
    max-inline-size: var(--container-max); /* Default width */
    margin-inline: auto;
    padding-inline: var(--container-gutter);
    container-type: inline-size;
    container-name: block;
}

/* Modifier classes for different widths */
.theme-block__container--narrow { max-inline-size: var(--container-narrow); }
.theme-block__container--wide   { max-inline-size: var(--container-wide); }

Example: ACF Image & Content Block

In this example, the <section> element receives the block's wrapper attributes and can have a background that spans the full viewport width. The .theme-block__container is placed inside it to control the width of the actual content.

<?php
/**
 * Image and Content Block
 */

// ... (field setup and class building logic) ...

$wrapper_attrs = get_block_wrapper_attributes([
    'class' => implode(' ', $classes),
]);
?>

<!-- The <section> is the block's main wrapper. It is full-width. -->
<section <?php echo wp_kses_data( $wrapper_attrs ); ?>>

    <!-- The container is INSIDE the block to control content width. -->
    <div class="theme-block__container">

        <?php if ( ! empty( $content_html ) ) : ?>
            <div class="image-and-content__content">
                <div class="image-and-content__content-inner">
                    <?php echo wp_kses_post( $content_html ); ?>
                </div>
            </div>
        <?php endif; ?>

        <?php if ( $image_id ) : ?>
            <div class="image-and-content__image">
                <?php echo wp_get_attachment_image( $image_id, 'large' ); ?>
            </div>
        <?php endif; ?>
        
    </div>
</section>

3. Global Styling Variables (variables.scss)

All styling should leverage the global CSS variables defined in variables.scss to maintain consistency across the site. These variables are defined within the :root scope, making them available globally.

Key Variables

:root {
    // === COLORS ===
    // Use these for text, backgrounds, borders, etc.
    --c-primary: #007cba;
    --c-secondary: #d6ce5e;
    
    // === FONTS ===
    // Use for font-family properties.
    --f-family-primary: Arial, sans-serif;
    --f-family-secondary: Georgia, serif;
    --f-size-base: 16px; // The base font size for the document.

    // === BREAKPOINTS ===
    // Use in media queries for responsive design.
    --breakpoint-sm: 576px;
    --breakpoint-md: 768px;
    --breakpoint-lg: 992px;

    // === LAYOUT ===
    // These define the widths for our container classes.
    --container-max: 72rem;     /* ~1152px - Default */
    --container-narrow: 60rem;  /* ~960px */
    --container-wide: 90rem;    /* ~1440px */

    // Defines the left/right padding for containers.
    --container-gutter: clamp(1rem, 4vw, 2rem);
}

Usage Example in Block SCSS

// in _image-and-content.scss

.image-and-content {
    &__content {
        color: var(--c-primary);
        font-family: var(--f-family-primary);
    }

    // Example of a media query
    @media (min-width: var(--breakpoint-md)) {
        // styles for medium screens and up...
    }
}

Summary & Best Practices

✅ DO place .theme-block__container inside each ACF block's main wrapper.
❌ DON’T wrap the_content() in page.php (or any other template) with a container.
✅ DO make blocks fully self-sufficient.
✅ DO use the global CSS variables from variables.scss for all colors, fonts, and layout values.
❌ DON’T use hardcoded values (e.g., #007cba, 1200px) in your block's stylesheet.

By following this structure, we ensure our theme is robust, scalable, and easy for any developer to work with.