Diagnosing XYZ Grid Layout Breaks in Foundation 6.x

Recognizable condition

Columns overlap, stack unexpectedly, or gutters disappear at specific breakpoints when the XYZ Grid is used. The symptom usually appears after a viewport resize or on devices with a particular pixel ratio.

Cause / diagnostic table

Observed symptom	Likely cause	Quick test
Columns overlap on medium breakpoint	Missing data-xyz-grid attribute on the grid container	Inspect the container in DevTools; attribute should be present
Gutters vanish on large screens	Custom CSS overriding .grid-x or .cell margins/padding	Disable custom stylesheet temporarily; reload
Columns stack incorrectly on small viewports	Incorrect nesting (e.g., .cell directly inside .grid-x without a row wrapper)	Validate HTML hierarchy against Foundation docs
JavaScript console shows “Foundation not initialized”	Foundation JS loaded before DOM ready or not called	Check script load order; ensure $(document).foundation() runs after DOMContentLoaded
Issue persists on latest CDN build	Known bug in the version you are using	Test with the official CDN example page

Ordered checks

1. Verify HTML structure – The grid container must have data-xyz-grid (or the appropriate class) and contain a .grid-x element that wraps .cell children. No extra wrappers between .grid-x and .cell.
2. Inspect computed styles – In Chrome/Edge DevTools, select a .cell and confirm its width matches the expected percentage for the current breakpoint (e.g., 50% for .medium-6). Look for overridden margin or padding.
3. Check browser console – Look for JavaScript errors, especially “Foundation is not defined” or “Cannot read property ‘foundation’ of undefined”.
4. Confirm Foundation JS initialization – Ensure $(document).foundation() (or Foundation.reflow()) runs after the DOM is ready. If using ES modules, import and call Foundation.init().
5. Test with a minimal example – Create a standalone HTML file that loads Foundation from the CDN (v6.7.5 or later) and includes only the XYZ Grid markup from the docs. If the minimal page works, the problem is in your project’s CSS/JS.

Fixes tied to findings

• Missing attribute / wrong nesting – Add data-xyz-grid to the outer container and restructure markup to match the required hierarchy.

  <div data-xyz-grid class="grid-container">
    <div class="grid-x">
      <div class="cell medium-6">…</div>
      <div class="cell medium-6">…</div>
    </div>
  </div>

• Conflicting custom CSS – Remove or scope the overriding rules. If you must keep them, increase specificity or use !important only as a last resort.

  /* Bad */
  .grid-x { margin: 0; }
  /* Good – scoped */
  .my-layout .grid-x { margin: 0; }

• Outdated Foundation version – Upgrade to the latest patch release.

  # Run in project root (requires write access to node_modules)
  npm install foundation-sites@latest --save

  After upgrading, rebuild your assets and clear browser cache.
• JavaScript initialization order – Move the Foundation init call to a DOMContentLoaded listener or place the script at the end of <body>.

  document.addEventListener('DOMContentLoaded', () => {
    $(document).foundation();
  });

Escalation criteria

If the layout still breaks after completing the minimal‑example test with the latest CDN build (v6.7.5+), take the following steps:

1. Create a reduced test case (CodePen, JSFiddle, or a GitHub repo) that reproduces the issue.
2. Open an issue on the Foundation GitHub repository with the test case, browser versions, and a description of the breakpoint where the failure occurs.
3. Alternatively, post the same test case on the Foundation community forum or Stack Overflow tagged foundation-6.

Verification checklist

• Open the page in DevTools, select a .cell, and confirm the computed width matches the breakpoint specification.
• Temporarily disable all custom stylesheets; reload and verify the grid renders correctly.
• Compare the rendered output side‑by‑side with the official XYZ Grid example from the Foundation documentation.

Limitations

This guide covers the XYZ Grid implementation in Foundation 6.5–6.7.x. It does not address the legacy float grid, the Flex grid, or third‑party grid plugins. Behavior may differ if you are using a custom Sass build that disables XYZ Grid features.