Problem
In mode A (modes/component-or-section.md) and mode B (modes/existing-site.md), the scaffolded local preview is a standalone shell — templates/page-template.html with the component dropped into a bare <main>. When the component is destined for an existing exported page, this shell preview does not reflect reality:
- The component renders without the real site's CSS cascade, fonts, nav, hero, and footer around it.
- Spacing/contrast/visual-rhythm decisions made against a blank shell are wrong once pasted into the live page (the surrounding sections change everything).
- The author can't see the actual seam between the new section and the sections above/below it until after the Webflow paste — the most expensive place to discover a problem.
The skill already says "test locally by opening the HTML in a browser," but the HTML being tested isn't representative for the existing-page case.
Proposed enhancement
Make the local preview, for any component targeting an existing page, be a copy of that real exported page with the component injected between explicit build markers:
<!-- BUILD:COMPONENT:START -->
<section class="my-component"> ... </section>
<!-- BUILD:COMPONENT:END -->
- Site CSS/JS/images are referenced back into the existing export folder via relative paths; the component's own
component.css / component.js stay local to its folder.
_build.py exports only the marked region to the .webflow.* files. If the markers are absent (true standalone component, no target page), it falls back to the current whole-<body> extraction + chrome/script stripping. This is backward compatible.- No preview copy is left inside the canonical export folder — the real export stays untouched until the manual Webflow paste.
Result: local preview is pixel-identical to the final Webflow output in real page context, including the seams with adjacent sections, with zero extra steps for the author.
Suggested implementation
-
templates/_build.py — add marker-aware extraction to build_html():
COMPONENT_START = "<!-- BUILD:COMPONENT:START -->"
COMPONENT_END = "<!-- BUILD:COMPONENT:END -->"
def build_html(rename_map):
raw = _read(SRC_HTML)
if COMPONENT_START in raw and COMPONENT_END in raw:
body = raw.split(COMPONENT_START, 1)[1].split(COMPONENT_END, 1)[0]
else:
# ... existing <body> extraction + preview-spacer/script strip ...
body = body.strip() + "\n"
# ... unchanged from here ...
-
modes/component-or-section.md and modes/existing-site.md — in the scaffold step, add a branch:
- Targeting an existing exported page? → copy that page to
<component>/index.html, fix the asset paths to point back at the export folder, wrap the insertion point in the two markers.
- Truly standalone (no target page)? → keep the current
page-template.html shell.
-
templates/page-template.html — add the two marker comments around the example section, and a one-line note explaining the build extracts only the marked region.
-
reference/webflow-designer-checklist.md — note that local preview now equals final output in context, so the post-paste visual diff should be minimal; any difference points at a Footer-Code/asset-relink gap rather than a layout surprise.
Why it matters
This is the single highest-leverage DX fix for the existing-site workflow: it moves the "does this actually look right next to the real hero/footer?" feedback loop from after the Webflow paste (expensive, slow, error-prone) to the local browser refresh (instant, free). It also removes a class of bugs where authors leave stray preview files inside the canonical export.
Origin
Surfaced while shipping a Thank-You-page Instagram section into an existing exported Webflow site (Britus Education / Sheffield, Task 3). Implemented locally as the convention documented in that project's CLAUDE.md; proposing it upstream so every existing-site conversion benefits.
Problem
In mode A (
modes/component-or-section.md) and mode B (modes/existing-site.md), the scaffolded local preview is a standalone shell —templates/page-template.htmlwith the component dropped into a bare<main>. When the component is destined for an existing exported page, this shell preview does not reflect reality:The skill already says "test locally by opening the HTML in a browser," but the HTML being tested isn't representative for the existing-page case.
Proposed enhancement
Make the local preview, for any component targeting an existing page, be a copy of that real exported page with the component injected between explicit build markers:
component.css/component.jsstay local to its folder._build.pyexports only the marked region to the.webflow.*files. If the markers are absent (true standalone component, no target page), it falls back to the current whole-<body>extraction + chrome/script stripping. This is backward compatible.Result: local preview is pixel-identical to the final Webflow output in real page context, including the seams with adjacent sections, with zero extra steps for the author.
Suggested implementation
templates/_build.py— add marker-aware extraction tobuild_html():modes/component-or-section.mdandmodes/existing-site.md— in the scaffold step, add a branch:<component>/index.html, fix the asset paths to point back at the export folder, wrap the insertion point in the two markers.page-template.htmlshell.templates/page-template.html— add the two marker comments around the example section, and a one-line note explaining the build extracts only the marked region.reference/webflow-designer-checklist.md— note that local preview now equals final output in context, so the post-paste visual diff should be minimal; any difference points at a Footer-Code/asset-relink gap rather than a layout surprise.Why it matters
This is the single highest-leverage DX fix for the existing-site workflow: it moves the "does this actually look right next to the real hero/footer?" feedback loop from after the Webflow paste (expensive, slow, error-prone) to the local browser refresh (instant, free). It also removes a class of bugs where authors leave stray preview files inside the canonical export.
Origin
Surfaced while shipping a Thank-You-page Instagram section into an existing exported Webflow site (Britus Education / Sheffield, Task 3). Implemented locally as the convention documented in that project's
CLAUDE.md; proposing it upstream so every existing-site conversion benefits.