Zero WordPress's default root block gap in Studio Code scaffolded themes

[youknowriad]

Related issues

How AI was used in this PR

Built with Claude Code: it explored how the agent scaffolds themes and where spacing guidance lives, proposed the options, and implemented the chosen approach. Changes were human-directed and reviewed.

Proposed Changes

When the Studio Code agent builds a site, an unexpected gap often appears between the header and the content, and between the content and the footer. The agent designs those sections as self-contained bands with their own padding, but WordPress inserts margin-block-start: var(--wp--style--block-gap) between the template's top-level children — with a 24px core default that applies even when the theme never declares a block gap. The agent doesn't model that injected gap, so generated sites render with mystery spacing the design never asked for.

This PR makes reality match the agent's mental model instead of asking the agent to compensate:

• Themes created by scaffold_theme now zero that root-level gap in style.css, so top-level sections butt edge-to-edge and own their vertical rhythm through their padding. Spacing between sections becomes something the agent adds deliberately rather than something core injects silently. The reset is scoped to the template root only — block-gap behavior inside nested layouts (paragraph rhythm, flex gaps) is untouched.
• The block-content skill now explains the mechanism proactively (it was previously only mentioned in the reactive visual-polish skill), including how to handle non-scaffolded themes and why zeroing styles.spacing.blockGap in theme.json is the wrong fix (it cascades into every flow layout and collapses content rhythm site-wide).

User impact: sites generated by the Studio Code agent should come out with the header/content/footer spacing the design intended, with fewer polish iterations spent diagnosing the injected gap.

The data-liberation agent's existing per-section margin zeroing is intentionally left unchanged — its sections live inside page content where a template-root reset doesn't reach, and its fix is deterministic engine code that keeps patterns theme-agnostic.

Testing Instructions

• npm test -- apps/cli/ai/tests/tools.test.ts — includes a new assertion that the scaffolded style.css ships the reset.
• End to end: build the CLI (npm run cli:build), ask the Studio Code agent to create a new site with a custom theme, and inspect the rendered page — the header should sit flush against the first content section and the footer flush against the last, with no ~24px gap. Also worth confirming in the editor view (the reset rides add_editor_style) that the front end and editor agree.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

🤖 Generated with Claude Code

[wpmobilebot]

📊 Performance Test Results

Comparing dc2a21d vs trunk

app-size

Metric	trunk	dc2a21d	Diff	Change
App Size (Mac)	1316.83 MB	1316.83 MB	+0.00 MB	⚪ 0.0%

site-editor

Metric	trunk	dc2a21d	Diff	Change
load	1088 ms	1093 ms	+5 ms	⚪ 0.0%

site-startup

Metric	trunk	dc2a21d	Diff	Change
siteCreation	6483 ms	6504 ms	+21 ms	⚪ 0.0%
siteStartup	1854 ms	1851 ms	3 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)