# Generation Guide

> Complete system context for authoring valid storefront source

Canonical URL: https://c22dfdd27662:3005/resources/generation-guide

## Overview

The **Generation Guide** is the single most important resource in the Storefront MCP. It delivers the complete system context needed to author valid source-format pages.

**URI**: `vibe://docs/generation-guide`  
**Format**: `text/markdown`  
**When to read**: BEFORE generating any page — it must be your first action in any generation workflow.

## What It Contains

The generation guide is a dynamically assembled markdown document with five sections:

### 1. System Prompt

Complete instructions on how to author source-format HTML, including:
- **Output format**: HTML sections with structured `head`, `theme_css`, and `scripts` tool parameters
- **Base styles**: CSS reset and typography already loaded by the renderer
- **CSS variables**: The complete `--lx-*` variable catalog
- **Shared keyframes**: Pre-loaded animations (fadeUp, fadeIn, scaleIn, slideInLeft, slideInRight, marquee, float, shimmer, wordFade, pulseRing)
- **14 generation rules**: Tailwind-first, island embedding protocol, semantic HTML, mobile-first design, performance guidelines, security constraints

### 2. User Prompt (optional)

If the guide was requested with a brand brief or page type, this section provides:
- Page type focus (PDP, landing, homepage, collection)
- Brand tone and industry context
- Relevant products and reference URLs
- Page-specific island recommendations

### 3. Island Catalog

Filtered list of the currently available, non-deprecated islands with:
- Name and category (commerce, social_proof, content, engagement, navigation)
- Usage hint (when and where to use the island)
- HTML embedding example with `<lx-island>` and a JSON script child

The catalog is filtered by page type if specified, otherwise shows all islands.

### 4. Valid Island Names

Comma-separated list generated from the current island catalog for quick
validation. Do not depend on a hardcoded island count.

### 5. Page Source Contract

The complete authoring contract for source HTML, head settings, theme CSS, and
page-level scripts.

## How to Use

**In any generation workflow:**

```typescript
// Step 1: Read the guide (ALWAYS FIRST)
const guide = await readResource("vibe://docs/generation-guide");

// Step 2: Author source-format HTML
const source = await llm.generate({
  systemContext: guide,
  userPrompt: "Create a PDP for hydrating serum"
});

// Step 3: Compile before saving
const validated = await call_tool("lexsis_pages", {
  action: "compile",
  args: {
    source,
    head: { title: "Hydrating Serum" }
  }
});
```

**Key benefits:**
- **Shared context in one read**: Resolve the current schema for each selected
  island before authoring its props
- **Always current**: Dynamically built from source-of-truth catalogs
- **Page-type optimized**: When you specify a page type, you get filtered islands and focused instructions

## Quiz journeys

Use the live [Quiz island](/islands/engagement/quiz) for questions, branching,
results, real product/variant choices, and cart actions. Read
`vibe://schema/island/Quiz` before compilation. Do not implement quiz state with
custom section JavaScript or hidden commerce controls.

Optional saving follows [Forms and Quiz Responses](/tools/forms): inspect the
saved version, prepare its policy, activate with approval, publish the matching
page version, then verify capture on the published URL. Saving consent,
analytics consent, design approval, and publication are separate concerns.

## Performance Guidelines from the Guide

The guide enforces several performance constraints:

1. **Use Tailwind classes** for layout, spacing, sizing, responsive behavior,
   and state styling
2. **Use shared keyframes** instead of defining new `@keyframes`
3. **Minimize section JS** — only for animations/observers, no network access
4. **Page scripts for integrations** — use top-level `scripts` array for analytics/widgets
5. **No external dependencies in section CSS** — no `@import`, no `url()` to external resources

## Template Resources

The generation guide can be customized via template resources:

### Section Templates

Search templates before generating a section from scratch. Fetch selected
templates with `lexsis_design` action `get_section`. Its response includes one
complete `source` string per template with HTML plus any section CSS and
JavaScript. A template can contain `<lx-island>` elements, plain HTML, or both.

Template results return complete source-format sections ready to tailor and
pass to `lexsis_pages` action `compile`.

Do not assume template-search metadata is authoritative for `has_js` or
`islands_used`. Fetch the selected artifact and inspect its complete source.

### Individual Skill Guides

**Format**: `text/markdown`

Search with `lexsis_support` action `search_docs`, then read the exact resource URI
returned by that search. Do not construct a `vibe://skills/{name}` URI or rely
on a hard-coded catalog; the search result is the availability check.

**Usage:**
```typescript
// Load the exact URI returned by lexsis_support action search_docs
const guide = await readResource(searchResult.resource_uri);
```

## What It Replaces

The generation guide resource **replaces the deprecated `get_storefront_skills` tool**.

**Migration:**
```typescript
// Old (deprecated)
const guide = await call_tool("get_storefront_skills", {pageType: "pdp"});

// New (preferred)
const guide = await readResource("vibe://docs/generation-guide");
```

## When NOT to Use

Do **not** re-read the generation guide for every section edit or small change. Read it once at the start of a generation session and cache it. For edits:

1. **Section edits**: Use the existing page context + edit instructions
2. **Island prop changes**: Read `vibe://catalog/islands/{name}` for just that island's spec
3. **Schema validation**: Read `vibe://schema/page` for just the schema

The generation guide is comprehensive (3-5kb markdown) — only fetch it when you need the full picture.

## Example Workflow

**New page generation:**
```
1. User: "Create a PDP for vitamin C serum"
2. Agent: readResource("vibe://docs/generation-guide")
3. Agent: LLM authors source-format HTML with guide as system context
4. Agent: call_tool("lexsis_pages", {action: "compile", args: {source, head, theme_css}})
5. Agent: call_tool("lexsis_page_create", {action: "create", args: {source, head, theme_css, slug, publish: false}})
```

**Page edit:**
```
1. User: "Make the hero background gradient"
2. Agent: call_tool("lexsis_pages", {action: "edit_context", args: {page_id}})
3. Agent: call_tool("lexsis_pages", {action: "section_source", args: {page_id, section_id: "hero"}})
4. Agent: edits one source-format section
5. Agent: call_tool("lexsis_drafts", {
     action: "page_patch",
     args: {
       page_id,
       expected_version: editContext.current_version,
       changes: [{operation: "upsert_section", source}]
     }
   })
6. Agent: call_tool("lexsis_pages", {action: "integrity", args: {page_id}})
7. Agent: verifies the preview at 390px, 768px, and 1280px with its browser capability
```

The MCP does not run a shared browser preview service. Browser QA belongs to
the calling agent.

The generation guide is your foundation — read it first, then build on it.