Augmenting Existing Pages

The Problem with compose_page on Real Projects

compose_page is designed for greenfield pages. It returns an ordered set of sections from scratch — ideal when starting fresh.

But most real scenarios look different: you have a navbar, a hero, and one or two content sections already. Calling compose_page will still suggest a navbar and hero — sections you don’t need.

The result: a generic list that ignores what’s already there, with no alternatives, no creative options, and no sense of what’s actually missing.

The Solution: augment_page

augment_page takes your existing sections as input and only fills the gaps.

augment_page(
  existing_sections: ["navbar", "hero", "services"],
  domain: "agency",
  tone: "modern",
  ux_goals: ["showcase_work", "build_trust", "drive_contact"]
)

What it does internally:

1. Maps each family name to its compositionRole (navbar → navigation, hero → entry, etc.)
2. Checks which roles still have open slots (respects ROLE_LIMITS)
3. Filters the pattern library to only patterns for uncovered roles
4. Runs the same semantic scoring as compose_page on the remaining candidates
5. Returns a full enriched response

What you get back:

## Already Covered
- `navbar` (navigation ✓)
- `hero` (entry ✓)
- `services` (supporting — 2 slots remaining)

## Gaps Found
Missing roles: trust, conversion, footer

## Suggested Additions
1. Testimonials Base (testimonials/base) — role: trust
2. Contact Base (contact/base) — role: conversion
3. CTA Arrow Badge (cta/arrow-badge) — role: conversion [enhanced]
4. Footer Base (footer/base) — role: footer

## Alternatives
- For testimonials/base: social-proof/creator-credit, logo-cloud/base
- For contact/base: appointment/base, cta/centered

## Bold Picks 💡
- portfolio/video-cards [animated] — Scroll-revealed case study cards ...
- hero/border-frame [enhanced] — If you want to swap the hero for ...

## Ideas Not Yet in Library
- Awards & Recognition strip (Awwwards, FWA badges)
- Scroll-driven process / methodology diagram

## Recommended Snippets
1. Static Grain (atmosphere/static-grain) — atmosphere suits the modern tone
2. Stagger Entrance (interactions/stagger-entrance) — supports showcase_work

## Recommended Fonts
- Heading: Inter
- Body: Inter

Enhanced compose_page Output

compose_page now returns the same enriched format for greenfield pages.

Beyond the primary section list, every response includes:

Alternatives — swap any section

For each selected pattern, up to 3 equally-valid alternatives with the same compositionRole:

## Alternatives
- For hero/base: hero/border-frame, hero/split-image, hero/product-preview
- For features/base: features/bento, features/icon-grid

Use these when the primary pick doesn’t match the client’s visual direction, or when you want to offer the user a choice.

Bold Picks — the unexpected option

Patterns that scored well but weren’t selected because their role was already filled. Filtered to tier: enhanced or animated: true — patterns that are more distinctive:

## Bold Picks 💡
- cta/ticker-sale [enhanced] — Animated ticker for urgency, unusual for agency but striking
- hero/filmstrip [animated] — Scroll-scrubbed hero, high effort but high impact

Always show these. A user who sees only the safe picks never knows they could have had something more interesting.

Ideas Not Yet in Library

Content ideas that fit the project’s domain and uncovered UX goals — but don’t yet exist as patterns:

## Ideas Not Yet in Library
- Client project counter with animated numbers
- Behind-the-scenes studio culture section
- Third-party review aggregate (G2, Trustpilot rating block)

These start conversations. They show the user you understand their domain. And they’re an invitation to brief new patterns.

The Full AI Workflow

Don’t call just one tool. A complete WebSpire session for an existing project looks like this:

1. augment_page(existing_sections, domain, tone, ux_goals)
   → gaps + picks + alternatives + bold picks + missing ideas

2. recommend_fonts(domain, tone)
   → heading/body/mono pairing

3. recommend_design_skill(domain, tone, ux_goal)
   → spacing, color, and component rules for the chosen tone

4. search_snippets("atmosphere grain texture overlay")
   → CSS polish layer, adapt query to the visual direction

5. search_canvas_effects(...)   ← only for visual/atmospheric projects
   → motion layer for hero or background sections

Combine all five outputs and present them as a structured palette to the user.

Inferring domain / tone / ux_goals

You don’t need to ask the user for these values — derive them from what you know about the project.

Infer domain from the site’s purpose:

| What you observe | domain | |---|---| | Product with subscriptions, user accounts | saas | | Creative studio, branding, design | agency | | Online store, products, checkout | ecommerce | | Law firm, compliance, contracts | legal | | Clinic, health service | healthcare | | School, course, training | education | | Strategy, management consulting | consulting | | Personal site, portfolio, blog | personal |

Infer tone from visual signals:

| What you observe | tone | |---|---| | Clean layout, blue/neutral, product screenshots | modern | | Dark backgrounds, glass effects, high contrast | premium | | Serif fonts, large whitespace, editorial structure | editorial | | Rounded shapes, friendly colors, illustrations | friendly | | Code blocks, monospace, technical diagrams | technical |

Infer ux_goals from business intent (pick 2–4):

| Business intent | ux_goal | |---|---| | Get signups / trial starts | drive_signup | | Get inquiries / leads | drive_contact | | Sell a product | drive_purchase | | Establish credibility | build_trust | | Explain a complex offer | explain_offer | | Show portfolio work | showcase_work | | Demonstrate expertise | highlight_expertise | | Tell a brand story | tell_story |

existing_sections — What to Pass

Pass family names, not pattern IDs:

✓  existing_sections: ["navbar", "hero", "services", "contact"]
✗  existing_sections: ["navbar/base", "hero/with-image"]   ← IDs, not families

If you don’t know the exact family names, look at the HTML — every WebSpire section has a ws-{family} class on the root element.

If the existing page wasn’t built with WebSpire at all, pass the section types as descriptions and map them to the closest family names:

| Existing section | Use family | |---|---| | Top navigation bar | navbar | | Full-width hero with headline | hero | | “What we offer” section | services or features | | Client logos strip | logo-cloud | | Customer quotes | testimonials | | Contact form | contact | | Page footer | footer |

Composition Role Reference

| Role | Limit | Typical families | |------|-------|-----------------| | navigation | 1 | navbar, announcement-bar | | entry | 1 | hero, page-header | | supporting | 3 | features, services, portfolio, blog, integrations, faq | | conversion | 2 | pricing, contact, cta, appointment | | trust | 2 | testimonials, logo-cloud, awards-list, social-proof | | footer | 1 | footer |

augment_page uses these limits to determine what’s still available after accounting for existing sections.