visual-polish

1. Enumerate every section and component of the page (from the page markup you wrote, or by inspecting the top-level containers).
2. If you can view images, take one take_screenshot with viewport: "all" (desktop + mobile). A model that cannot view images skips this step: inspect_design is then the whole diagnosis, so the sweep below must be complete rather than guided by what looks wrong.
3. Go section by section. For each, call inspect_design on the relevant selectors and compare the rendered DOM and computed styles against your intent and the theme's style.css (read it). The screenshot is the symptom; inspect_design is the cause — never diagnose from the screenshot alone, because subtle issues like doubled button padding barely show in pixels. Inspect even sections that look roughly right, and always inspect:
   • the header and footer template parts — for padding-left/padding-right on the bar; a part whose root group is not layout: constrained (and has no constrained inner group) gets no gutter, and its text touches the viewport edge,
   • every section wrapper — for width and centering,
   • every button — BOTH .wp-block-button and .wp-block-button__link, with includeHover: true.
   • every block that paints its own box (background, border, shadow — cards, panels, tinted sections) and every non-constrained full-width section — for padding-left/padding-right, which must not be 0px when the box holds text.
   • every inset box — a block that is rounded, bordered, or narrower than its container and paints its own background — for the edges it meets: compare its boundingBox with the neighbouring header, footer, or section, because an inset box must not sit directly against a hard edge such as the footer's border. Full-bleed bands are meant to sit flush; leave them alone.
4. List the complete set of issues before fixing anything — a concise checklist, one short line per issue: the section, the root cause from the DOM, and the exact fix (file, selector, change). A list, not prose.

Do not make a single edit until you have diagnosed every section and listed every issue. A complete diagnosis is the gate into Phase 2.

Work through the plan with targeted Edit calls (one Write/Edit per turn, per the system prompt cadence — never batch files into one turn). Do not screenshot between edits. If an edit changes block markup (not just CSS), re-run validate_blocks on that file and re-check its diff, since the serializer can change classes again.

After the whole batch, take one viewport: "all" screenshot — or, when you cannot view images, re-run inspect_design on the selectors you changed. Check each plan item off and look for regressions the fixes introduced.

This looping phase applies to the home page only (see "Scope" above). For every other page — including WooCommerce pages — stop after this single verification pass; do not loop. For the home page, each pass is expensive, so cap the cycle at 5 passes. If issues remain and you are within that budget, return to Phase 1 for what's left — re-diagnose the remaining issues with inspect_design, don't fix blind.

Symptom: a section meant to be full-width renders in the narrow content column; a section is wider/narrower than intended; or a section's content sits off-center instead of centered.

Inspect the section wrapper. Check boundingBox (x and width) against viewportWidth, and read the ancestors chain plus the margin-left/margin-right computed values. WordPress constrains children of constrained-layout containers via .is-layout-constrained > *:not(.alignfull):not(.alignwide), which custom CSS like width: 100% cannot override — and a constrained layout is also what centers inner content (via auto inline margins). For a full-width section with centered content, the outer group needs {"align":"full","layout":{"type":"constrained"}}. When width or centering is wrong, the cause is the align/layout on the block markup (or custom margins/widths fighting the layout) — fix it in the markup, not by forcing width or margins in CSS.

That markup fix only works if the theme declares a content width. If a constrained section still spans the full container after you set it, check the theme's theme.json for settings.layout.contentSize — with no contentSize and no wideSize, WordPress emits no max-width at all for constrained layouts and the block markup cannot fix it. Declare the widths in theme.json, not per-section max-width in CSS.

Symptom: a button looks too big (doubled padding), its background/border/radius is wrong, or it has two conflicting hover effects.

The button block is two nested elements: the .wp-block-button wrapper and, inside it, the .wp-block-button__link — the actual <a>/<button>, also carrying .wp-element-button. WordPress core applies the button's padding, background, border, and radius to the inner .wp-block-button__link / .wp-element-button, NOT the wrapper. Your CSS must target that same inner element so it overrides the default instead of stacking a second padded box on the wrapper.

The common trap: a custom className on a button block lands on the wrapper (.wp-block-button.your-class), not the link. So .your-class { padding … } styles the wrapper, on top of WP's default padding on the inner link — doubled box. Descend to the inner element instead: .your-class .wp-element-button.

For global button styling (consistent buttons site-wide), target .wp-element-button in style.css. WordPress puts that class on the inner styled element of every button — the button block and buttons from other blocks (search, file, etc.) — so one rule covers them all and overrides cleanly.

Inspect BOTH selectors with includeHover: true and compare their computed styles:

• If padding/background/border is set on BOTH the wrapper and the link, the button renders with doubled padding and looks too big — remove that styling from the wrapper (or its custom class) and put it on .wp-element-button / .wp-block-button__link.
• There must be exactly ONE hover rule, on the inner element (.wp-element-button:hover or .wp-block-button__link:hover), never the .wp-block-button wrapper. If both have hover styles you get two conflicting hover effects — delete the wrapper hover. Use the hover block in the inspect output to confirm only the inner element changes.

Symptom: copy sits flush against the edge of a card, a tinted panel, a bordered box, or the window — most visible on mobile.

Inspect the box and read padding-left/padding-right. WordPress pads only full-width constrained groups (the root gutter via .has-global-padding) and zeroes it on constrained groups nested inside them; a group, column, or cover with its own background or border gets no padding, and neither does a full-width section with a default, flex, or grid layout. Fix it by giving the block's class horizontal padding in style.css (reuse var(--wp--style--root--padding-left) for a section gutter) or by moving the text into a constrained inner group — never with margins on the text blocks.

The header is the usual victim: rewriting parts/header.html from scratch tends to drop the scaffold's outer {"layout":{"type":"constrained"}} group, leaving a flow or flex group that gets no gutter, so the site title sits at x: 0. Restore the constrained wrapper in the part's markup rather than padding the bar in CSS.

Symptom: a rounded or bordered card is the first or last section and its edge lands directly on the footer's top border or the header's bottom edge, with no breathing room.

Inspect the box and its neighbour and compare their boundingBox values: equal edges with no gap is the fault. Scaffolded themes zero the gap between the template's top-level blocks and let sections own their rhythm, which is right for full-bleed bands but leaves an inset box touching whatever follows it. Give that section (not the text inside it) bottom or top spacing, or close the page on a full-bleed band instead. Do not add spacing to full-bleed sections — they are meant to sit flush.

Symptom: gaps between paragraphs, headings, or sections are larger or smaller than the CSS suggests.

Vertical rhythm is owned by WordPress layout CSS, not your margins: :where(.is-layout-flow) > * + * applies margin-block-start: var(--wp--style--block-gap). Inspect the container and the adjacent blocks — read customProperties["--wp--style--block-gap"] and the margin-top/margin-bottom computed values. If block-gap is fighting your margins, set spacing through theme.json spacing.blockGap or the block's own spacing, or override knowing that exact selector.

Symptom: a column or grid cell background doesn't appear, doesn't fill the cell, or sits on the wrong element.

Inspect .wp-block-column (or the grid cell) and any inner core/group you put the background on. Check which node's background-color/background-image is set and whether its boundingBox actually fills the cell. A background on an inner group only covers its content height; to fill the cell, the color belongs on the column/cell node. Columns are flex items — confirm align-items/stretch behavior matches intent.