generating-weaverse-project-json
Use when generating Weaverse project export JSON for import into the Weaverse editor. Triggers on requests to create, build, or produce a Weaverse project JSON file from a site migration, design spec, page layout description, or existing export. Also use when converting section plans into importable project and pages data.
Weaverse · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Weaverse/shopify-hydrogen-skills --skill generating-weaverse-project-json技能说明
name: generating-weaverse-project-json description: Use when generating Weaverse project export JSON for import into the Weaverse editor. Triggers on requests to create, build, or produce a Weaverse project JSON file from a site migration, design spec, page layout description, or existing export. Also use when converting section plans into importable project and pages data.
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. The Content API can only update items that already exist, so the import-then-update split matters: use this skill to create structure, weaverse-content-api to maintain it. Keep the item ids stable between the two.
Generation Steps
- Read references — load
references/project-json-schema.mdfor the contract andreferences/demo.jsonfor a complete real-world example - Identify registered types — read
app/weaverse/components.tsto know which section and block types are available - Read section source code — for each section type you plan to use, read its source in
app/sections/orapp/components/to learn valid schema fields, enum values, and defaults - Build the JSON following the structure below
- Run the validator — execute
python scripts/validate.py <output-file>to catch structural errors - 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:
| Key | Type | Purpose |
|---|---|---|
previewHost | string | Dev server URL, usually http://localhost:3456 |
theme | object | Storefront-wide design tokens (colors, typography, layout) |
defaultLocale | object | { label, language, country, currency, pathPrefix } |
recentColors | string[] | Editor color picker recent colors |
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
itemsarray, hierarchy is expressed throughchildrenid-references - One root
mainitem per page — its id must matchrootId childrenis REQUIRED on every item — use[]for leaf items,[{ "id": "<item-id>" }]for parentsdatais REQUIRED on every item — use{}when no non-default values are neededtypemust be a registered section or block type fromapp/weaverse/components.ts
CRITICAL: The Weaverse importer expects both data and children to be