Guides

Every guide is a delta from a section you already have — never a whole file. Find your task below and copy the shapes from its guide, not from memory. For a complete, real 12-section template to read end to end, scaffold the example workspace instead: npm create @homepages/workspace@latest my-work -- --example spw-essential.

The author loop

Every guide ends here. It is the same three steps whatever you changed:

1. Edit the section’s section.ts, Renderer.tsx or fixtures.ts (Sections and their declarations).
2. Preview with npm run dev — the page reloads on save, so you are reading your change against real fixture content rather than imagining it.
3. Check with npm run check. It is the acceptance gate: what it reports is what a submission is judged on, and every failure names a rule id you can look up.

A guide that ends “verify with the author loop” means exactly this — run all three, in order, before you move on.

Find your task

Declare slots

How do I…	Guide	What it covers
add an image slot the editor can crop	image-slot-crop.md	Add an image slot the editor crops to a fixed ratio.
give the user a closed set of choices	select-slot.md	Give the user a closed set of choices — a slot whose value is one of a vocabulary you write out or one a bound fact supplies.
add a repeating list the user edits per item (unit table, cards, gallery)	collection-slot.md	Add a repeating list whose items the editor selects and edits one at a time.
present several fields as one card in the editor	add-a-group.md	Collapse several slots into one card in the editor’s sidebar, and mark the container the editor resolves them through.

Source a slot’s value

How do I…	Guide	What it covers
fill a slot from a property fact without AI	bind-property-fact.md	Fill a slot from a known property fact, no AI.
derive a slot’s value from facts instead of having AI write it	compute-a-value.md	Derive a slot’s value from the property’s facts with a function you write, instead of copying a fact or having AI write it.
have AI write a slot’s content	fill-spec-decision.md	Have AI write a slot’s content.

Add interactivity

How do I…	Guide	What it covers
make part of a section interactive (an island)	interactive-island.md	Make part of a section interactive with a client-hydrated island.
collect contact details from a visitor (a lead form)	lead-form.md	Collect a visitor’s contact details and submit them to HomePages as a lead.
hold back content until the visitor submits the lead form	gate-behind-lead-form.md	Hold back a section’s content until the visitor has submitted your lead form.

Preview your work

How do I…	Guide	What it covers
source a fixture from a real property, not invented values	pick-a-scenario.md	Source a fixture’s slots from real property data, via defineFixtures or by the fill-by-source rule.
preview a section’s structural edge cases / states	fixture-states.md	Preview a section’s structural edge cases.
preview sections in a browser as I author them	preview-with-dev.md	Preview sections in a browser as you author them — the canvas, the live template rendering, and the render endpoints an agent can drive.

Compose a template

How do I…	Guide	What it covers
render one section two ways, decided by facts or AI and switchable by the user	add-a-variant.md	Render one section two ways, with the case seeded by facts or AI and switchable by the user unless locked.
make two composed sections agree about something	reconcile-across-sections.md	Add a cross-section rule to a template, so two composed sections stop contradicting each other.
add another template to the workspace, or a section to one	second-template.md	Add another template to the workspace, or another section to a template.
give the site a second page, and link between them	add-a-page.md	Give a template a second page — its own path and sections, with the header shared across both and a menu linking them.
stop a long, image-heavy page exhausting the browser’s raster memory	content-visibility.md	Let off-screen sections stop consuming raster memory on a long, image-heavy page — and pay the containment cost deliberately.

Organize your files

How do I…	Guide	What it covers
organize a section’s files beyond the reserved contract files	organize-section-folder.md	Structure a section’s files beyond the reserved contract files.
ship a static asset (image/svg/font) with a section	static-asset.md	Add a graphic — an icon, a divider, a photo, a font — to a section.
use a third-party npm package in a section	third-party-package.md	Use a third-party npm package in a section.

Check and submit

How do I…	Guide	What it covers
run the acceptance gate and read what it reports	run-check.md	Run the acceptance gate and read what it tells you — its toolchain, its output shape, and its JSON report.
check failed and I do not know what it wants	diagnose-a-failing-check.md	Work one check failure from red to green — what each part of a finding is for, where it points, and what the fix looks like.
package a template for submission	prepare-submission.md	Package a template for submission.
a new major kit version shipped	cross-a-kit-major.md	Move a workspace onto a new major kit version — the changelog, the install, the migration list, and the re-pack.