# Island Catalog

> All interactive islands with props, categories, and usage hints

Canonical URL: https://fa7e86e3d553:3005/resources/island-catalog

## Overview

The **Island Catalog** is the discovery resource for interactive components
available to page authors. Use it to select an island, then read that island's
schema before writing source.

**URI**: `vibe://catalog/islands`  
**Format**: `application/json`  
**When to use**: Read this before generating page HTML to discover relevant islands.

## Structure

The catalog is a JSON array where each island has:

```typescript
{
  name: string;
  category: string;
  summary: string;
  usage: {
    hint: string;
    when_to_use: string;
    when_not_to_use: string;
    combine_with: string[];
    anti_patterns: string[];
  };
  variants: string[] | null;
  behavior: {
    default_hydrate: string;
    headless: boolean;
  };
  styling: {
    css_vars: string[];
    parts: string[];
  };
}
```

## Categories

### Commerce islands

Primary e-commerce functionality — cart, checkout, product display, discounts.

**Key islands:**
- `BuyBox` — Add-to-cart with variant selection
- `CartDrawer` — Legacy Cart V1 slide-out cart; use Cart V2 for new pages
- `DrawerShell`, `CartLines`, `CartSummary`, and `CartCheckoutButton` — Effective-profile cart foundation
- `CartCrossSell` — Profile-driven reactive product recommendations
- `CartRewardProgress` — Cart V2 reward milestones with automatic gift and discount reconciliation
- `CartCoupons` — Cart V2 curated offers, applied savings, and manual coupon entry
- `ProductGallery` — Eight-layout mixed-media PDP gallery with thumbnails, collages, grids, masonry, and lightbox
- `VariantSwatches` — Visual variant selector
- `QuantityBreaks` — Volume discount display
- `SubscriptionToggle` — Subscribe & Save
- `StickyBar` — Fixed bottom add-to-cart
- `ProductCarousel` — Horizontal product-card scroll with unified multi-media cards
- `FeaturedCollectionStage` — Editorial shared-stage collection rail with active product details
- `ShoppableVideoFeed` — Responsive shoppable reels, rails, and video grids
- `BundleBuilder` — Frequently Bought Together
- `BundleConfigurator` — Build-your-own boxes with exact item limits, repeats, and live pricing
- `InventoryIndicator` — Stock urgency
- `DeliveryEstimate` — Shipping timeline with countdown
- `PaymentOptions` — BNPL messaging
- `QuickAdd` — Lightweight add-to-cart for grids
- `OptionResolver` — Multi-axis variant resolution (invisible)
- `VariantSelector` — Scoped dropdown, swatch, or button option selector
- `ProductHero` — Premium variant-aware PDP media hero
- `PlanSelector` — Subscription-plan cards and pricing coordination

Read the selected island schema to determine whether it accepts a `productId`,
an authored product object, or both.

### Social Proof (3 islands)

Trust signals and FOMO — reviews, purchase notifications, badges.

- `ReviewCarousel` — Scrolling review cards
- `ReviewList` — Paginated or filterable review list
- `SocialProofPopup` — Toast notifications (recent purchases)

### Content and media

Information display and media — FAQs, videos, comparisons, galleries, and
full-bleed hero media.

- `FAQ` — Expandable accordion
- `VideoPlayer` — Lazy-loaded video
- `BeforeAfter` — Interactive image slider
- `ImageZoom` — Hover/click-to-zoom
- `CountdownTimer` — Urgency countdown
- `GalleryLightbox` — Event-driven fullscreen image lightbox with thumbnail sidebar
- `MediaCarousel` — Shared image/adaptive-video carousel
- `HeroMedia` — Full-bleed image or video hero media

### Engagement (5 islands)

Lead capture and interaction — email signups, size guides, ingredient explorers.

- `EmailCapture` — ESP-connected signup form
- `FunnelRuntime` — Server-resolved quizzes, offers, and capture flows
- `Modal` — Reusable modal/popup behavior
- `SizeGuide` — Size chart modal
- `IngredientExplorer` — Interactive ingredient breakdown

### Navigation (5 islands)

Site navigation and wayfinding.

- `SiteHeader` — Combined announcement + navbar in one fixed header (preferred)
- `Navbar` — Top navigation with mobile hamburger
- `AnnouncementBar` — Top banner with rotating messages
- `MobileMenu` — Full-screen mobile drawer
- `Footer` — Footer navigation, social links, and newsletter capture

## How to Use

**Step 1: Read the catalog**
```typescript
const catalog = await readResource("vibe://catalog/islands");
const islands = JSON.parse(catalog);
```

**Step 2: Filter by category**
```typescript
const commerceIslands = islands.filter(i => i.category === "commerce");
```

**Step 3: Find relevant islands**
```typescript
// For a PDP
const pdpIslands = islands.filter(i => 
  ["commerce", "social_proof", "content"].includes(i.category)
);
```

**Step 4: Author in source format**
```html
<lx-island name="BuyBox">
  <script type="application/json">
    { "product": { "...": "..." } }
  </script>
</lx-island>
```

## Island Authoring Protocol

All new pages use `<lx-island>` source elements:

```html
<lx-island name="{IslandName}" hydrate="visible">
  <script type="application/json">{JSON_OBJECT}</script>
</lx-island>
```

**Rules:**
1. `name` must exactly match a valid island name (case-sensitive).
2. The JSON script must contain one valid props object.
3. `hydrate`, `headless`, `class`, `id`, `style`, ARIA, and `data-*`
   attributes are passed through by the compiler.
4. Run `lexsis_pages` with action `compile` to validate the result.

## Template Resources

For detailed island specifications, use the individual island resource:

**URI pattern**: `vibe://schema/island/{name}`
**Format**: `application/json`

**Example:**
```typescript
// Get full BuyBox spec
const buyBox = await readResource("vibe://schema/island/BuyBox");
```

## Example Catalog Entry

```json
{
  "contract_version": 2,
  "name": "BuyBox",
  "category": "commerce",
  "props": {
    "productId": { "type": "string", "required": false },
    "ctaText": { "type": "string", "required": false },
    "variant": {
      "type": "enum",
      "required": false,
      "values": ["default", "compact", "expanded"]
    }
  },
  "authoring": {
    "format": "source-html",
    "element": "lx-island",
    "props_encoding": "script[type=application/json]",
    "example": "<lx-island name=\"BuyBox\"><script type=\"application/json\">{\"productId\":\"gid://shopify/Product/123\"}</script></lx-island>"
  }
}
```

## Common Patterns

### PDP Page Structure

```html
<!-- Hero -->
<section>
  <lx-island name="ProductGallery">
    <script type="application/json">{ "productId": "..." }</script>
  </lx-island>
  <lx-island name="BuyBox">
    <script type="application/json">{ "productId": "..." }</script>
  </lx-island>
</section>

<!-- Details -->
<details>
  <summary>Product details</summary>
  <p>Product specifications, materials, and care information.</p>
</details>

<!-- Social Proof -->
<lx-island name="ReviewCarousel">
  <script type="application/json">{ "productId": "..." }</script>
</lx-island>

<!-- FAQ -->
<lx-island name="FAQ">
  <script type="application/json">
    {"items":[{"question":"When will it arrive?","answer":"Most orders arrive in three to five business days."}]}
  </script>
</lx-island>
```

Cart V2 is enabled by default. The renderer injects the effective cart
profile; do not add CartDrawer, DrawerShell, or a Cart V2 flag to source.

`Tabs` remains deprecated. Use the supported FAQ island for reusable accordion
behavior.

### Landing Page Structure

```html
<!-- Hero -->
<section>
  <h1>Headline</h1>
  <lx-island name="EmailCapture">
    <script type="application/json">{}</script>
  </lx-island>
</section>

<!-- Social Proof -->
<lx-island name="SocialProofPopup">
  <script type="application/json">{}</script>
</lx-island>

<!-- Testimonials -->
<lx-island name="ReviewCarousel">
  <script type="application/json">{}</script>
</lx-island>

<!-- CTA -->
<section>
  <lx-island name="ProductCarousel">
    <script type="application/json">{}</script>
  </lx-island>
</section>
```

### Multi-Variant Product Pattern

When product has 2+ option axes (e.g., Color × Size):

```html
<lx-island name="OptionResolver">
  <script type="application/json">
{
  "variants": [
    {
      "id": "example-id",
      "selectedOptions": "example-selectedOptions",
      "price": "example-price",
      "available": true
    }
  ],
  "options": [
    {
      "name": "example-name",
      "position": 0
    }
  ]
}
  </script>
</lx-island>

<lx-island name="VariantSwatches">
  <script type="application/json">
{}
  </script>
</lx-island>

<lx-island name="ProductGallery">
  <script type="application/json">
{}
  </script>
</lx-island>

<lx-island name="BuyBox">
  <script type="application/json">
{
  "product": {
    "title": "example-title",
    "price": "example-price",
    "variants": []
  }
}
  </script>
</lx-island>
```

**Event flow:**
1. User clicks Color swatch → `option:changed` event
2. User clicks Size swatch → `option:changed` event
3. OptionResolver combines options → `variant:changed` event
4. ProductGallery + BuyBox update to resolved variant

## Runtime Island Names

The runtime accepts the following names for compatibility. Deprecated names
remain valid for existing pages but are excluded from new-page discovery:

Do not copy a hardcoded runtime list into generation logic. Read
`vibe://catalog/islands`, which is generated from the current 58-island schema
catalog and excludes deprecated entries from active recommendations.

See [Deprecated Islands](/islands/deprecated) for the complete deprecated
list: `BackToTop`, `Carousel`, `CartDrawer`, `Countdown`, `Marquee`,
`StatCards`, and `Tabs`.

## When to Read This Resource

**Read the full catalog when:**
- Starting a new page generation
- You need to browse available islands by category
- You're unsure which island fits your use case

**Read individual island resources when:**
- You know which island you need
- You want detailed prop schemas
- You're debugging props validation errors

**Don't read this when:**
- Editing existing sections without adding new islands
- Making style/CSS changes
- Working with static HTML (no interactivity needed)

The island catalog is your component menu — reference it when composing interactive sections.