figma-to-weaverse

name	figma-to-weaverse
description	Use when recreating a Figma design as Hydrogen + Weaverse pages in this repo — turning a Figma file, frame, or flow into reusable Weaverse sections. Triggers on a figma.com URL, "build this design", "implement this Figma", or "create the storefront from the design". The Figma counterpart of cloning-websites-to-weaverse.

Figma to Weaverse

Turn a Figma design into maintainable Weaverse pages. This is the Figma input adapter — the sibling of cloning-websites-to-weaverse, but the source is a Figma file instead of a live URL. Both adapters converge on the same downstream skill, generating-weaverse-project-json.

Figma file / frame ─→ figma-to-weaverse ─→ generating-weaverse-project-json ─→ import / content API
   (Figma MCP)        (tokens + manifest + preview)        (project JSON)

The two adapters share the same downstream rules. Section matching, deep schema verification, the content manifest, the clone preview route, and the brand-guideline conflict rule are identical to cloning-websites-to-weaverse — read that skill for the full matching logic. This skill only replaces the extraction layer (Figma MCP instead of Firecrawl) and adds Figma-specific gotchas.

When to Use

• A figma.com URL (file, frame, or selection) is the source of a page or storefront
• "Implement this design in Weaverse", "build the homepage from Figma"
• Multi-frame flows that map to multiple Weaverse pages

Do not use it for live-website cloning (use cloning-websites-to-weaverse) or tiny copy edits.

Required Inputs

• Figma file/frame/node URL (or current selection)
• .guides/brand-guideline.md
• sections.md
• app/weaverse/components.ts

Required Outputs

Same three deliverables as the website cloning skill:

1. Content manifest — per-section table of real asset URLs (from Figma asset export), text, links, Shopify refs, media types.
2. Clone preview route — a single app/routes/clone-preview.$page.tsx rendering the full design as React + Tailwind, section-marked, brand-adjusted. User must approve this before section decomposition.
3. Design spec — section mapping, schema boundaries, interaction model, token mapping.

Extraction with Figma MCP (MCP-first)

Use the Figma MCP tools. They return structured design data — more precise than scraped HTML for tokens and layout, but weaker on real interaction (a static design has no runtime behavior).

Before any use_figma write call, load the figma-use skill. For reads below, no write is needed.

1. Map the structure — get_metadata on the file/frame to get the node tree. Top-level frames/sections become your section-splitting boundaries (the Figma equivalent of HTML section markers).
2. Extract design tokens — get_variable_defs for colors, typography, spacing, radius. These map directly into project.config.theme in the JSON generator (colors → colorPrimary/colorText/…, type scale → bodyBaseSize/h1BaseSize/…). This is the biggest advantage over web scraping — tokens are explicit, not inferred.
3. Read layout + content per frame — get_design_context on each section frame for layout structure, auto-layout direction, text content, and component usage. Auto-layout (horizontal/vertical, wrap, spacing) tells you composition (side-by-side vs stacked vs grid).
4. Export assets — download_assets (or get_screenshot of leaf image nodes) to get real image/icon URLs. These populate the content manifest's image columns. There is no "video src" to extract like in HTML — flag motion/video intent from frame names or prototype notes instead.
5. Visual reference — get_screenshot of each frame for the approval checkpoint and for verifying the clone preview matches.
6. Design system reuse — search_design_system / get_libraries when the file uses a component library, to understand reusable component intent.

Plugin fallback

If the MCP can't reach the file or can't export a specific asset (e.g. a flattened group, an unusual export setting), fall back to a Figma agent plugin export and read its output file. MCP is the primary path; use the plugin only to fill a concrete gap, and note in the manifest which assets came from the fallback.

Workflow

1. Read .guides/brand-guideline.md first. Brand guideline beats the design on visual conflicts.
2. Ensure sections.md exists and is current before section matching.
3. Extract the design with Figma MCP (steps 1–6 above). Save raw context/exports under .figma/<file>-<frame>.json (mirrors the cloning skill's .firecrawl/).
4. Map tokens — turn get_variable_defs output into a theme token table for project.config.theme.
5. Build the content manifest — required deliverable, same columns and rules as the cloning skill. Asset URLs come from download_assets, not from guessing.
6. Generate the clone preview route at app/routes/clone-preview.$page.tsx — React + Tailwind, real assets, brand-adjusted tokens, {/* === BLOCK NAME === */} markers per frame.
7. User approval checkpoint — STOP and wait. Present the preview URL + a summary (frame/section count, brand overrides, gaps). Do not proceed until the user explicitly approves. Iterate the preview on feedback.
8. Decompose & match — split into section-sized blocks (one per top-level frame, usually). Classify media type, composition, layout mechanism, interaction. Then match against sections.md using the layout matching priority and deep structural verification defined in cloning-websites-to-weaverse (composition → layout → interaction → content model; then read the candidate section's source to verify aspect ratios, responsive images, split ratios, child types, animation, overlays). Classify as REUSE_EXISTING, ADAPT_EXISTING, or CREATE_NEW_REUSABLE_SECTION.
9. Implement with clean schema boundaries: shared tokens → app/styles/app.css; sitewide controls → app/weaverse/schema.server.ts; section-local → section schema. Register new sections in app/weaverse/components.ts.
10. Hand off the design spec + content manifest + token table to generating-weaverse-project-json.
11. Verify desktop and mobile, then delete the temporary preview route once the Weaverse page matches the approved preview.

Figma-specific differences from website cloning

Aspect	Website (Firecrawl)	Figma (MCP)
Design tokens	inferred from CSS/computed styles	explicit via get_variable_defs — map directly to theme
Section boundaries	HTML section markers, slider/grid classes	top-level frames / auto-layout containers from get_metadata
Composition	read from HTML positioning	read from auto-layout direction/wrap/spacing
Assets	image/video URLs in HTML	download_assets exports; no real video src
Interaction	real runtime behavior in HTML	none at runtime — infer from frame names, prototype links, designer notes; do not invent interactions the design doesn't imply
Responsive variants	<picture> / breakpoint classes	separate desktop/mobile frames if the designer made them; otherwise one frame

Red Flags

• Skipping the approval checkpoint — same rule as website cloning: the user must approve the clone preview before section decomposition.
• Inventing interactions — a static Figma frame has no carousel autoplay or scroll behavior unless the prototype or notes say so. Don't classify a frame as a slider just because it shows multiple cards. Confirm from prototype links or frame naming.
• Ignoring Figma variables — get_variable_defs is the cleanest token source you'll ever get. Hardcoding colors/sizes when variables exist throws away the main Figma advantage.
• Guessing asset URLs — export real assets with download_assets; mark MISSING — [describe] in the manifest when an export fails, don't substitute a placeholder.
• One giant bespoke section per frame — decompose into reusable sections; reuse the registry first.
• Re-deriving the matching rules — the section-matching priority and deep schema verification live in cloning-websites-to-weaverse. Follow them; don't reinvent a looser version.
• Treating mobile/desktop frames as two pages — they're responsive variants of the same section; map to imageMobile/imageDesktop or breakpoint logic, not separate pages.
• Leaving the preview route in the repo — delete it after the Weaverse page is verified.

Related skills

• cloning-websites-to-weaverse — the website input adapter; owns the shared section-matching, manifest, and preview rules this skill reuses.
• generating-weaverse-project-json — downstream; turns this skill's spec + manifest + token table into import-ready JSON.
• weaverse-content-api — push or update content into the live project after import.
• figma-use / figma-generate-design — Figma MCP plugin skills; load figma-use before any use_figma write call.