Page hierarchy and sections

The Page Composition workspace is the top-level page composition planner. Its Section library pane and Page hierarchy pane sit side by side so reusable structures can be created, organised, and dragged directly onto pages. It is not a detailed page builder.

Reusable definitions live in the Section library pane. Their global labels and shared implementation context remain stable, while each placed instance can be renamed in Page hierarchy to describe its role on that page—for example, Two Column Content - Business Services can still reference the global Two Column Content definition.

Every Page node from Structure appears as a page card. Imported AI pages also create hidden Page Hierarchy route-card copies so the hierarchy is populated immediately after import.

Build the Sections library

Every section is reusable by default. Create it in Sections, create it from a Page Hierarchy add menu, or select a preset on a page; each path creates or reuses one canonical library definition.

Each reusable section includes:

• A stable global name, such as Top Nav, Footer, or Two Column Content.
• An abstract preset thumbnail.
• Shared purpose and implementation notes.
• Composition and reuse tags.
• A library-specific workflow status color.
• An instance count showing how many page placements reference it.

Drag sections to reorder the library. Add divider rows to create labelled groups such as Navigation, Content, and Case Studies. A grouped definition keeps the divider's stable groupId in JSON, so imports and later revisions retain the organisation.

Library cards keep their shared structure visible in one compact layout: a 4:3 thumbnail beside the reusable title and context, with tags spanning the full content width below. A narrow utility rail holds the single drag handle, usage count, and definition status swatch.

The row grip is the single movement control. Drop it within the library to reorder the definition, or drag it onto a Page hierarchy card to place a linked copy.

Use shortcut 1 while the pointer is over the Section library pane to open the section preset picker. Use shortcut 2 to add a divider. Over the Page hierarchy pane, shortcut 1 opens the page picker.

Changing a reusable section's name, notes, tags, or abstract pattern updates linked page instances. Changing its library status does not change the status of any Page Hierarchy instance.

Deleting a reusable section or divider requires two clicks. The first click arms the row briefly; click again to confirm. Deleting a reusable section removes it from the library and detaches linked instances as local page sections.

Page cards

Each card represents one page or route. Cards show:

• The page name.
• The number of planned sections.
• Section order from top to bottom.
• Completion progress for sections tagged green.
• The linked library definition name, or a Legacy marker for older embedded data.

New page cards place left to right and wrap after six cards. If you drag a card manually, Skafold preserves that manual position instead of recalculating it on the next import or reload.

Add section patterns

Use the add-section control on a page card or between existing sections to insert a section at the exact point it belongs. Choosing an existing library definition adds another placement. Choosing a new preset creates its library definition automatically; selecting that preset again reuses the existing definition instead of creating numbered duplicates.

Patterns are abstract structure hints, not final UI components. They help communicate broad composition:

• Full width sm, Full width md, Full width lg, Full width xl
• 2 cards row, 3 cards row, 4 cards row, 5 cards row
• 2 columns, 2 columns 1:2, 2 columns 2:1, 2 columns 3:5
• 3 columns, 4 columns, 5 columns
• Grid patterns such as 2 x 1 grid, 3 x 2 grid, and 3 x 5 grid

Use compact card rows for shallow strips of cards. Use grid patterns for square or multi-row compositions. Use full-width sizes to indicate vertical weight, from a thin strip through a large hero-like band.

Section names

The section name communicates purpose. Prefer recognised names when one fits:

• Top Nav
• Hero
• Features
• Cards
• Product Grid
• CTA
• FAQ
• Contact Form
• Footer

Use a custom name only when the section has genuinely project-specific behavior. Avoid using the name to carry all implementation detail; use notes and tags for that.

Notes and composition tags

Edit notes, tags, presets, and build guidance on the canonical definition in Sections. Page Hierarchy intentionally keeps only the independent placement title and content workflow status.

Use notes for the section's purpose and handoff context:

Compare the three service tiers and route visitors to the relevant enquiry path.

Use composition tags for quick implementation cues:

• Content: title, eyebrow, summary, price, author
• Media: background image, video, gallery, icon
• Structure: grid with cards, card row, split content, accordion
• Controls: search, filter, sort, pagination
• Actions: primary cta, add to cart, submit
• States: empty state, loading state, validation message

Tags are intentionally lightweight. They should help the handoff without turning the planner back into a long form.

Workflow status colors

Select the status circle in the library card's utility rail to open its color palette. Choose a color to make workflow state visible at a glance, or clear the color when no status is needed. The palette closes after a selection, when you click elsewhere, or when you press Escape.

The suggested meanings are intentionally flexible:

• Blue: work in progress.
• Purple: review or signoff.
• Amber: needs attention.
• Red: blocked.
• Green: complete.

No explicit status is treated as not started.

Only green counts toward the page-level completion rollup. The other colors remain flexible visual tags, so a team can adapt them to its own stages without changing the page model.

Status is intentionally isolated by context. A reusable definition has its own status in Sections, while every placed page instance has its own status in Page Hierarchy. This lets a team track the shared structure through design, build, and approval while separately tracking page-specific content or implementation readiness.

Reusable-by-default sections

All sections use the same reusable model, whether they currently appear once or many times. Typical repeated definitions include:

• Top navigation
• Footer
• Announcement bar
• Repeated CTA
• Shared product teaser
• Reused service proof block

The stable name, notes, tags, structure pattern, and build guidance come from the library definition. A placement can have a page-specific title without renaming that definition—for example, Two Column Content - Business Services can reference Two Column Content.

Older embedded sections continue to display with a Legacy marker. New sections are always linked, and import/export promotes page-only legacy definitions without merging records by name.

What gets exported

Sections.md includes reusable section names, structures, shared notes, tags, build guidance, library workflow status, and usage counts.

Page Layouts.md includes:

1. Page names and route paths where available.
2. Ordered section names.
3. Library-definition references.
4. Page-specific workflow status color and its suggested meaning.

Skafold JSON round-trips canonical definitions, divider groups and groupId, lightweight page placements, globalSectionId, page-specific instanceName, and independent library/placement status colors.

What to avoid

• Do not model every component prop.
• Do not use tags as a replacement for notes.
• Do not create duplicate definitions when an existing component is the same reusable structure.
• Do not treat the abstract pattern as pixel-perfect design.
• Do not leave imported sections unreviewed before handoff.

The goal is enough structure and context to guide implementation without recreating a full CMS schema or design system inside Page Hierarchy.