Generating Weaverse Project JSON

Generate valid, import-ready Weaverse project export JSON files.

Overview

This skill produces JSON files that conform to the Weaverse import contract. It works independently — you can use it from a site migration, a design spec, a verbal description, or any other input that describes what pages and sections should exist.

The output is a single JSON file matching the schema in references/project-json-schema.md, with a real-world example in references/demo.json.

Inputs

This skill accepts any of these as input:

• Section mapping from cloning-websites-to-weaverse (website migration flow)
• Section mapping + token table from figma-to-weaverse (Figma design flow)
• Design spec describing pages, sections, and content
• Verbal description of what the storefront should look like
• Existing export to modify or extend

The only hard requirement: you need to know which section types to use. Read app/weaverse/components.ts to get the list of registered sections and blocks.

Delivery

This skill produces an import JSON that establishes the project structure — pages, sections, and initial content. That JSON is imported once into the Weaverse Studio editor to create the project.

After the structure exists, ongoing content edits (copy, images, localization, bulk updates) should go through the `weaverse-content-api` skill, not by re-importing. Keep the item ids stable between the two so later patches target the same items.

When the project already exists (the usual case for adding pages to a live store), you don't have to import at all: create the page with POST /projects/:projectId/pages and send the JSON's items in one PATCH (see "Populate a new or empty page" in weaverse-content-api). Keep the JSON file in the repo as the record of what was pushed, and sync it back if you change the live page afterwards.

Generation Steps

1. Read references — load references/project-json-schema.md for the contract and references/demo.json for a complete real-world example
2. Identify registered types — read app/weaverse/components.ts to know which section and block types are available
3. Read section source code — for each section type you plan to use, read its source in app/sections/ or app/components/ to learn valid schema fields, enum values, and defaults
4. Build the JSON following the structure below
5. Run the validator — execute python3 scripts/validate.py <output-file> (works on Python 3.8+) to catch structural errors
6. Fix any issues the validator reports, then re-run until clean

JSON Structure

Top-level

{
  "version": "1.0.0",
  "exportedAt": "<ISO timestamp>",
  "project": { "name": "<name>", "config": {} },
  "pages": [],
  "pageAssignments": []
}

project.config

Contains theme settings, locale, and colors. Accepted keys:

For theme, refer to references/demo.json → project.config.theme for the full set of valid keys. Key categories:

• Colors: colorPrimary, colorText, colorBackground, colorLine, colorTextSubtle, colorLineSubtle, colorTextInverse, colorForeground
• Typography: bodyBaseSize, bodyBaseLineHeight, bodyBaseSpacing, h1BaseSize, headingBaseLineHeight, headingBaseSpacing
• Layout: pageWidth, footerWidth, headerWidth, navHeightDesktop, navHeightTablet, navHeightMobile
• Header/Footer: headerBgColor, headerText, footerBgColor, footerText, topbarBgColor, topbarTextColor, topbarHeight
• Buttons: buttonPrimaryBg, buttonPrimaryColor, buttonSecondaryBg, buttonSecondaryColor, btnCornerRadius
• Product cards: pcardAlignment, pcardImageRatio, pcardBorderRadius, pcardShowVendor, pcardShowReviews, pcardShowSalePrice, etc.
• Badges: newBadgeText, newBadgeColor, saleBadgeText, saleBadgeColor, soldOutBadgeText, soldOutBadgeColor, bestSellerBadgeText, bestSellerBadgeColor
• Social: socialFacebook, socialInstagram, socialLinkedIn, socialX
• Newsletter: newsletterTitle, newsletterDescription, newsletterButtonText, newsletterPlaceholder, newsletterPopupEnabled, etc.

Only include theme keys you understand and intend to set. Do not copy the entire demo theme blindly.

Pages

Each page has id, name, rootId, and a flat items array:

{
  "id": "b98mnnqmv3tmce7wmw3l7vw4",
  "name": "Homepage",
  "rootId": "019b917a-f48f-72d4-aee7-3b1eae6b7dca",
  "items": [
    { "id": "019b917a-f48f-72d4-aee7-3b1eae6b7dca", "type": "main", "data": {}, "children": [{ "id": "019b917a-f48f-72d4-aee7-3b1f5ca586c1" }] },
    { "id": "019b917a-f48f-72d4-aee7-3b1f5ca586c1", "type": "hero-image", "data": { "height": "small" }, "children": [{ "id": "019b917a-f48f-72d4-aee7-3b22cd55e21b" }] },
    { "id": "019b917a-f48f-72d4-aee7-3b22cd55e21b", "type": "heading", "data": { "content": "Welcome" }, "children": [] }
  ]
}

Key rules:

• Flat items — all items live in the items array, hierarchy is expressed through children id-references
• One root `main` item per page — its id must match rootId
• `children` is REQUIRED on every item — use [] for leaf items, [{ "id": "<item-id>" }] for parents
• `data` is REQUIRED on every item — use {} when no non-default values are needed
• `type` must be a registered section or block type from app/weaverse/components.ts

CRITICAL: The Weaverse importer expects both data and children to be present on EVERY item. Omitting them causes silent import failures (empty page renders). Always include "data": {} and "children": [] even when empty.

Page Assignments

Maps pages to routes:

{ "pageId": "b98mnnqmv3tmce7wmw3l7vw4", "type": "INDEX", "handle": "", "locale": "en-us" }

Common types: INDEX, PRODUCT, COLLECTION, ALL_PRODUCTS, COLLECTION_LIST, PAGE, BLOG, ARTICLE, CUSTOM.

For CUSTOM pages, set handle to the route slug (e.g., "reseller"). For standard template pages, handle is usually empty "".

Template page stubs

Standard pages (product, collection, blog, article) that aren't being customized should be empty stubs:

{
  "id": "qa8xa47ou35atbo1ik4w7v6y",
  "name": "Default product",
  "rootId": "019b917a-f490-794d-95d0-82a578d7cdfc",
  "items": [{ "id": "019b917a-f490-794d-95d0-82a578d7cdfc", "type": "main", "data": {}, "children": [] }]
}

Data Value Rules

Only use verified enum values

Before writing any select, toggle-group, or position value, read the section source code. Common mistakes:

Only include non-default values

If a field matches the schema default, omit it. The Weaverse editor strips defaults on save. Including them creates noise.

Schema presets are not defaults: a value a section's presets turn on (e.g. enableOverlay: true) is only applied when a merchant adds the section in Studio, not on import or Content API writes. Compare against the input's defaultValue, and write any preset value you actually want explicitly.

Shopify entity references

Collections and products use object format, not bare strings:

// Collections
"collections": [{ "id": 456905851102, "handle": "covers" }]

// Products
"product": { "id": 123456789, "handle": "my-product" }

If real Shopify IDs are unknown, omit the field or use []. Do not invent fake IDs.

Image fields

External images use a bare URL string. Shopify-hosted images use the media object:

// External
"backgroundImage": "https://example.com/image.jpg"

// Shopify media
"backgroundImage": {
  "id": "gid://shopify/MediaImage/12345",
  "url": "https://cdn.shopify.com/...",
  "width": 1920, "height": 1080, "altText": "Description"
}

For anything that will go live, use Shopify media. Figma MCP asset URLs (figma.com/api/mcp/asset/...) expire after about 7 days and some storefront image transforms block them; upload the files to Shopify first (weaverse-content-api → upload) and use the returned objects. SVGs upload as generic files and come back as a plain CDN URL string.

ID Format Rules

Page IDs and item IDs use different formats:

Integrity rules:

• Every page id must be unique across the export
• Every item id must be unique across the export
• rootId must match the root main item's id exactly
• Every child reference must point to an existing item in the same page
• Page IDs are CUIDs — use a CUID generator or produce 25-char lowercase alphanumeric strings
• Item IDs are UUIDs — use UUID v7 format (timestamp-sortable, hyphenated)
• When one repo holds several exports (one per page), give each page its own id range (e.g. 019b9400-… for the homepage, 019b9500-… for the next page) so items never collide when pages are pushed to the same project

Validation

After generating the JSON, run the bundled validator:

python3 scripts/validate.py <path-to-output.json>

The validator checks:

• Valid JSON structure
• Required top-level fields present
• Every page has id, name, rootId, items
• Every rootId resolves to an item with type: "main"
• Every item has data and children fields (both required)
• No duplicate item IDs
• All child references resolve to existing items within the same page
• All pageAssignment.pageId values resolve to existing pages

Fix any reported errors and re-run until clean. Do not deliver JSON that fails validation.

Common Mistakes