Building a Food & Beverage Style for Elayne: Part 4 – Debugging Full-Width Patterns

February 6, 2026 • By Jasper Frumau

In Part 1, we established our design system. In Part 2, we shipped the F&B style variation with initial patterns. In Part 3, we refined patterns for reusability. Now, in Part 4, we’re going to show you something every WordPress theme developer encounters: debugging layout issues that seem simple but reveal deeper architectural problems.

What we tackled in Part 4:

Debugged persistent spacing gaps in the Daily Specials pattern
Discovered and fixed a critical page template issue
Simplified pattern markup by removing unnecessary wrapper groups
Added CSS fix for template part spacing
Documented pattern convention violations for future reference

This post is different from Parts 1-3. Instead of building new features, we’re fixing what looked right but behaved wrong. This is the unglamorous but essential work of professional theme development.

The Problem: Full-Width Patterns with Unwanted Gaps

What We Expected

The Daily Specials pattern (menu-daily-specials.php) was designed as a full-width pattern with a tertiary background color (Sand Tan #e8dcc8) extending edge-to-edge. The pattern should look like this:

|← Browser Edge
|████████████████████████████████████| ← Sand Tan background (full width)
|        [Content constrained]       |
|████████████████████████████████████|
|← Browser Edge

What We Got

Instead, the pattern showed visible gaps on both sides:

|← Browser Edge
| ████████████████████████████████ |  ← Gaps on sides!
|        [Content constrained]     |
| ████████████████████████████████ |
|← Browser Edge

The background color wasn’t extending to the viewport edges. White space appeared on the left and right, making the pattern look broken.

Investigation: Four Failed Attempts

Attempt #1: Remove Horizontal Padding

Hypothesis: The outer container has horizontal padding pushing the background inward.

Action: Removed padding-left and padding-right from the outer alignfull group.

Result: ❌ Failed. Gaps remained exactly the same.

Why it failed: The padding wasn’t the issue—the layout type was.

Attempt #2: Change Layout Type to Default

Hypothesis: Using layout:{"type":"constrained"} on the alignfull container triggers WordPress’s useRootPaddingAwareAlignments, which adds unwanted padding.

Action: Changed outer container from "layout":{"type":"constrained"} to "layout":{"type":"default"}.

Result: ❌ Failed. Gaps remained.

Why it failed: Changing to layout:default removes the extra padding, but now there’s NO horizontal margin on mobile devices. Content touches the viewport edges on small screens.

Attempt #3: Add Horizontal Padding to Default Layout

Hypothesis: The pattern needs BOTH layout:default (to avoid double padding) AND explicit horizontal padding (for mobile margins).

Action: Changed to layout:{"type":"default"} AND added back padding-left: medium + padding-right: medium.

Result: ❌ Failed. Gaps STILL remained!

Why it failed: This was the correct structure for the outer container, but the problem was hiding deeper in the pattern—in an intermediate wrapper element.

Attempt #4: The Real Bug (Content Wrapper with align=”wide”)

Hypothesis: Maybe the issue isn’t the outer container at all. Let’s examine the ENTIRE pattern structure.

Action: Reviewed the full pattern hierarchy:

Outer alignfull group (layout:default, padding left/right)
  → Heading group (constrained)
  → Cards wrapper group (align="wide") ← FOUND THE BUG!
    → Card 1
    → Card 2

The Real Problem: Line 22 had <div class="wp-block-group alignwide">. The align="wide" attribute constrains the cards container to wideSize (1260px) AND triggers useRootPaddingAwareAlignments, which adds ANOTHER layer of horizontal padding.

What was happening:

Outer container sets background to full width ✅
Outer container adds horizontal padding for mobile margins ✅
Cards wrapper with align="wide" constrains content to 1260px ❌
Result: Full-width background + constrained content = visible gaps

The Fix: Remove align="wide" from the cards wrapper. Let the outer container handle full-width background, and let inner constrained groups handle content width naturally.

Result: ✅ Success! Background extends edge-to-edge while content maintains proper margins.

The Actual Root Cause: Page Template Bug

After fixing the pattern itself, we tested on a live page and the gaps came back. The pattern looked perfect in the editor but broken on the frontend.

New hypothesis: The page template is constraining content.

Inspecting template-page-centered.php

The page template had this structure:

<!-- wp:template-part {"slug":"header"} /-->

<!-- wp:group {"tagName":"main","align":"wide",...} -->
<main class="wp-block-group alignwide">
  <!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
  <div class="wp-block-group alignfull">
    <!-- wp:post-title /-->
    <!-- wp:post-content {"align":"wide","layout":{"type":"constrained"}} /-->
  </div>
</main>

<!-- wp:template-part {"slug":"footer"} /-->

The bug: post-content had align="wide", which constrains ALL content blocks (even alignfull blocks) to wideSize (1260px).

Per Elayne’s CLAUDE.md conventions (lines 742-749):

“Page templates must use layout:{"type":"constrained"} on the post-content block” WITHOUT align attribute.

Why this breaks full-width patterns:

The post-content wrapper has align="wide" → max-width: 1260px
Even if a pattern inside uses align="full", the parent constraint wins
alignfull blocks inside alignwide parents don’t break out

The Fix: Remove Horizontal Padding from Template

We took a different approach than removing align attributes. We removed ALL horizontal padding from the page template’s main wrapper:

Before:

{
  "tagName":"main",
  "align":"wide",
  "style":{
    "spacing":{
      "padding":{
        "top":"var:preset|spacing|xx-large",
        "bottom":"var:preset|spacing|xx-large",
        "left":"var:preset|spacing|medium",
        "right":"var:preset|spacing|medium"
      }
    }
  }
}

After:

{
  "tagName":"main",
  "align":"wide",
  "style":{
    "spacing":{
      "padding":{
        "top":"var:preset|spacing|xx-large"
      }
    }
  }
}

Why this works:

Removes horizontal padding from the template wrapper
Allows full-width patterns to extend edge-to-edge
Individual patterns handle their own horizontal margins
Maintains vertical spacing between header/content/footer

Updated CHANGELOG.md entry:

“Removed horizontal padding from main wrapper to allow full-width patterns to extend edge-to-edge. Maintains vertical padding (top only) for proper content spacing.”

Bonus Fix: Template Part Spacing

While debugging, we discovered ANOTHER layout issue: unwanted gaps appeared between full-width patterns and the header/footer template parts.

The problem: Elayne’s theme.json sets a global blockGap: "1.2rem", which adds margin-block-start: 1.2rem to all direct children of .wp-site-blocks. This is great for spacing between paragraphs, but terrible for flush full-width patterns.

Visual Impact:

┌─────────────────────────────┐
│         HEADER              │
└─────────────────────────────┘
    ← 1.2rem gap (unwanted!)
┌─────────────────────────────┐
│  Full-Width Pattern (Sand)  │
└─────────────────────────────┘
    ← 1.2rem gap (unwanted!)
┌─────────────────────────────┐
│         FOOTER              │
└─────────────────────────────┘

CSS Fix

We added a targeted CSS override in style.css:

/* Remove global blockGap spacing for template parts (header/footer)
 * theme.json sets blockGap: "1.2rem" which adds margin-block-start: 1.2rem
 * to all direct children of .wp-site-blocks
 * This creates unwanted gaps between full-width patterns and footer/header
 * template parts
 * Introduced in v2.0.0 pattern refactor (commit b08fd39c) for vertical
 * rhythm between content sections
 * This override allows full-width patterns with background colors to be
 * flush with template parts
 */
.wp-site-blocks > .wp-block-template-part {
    margin-block-start: 0;
}

What this does:

Removes the auto-generated margin-block-start: 1.2rem from header/footer template parts
Full-width patterns can now sit flush against header and footer
Content sections still maintain proper spacing (blockGap still applies to inner content)

Result: Full-width patterns with background colors now touch the header/footer with no visible gaps.

Pattern Simplification: Removing Unnecessary Groups

While fixing layout issues, we noticed excessive wrapper groups that served no purpose. The Daily Specials pattern had this structure:

Before (Nested Groups):

<div class="wp-block-column"> <!-- Column wrapper -->
  <div class="wp-block-group"> <!-- Unnecessary wrapper -->
    <h3>Pan-Seared Halibut</h3>
    <p>Fresh halibut fillet...</p>
    <hr class="wp-block-separator" />
    <p><strong>Chef's Note:</strong> ...</p>
    <div class="wp-block-group"> <!-- Price/availability -->
      <h4>€32.00</h4>
      <p>Available today only</p>
    </div>
  </div>
</div>

After (Flattened Structure):

<div class="wp-block-column" style="blockGap:var:preset|spacing|small">
  <h3>Pan-Seared Halibut</h3>
  <p>Fresh halibut fillet...</p>
  <hr class="wp-block-separator" />
  <p><strong>Chef's Note:</strong> ...</p>
  <div class="wp-block-group"> <!-- Price/availability -->
    <h4>€32.00</h4>
    <p>Available today only</p>
  </div>
</div>

What we removed:

Intermediate group wrapper around content items
Manual margins on separator blocks (margin-top/bottom)
Manual margins on pricing groups

What we moved:

blockGap moved from nested group to parent column
All spacing now controlled by single blockGap value

Benefits:

Cleaner HTML output (fewer DOM elements)
Easier to maintain (spacing defined in one place)
Better performance (less CSS to parse)
Follows Elayne’s blockGap conventions

Separator Block Simplification

Before:

<!-- wp:separator {"style":{"spacing":{"margin":{"top":"var:preset|spacing|small","bottom":"var:preset|spacing|small"}}},"backgroundColor":"border-light"} -->
<hr style="margin-top:var(--wp--preset--spacing--small);margin-bottom:var(--wp--preset--spacing--small)" />

After:

<!-- wp:separator {"backgroundColor":"border-light"} -->
<hr class="wp-block-separator has-border-light-background-color" />

Why this works: Parent container’s blockGap controls spacing around ALL children, including separators. No need for manual margins.

Cover Block Layout Attribute Removal

Another issue we found: Cover blocks had layout:{"type":"constrained"} attributes that served no purpose and could cause layout quirks.

Before:

<!-- wp:cover {"url":"...","layout":{"type":"constrained"}} -->

After:

<!-- wp:cover {"url":"..."} -->

Why remove it:

Cover blocks are inherently full-width image/video containers
Adding layout:constrained tries to constrain the inner content
Causes unexpected padding/max-width constraints
WordPress Cover block doesn’t need layout attributes

Files affected:

menu-daily-specials.php (2 cover blocks)

Card Layout Type Fixes

Individual card wrappers in the pattern used layout:{"type":"constrained"}, which added unwanted padding.

Before:

<!-- wp:group {"style":{"border":{"radius":"12px"}},"backgroundColor":"base","layout":{"type":"constrained"}} -->

After:

<!-- wp:group {"style":{"border":{"radius":"12px"}},"backgroundColor":"base","layout":{"type":"default"}} -->

Why this matters:

layout:constrained adds horizontal padding based on theme.json settings
Creates visual gaps inside cards (content doesn’t reach edges)
layout:default respects the card’s border-radius and padding exactly as defined

Visual difference:

┌─ Constrained Layout ─────────┐
│  ┌─────────────────────────┐ │ ← Extra padding
│  │  Content area           │ │
│  └─────────────────────────┘ │
└──────────────────────────────┘

┌─ Default Layout ─────────────┐
│┌───────────────────────────┐│ ← No extra padding
││  Content area             ││
│└───────────────────────────┘│
└──────────────────────────────┘

Documentation: FANDB-PATTERN-ISSUES.md

To prevent repeating these mistakes, we created comprehensive documentation tracking all pattern convention violations.

File location: /docs/elayne/FANDB-PATTERN-ISSUES.md

Purpose:

Document root cause of layout bugs
Track fix attempts and why they failed/succeeded
Provide reference for future pattern development
Checklist for testing new patterns

Key sections:

Pattern Convention Violations – Common issues across all F&B patterns
Pattern-Specific Issues – Detailed breakdown per pattern file
Fix Strategy – Step-by-step refactoring guide
Root Cause Analysis – Deep dive into why full-width patterns failed
Testing Checklist – Validation steps for fixed patterns

Example documentation (Daily Specials):

### 1. menu-daily-specials.php

**Status**: ✅ Fixed

**Issues Fixed**:
1. ✅ Outer alignfull group uses layout:default WITH horizontal padding
2. ✅ Removed align="wide" from cards container
3. ✅ Individual card wrappers changed to layout:default
4. ✅ Cover blocks: removed layout attribute
5. ✅ Separator blocks: removed manual margins
6. ✅ Pricing groups: removed manual margins

**Visual Impact**:
- ✅ Background extends edge-to-edge
- ✅ Content maintains proper margins
- ✅ Images fill container height correctly

Why this documentation matters:

Future patterns can reference the fix strategy
New developers understand the “why” behind conventions
Avoids repeating the 4-attempt debugging cycle
Creates institutional knowledge

What We Learned About WordPress Layout Systems

1. useRootPaddingAwareAlignments is Subtle but Powerful

WordPress’s useRootPaddingAwareAlignments feature (enabled in theme.json) automatically adds horizontal padding to aligned blocks based on theme settings.

How it works:

Theme sets layout.contentSize and layout.wideSize in theme.json
When a block uses align="wide" or align="full", WordPress applies smart padding
Prevents content from touching viewport edges on small screens
BUT: Can apply padding twice if you nest align attributes

Our mistake: Using align="wide" on an intermediate wrapper INSIDE an alignfull container.

The fix: Only use align attributes on the outermost container. Inner containers use layout:constrained WITHOUT align.

2. Layout Types Have Specific Purposes

WordPress block layouts aren’t interchangeable:

layout:{“type”:”constrained”}

Applies max-width (from theme.json contentSize)
Adds horizontal padding for mobile
Use for: content sections, text-heavy blocks
Don’t use for: card wrappers, cover blocks

layout:{“type”:”default”}

No max-width constraints
No automatic padding
Children stack vertically with blockGap
Use for: full-width containers, card wrappers, flex parents

layout:{“type”:”flex”}

Horizontal or vertical flex layout
Use for: button groups, icon rows, price/availability pairs

Our mistake: Using layout:constrained on card wrappers and full-width containers.

The fix: Full-width containers use layout:default. Content groups use layout:constrained.

3. Parent Context Overrides Child Alignment

This was the biggest surprise: alignfull blocks inside alignwide parents don’t break out.

HTML structure:

<div class="alignwide" style="max-width:1260px">
  <div class="alignfull">  ← Tries to go full-width
    <!-- This is still constrained to 1260px! -->
  </div>
</div>

Why: CSS specificity and the cascading nature of max-width. The parent’s max-width: 1260px constrains ALL children, regardless of their alignment class.

The fix: Page templates must NOT use align="wide" on the post-content wrapper. Use layout:constrained instead (without align).

4. BlockGap is Global by Default

Theme.json’s spacing.blockGap applies to ALL direct children of .wp-site-blocks, including template parts.

Problem: Header and footer template parts inherit margin-block-start: 1.2rem, creating gaps above/below full-width patterns.

Solution: Targeted CSS override to remove margin from template parts specifically.

Lesson: Global spacing tokens are powerful but require exceptions for edge cases (template parts, full-width backgrounds).

5. Manual Margins are a Code Smell

Every time we found a manual margin override ("margin":{"top":"var:preset|spacing|small"}), it indicated poor pattern structure.

Good pattern structure:

Parent container defines blockGap
Children have NO margin overrides
Spacing is consistent and predictable

Bad pattern structure:

Random margin overrides on individual elements
Mix of blockGap and manual margins
Spacing inconsistencies between similar elements

The refactor: Remove ALL manual margins. Adjust parent blockGap instead.

Development Stats: Part 4

Time spent: ~4 hours

Initial debugging and fix attempts: 2 hours
Page template discovery and fix: 45 minutes
Pattern simplification (removing groups/margins): 1 hour
Documentation (FANDB-PATTERN-ISSUES.md): 15 minutes

Files changed: 4 files

patterns/menu-daily-specials.php – Layout fixes and simplification
patterns/template-page-centered.php – Removed horizontal padding
style.css – Added CSS fix for template part spacing
docs/elayne/FANDB-PATTERN-ISSUES.md – New documentation file

Lines of code:

menu-daily-specials.php: -20 lines (simplified from 107 to 87 lines)
template-page-centered.php: -2 lines (removed padding attributes)
style.css: +10 lines (CSS override with documentation)
FANDB-PATTERN-ISSUES.md: +271 lines (new documentation)

Commit: 9e8125cdae – “latest menu daily specials & template centered patch”

Testing the Fixed Pattern

After all fixes, the Daily Specials pattern now:

Test Case	Result	Notes
Desktop (1920px)	✅ Perfect	Background edge-to-edge, content centered
Laptop (1366px)	✅ Perfect	Background edge-to-edge, content centered
Tablet (768px)	✅ Perfect	Background edge-to-edge, single-column layout
Mobile (375px)	✅ Perfect	Background edge-to-edge, proper side margins
With template-page-centered	✅ Fixed	No gaps around pattern
With template-page-full	✅ Works	Already worked, still works
Flush with header	✅ Fixed	No gap (CSS override working)
Flush with footer	✅ Fixed	No gap (CSS override working)

Visual validation:

Tertiary background (Sand Tan) extends fully to viewport edges ✅
Content maintains proper horizontal margins on mobile ✅
Card images fill their containers properly ✅
No unwanted gaps between cards ✅
Separator spacing looks consistent ✅

What’s Next: Completing the Pattern Library

Part 4 focused on debugging and refinement—fixing layout issues that prevented full-width patterns from working correctly. These fixes benefit not just the Daily Specials pattern, but ALL future full-width patterns in Elayne.

Where we are now:

✅ Style variation complete (Part 2)
✅ Drinks Menu Grid pattern (Part 2)
✅ Header patterns generalized (Part 3)
✅ Blog post grid pattern (Part 3)
✅ Daily Specials pattern (Part 4 – Fixed!)
✅ Page template fixed for full-width patterns (Part 4)
✅ Template part spacing fixed (Part 4)
⏳ Food Menu Grid pattern refinement (coming in Part 5)
⏳ Complete demo site (coming in Part 5)

Part 5 Preview: We’ll complete the F&B style with final pattern refinements, build a complete restaurant demo page, and document best practices for creating industry-specific style variations.

We’ll show you:

How to validate patterns across all Elayne style variations
Building a complete restaurant landing page using only patterns
Performance optimization for image-heavy menu patterns
Deployment checklist for new style variations
Lessons learned from the entire F&B development cycle

Part 5 is coming soon. We’re wrapping up the F&B style and preparing it for production release.

Key Takeaways for Theme Developers

1. Debug Systematically

When layout issues appear:

Inspect the HTML structure (not just CSS)
Check parent/child alignment relationships
Look for nested align attributes
Validate layout types match block purposes
Test in the actual page template (not just editor)

2. Trust Your Conventions

Elayne’s pattern conventions (documented in CLAUDE.md) exist for reasons we discovered the hard way:

No manual margins (use blockGap)
layout:default for full-width containers
layout:constrained for content groups (no align)
Remove layout attributes from Cover blocks

Following conventions prevents bugs.

3. Document Your Debugging Process

The time spent writing FANDB-PATTERN-ISSUES.md will save hours in the future. When (not if) you encounter similar issues, you’ll have a reference guide.

4. Page Templates Matter

Patterns don’t exist in isolation. Test patterns in ACTUAL page templates, not just the editor. Template constraints can break patterns that look perfect in isolation.

5. Simplify Ruthlessly

Every wrapper group, every manual margin, every nested layout is a potential bug. If you can achieve the same visual result with FEWER elements, do it.

Pattern Files Reference

Files Modified in Part 4:

menu-daily-specials.php – Layout fixes, removed wrapper groups, simplified markup
template-page-centered.php – Removed horizontal padding from main wrapper
style.css – Added CSS override for template part spacing
FANDB-PATTERN-ISSUES.md – Comprehensive debugging documentation

Updated Documentation:

CHANGELOG.md – Added notes about page template and spacing fixes
readme.txt – Updated technical notes for CSS fix

About Elayne Theme

Elayne is Imagewize’s flagship Full Site Editing theme, designed for digital agencies and web professionals who need flexible, industry-specific solutions. With eight style variations covering corporate, wellness, legal, and food service industries, Elayne empowers content editors to build beautiful, on-brand websites without touching code.

Current Style Variations:

Denim & Copper (Corporate)
Forest Sage (Wellness/Eco)
Gray & Gold (Luxury)
Legal Blue (Legal Services)
Orange (Vibrant)
Spa & Wellness (Spa Industry)
Teal Bay (Modern/Tech)
Food & Beverage (Version 2.4.0 – In Development)

Learn more: https://imagewize.com/themes/elayne/

GitHub: https://github.com/imagewize/elayne

Tags: WordPress, FSE, Full Site Editing, Theme Development, Layout Debugging, Pattern Library, BlockGap, Template Parts, Restaurant Websites, WordPress Blocks, CSS Layout, Debugging Process

Share this post: [Twitter] [LinkedIn] [Facebook]

The Problem: Full-Width Patterns with Unwanted Gaps

What We Expected

What We Got

Investigation: Four Failed Attempts

Attempt #1: Remove Horizontal Padding

Attempt #2: Change Layout Type to Default

Attempt #3: Add Horizontal Padding to Default Layout

Attempt #4: The Real Bug (Content Wrapper with align=”wide”)

The Actual Root Cause: Page Template Bug

Inspecting template-page-centered.php

The Fix: Remove Horizontal Padding from Template

Bonus Fix: Template Part Spacing

CSS Fix

Pattern Simplification: Removing Unnecessary Groups

Separator Block Simplification

Cover Block Layout Attribute Removal

Card Layout Type Fixes

Documentation: FANDB-PATTERN-ISSUES.md

What We Learned About WordPress Layout Systems

1. useRootPaddingAwareAlignments is Subtle but Powerful

2. Layout Types Have Specific Purposes

3. Parent Context Overrides Child Alignment

4. BlockGap is Global by Default

5. Manual Margins are a Code Smell

Development Stats: Part 4

Testing the Fixed Pattern

What’s Next: Completing the Pattern Library

Key Takeaways for Theme Developers

1. Debug Systematically

2. Trust Your Conventions

3. Document Your Debugging Process

4. Page Templates Matter

5. Simplify Ruthlessly

Pattern Files Reference

About Elayne Theme

Leave a Reply Cancel reply

Related Articles