figma-to-shopify

name

figma-to-shopify

description

Convert Figma designs into Shopify Dawn-fork theme sections through a fixed three-phase flow — analyze the whole Figma, then produce a complete project document, then build sections from that document. Use whenever the user shares a Figma URL/node ID, starts a new theme project, asks to analyze a design, create/update a project brief, or build/convert any Shopify section — even without saying "Figma to Shopify". Also use when reviewing/updating docs/figma-brief.md. Development does NOT run QA — QA is a separate, explicit step handled by the qa agent.

Figma → Shopify (analyze → document → build)

Four phases, in order. Never code from a Figma link before the project document exists.

• Phase 0 — Intake client/Figma/store info from the user, if not already on file. No code.
• Phase 1 — Analyze the entire Figma. No code.
• Phase 2 — Document everything into docs/figma-brief.md. No code.
• Phase 3 — Build sections from the doc, using only relevant domain skills. No QA during development — see CLAUDE.md's "Two modes" rule for the full statement; not restated here.

Figma file key/link live in docs/figma-brief.md's project header (see Phase 0). Always fetch live via Figma MCP by node ID — never from memory.

---

Phase 0 — Intake (first run on a fresh project only)

If docs/figma-brief.md's project header still has placeholder values (<client name>, <figma-file-key>, etc.), this skill set hasn't been wired to a real project yet. Ask the user for client name, Figma URL/file key, dev store, and templates in scope before doing anything else — see CLAUDE.md's "First-run intake". Fill the project header in as soon as they answer, then proceed straight into Phase 1 without waiting for a separate request — analyzing and documenting the whole file is the expected next step once Figma access is confirmed, not something to ask permission for again.

Skip this phase entirely once the header is already filled in for a real project.

Phase 1 — Analyze (read-only)

Walk the whole file before writing anything: every template/section/component (variants+states), desktop/tablet/mobile differences (stacking, hidden elements, crops), typography/colors/spacing rhythm, images/icons/animations/interactions/repeated patterns. No code output — output is understanding, which Phase 2 records.

Phase 2 — Document

Goal: one docs/figma-brief.md any dev/session can build from without reopening Figma. Read references/brief-template.md before writing, references/design-tokens.md when mapping styles.

Contents:

1. Project header: client, Figma link+key, dev store, templates in scope.
2. Global tokens: fonts, colors (→ variable names + color schemes), spacing scale (references/design-tokens.md).
3. Page hierarchy & section list: every section across templates, build order (deps first — header/footer, shared components, then template-specific).
4. Status table: | Section | Node ID | Template(s) | Complexity | Status |.
5. One brief entry per section per references/brief-template.md (visual brief, content, schema plan, tokens, interactions, reuse check, deps/risks). Must carry the Figma node ID + deep link. For any decorative/background/off-canvas/absolutely-positioned layer, pull real x/y/width/height/opacity/rotation from get_metadata now — write actual numbers, never a qualitative guess ("upper-left", "faint"). Guessed-now becomes wrong-shipped-later.
6. Reuse check per section against sections/ and any team library — reuse beats rebuild.
7. Required Shopify pieces: sections, snippets, metafields/metaobjects, dynamic-content needs, functionality checklist.
8. Risks: metafields, apps, custom JS, design ambiguities needing client input.

Initial status for every section: pending.

Phase 3 — Build

Build one section at a time against its brief. Load only needed skills. No QA, no re-audit, no per-change Figma re-compare.

The step order below is a mandatory execution gate, not a recommendation. It applies to EVERY request to produce a section, in any phrasing — "Create <Section Name>", "Build <Section Name>", "Create node <Node ID>", "Build node <Node ID>", "Create this section", "Convert this Figma section", "Recreate this design", or any equivalent. No schema, Liquid, CSS, JavaScript, snippet, or file may be generated before the earlier gates are cleared, in order (see Mandatory Workflow Enforcement below).

0. Verify the status table isn't already stale before trusting it. Grep sections/ for a file matching the section's likely handle before starting — a pending row with a matching file already built (schema, CSS, JS wired up) means the table wasn't updated after a prior build, not that the section is unstarted. Reconcile the table first, then proceed.

1. Read the brief entry (## <Section Name>). If missing, mini-intake for that node, append entry, continue.

2. Re-fetch the live Figma node by stored node ID — call BOTH get_design_context (structure/data) AND get_screenshot (visual), every section, every time. Never skip the screenshot because the data looks complete — don't build from brief prose alone. Then compare the live Figma against the brief entry: if the design changed since the brief was written, list the diffs and report them before continuing.

   • Look at the screenshot before proposing anything. Data can be technically correct and still visually wrong — clipped nested components, optical spacing that doesn't match the coordinate math, overlaps, an asset/color that reads differently than its raw value. Actively compare the two: if the screenshot shows something the numbers don't explain (an element looks tighter/looser/bigger than its x/y/width/height imply), the screenshot wins — note the discrepancy and build from the visual read, don't silently trust the data.
   • This is a one-time pre-build look, not a repeated audit — one screenshot pull per section before coding. It does not replace or trigger the post-build Figma diff in step 6, and it is never repeated per code change (that would violate the no-re-audit-during-development rule).
   • Mandatory whenever the brief describes size/position/opacity qualitatively — those are exactly what gets eyeballed wrong. For decorative/background/off-canvas layers, pull real width/height/x/y/opacity and use them directly. For repeated/duplicated rows (marquees, tickers, tag lists), compute item gap from consecutive children's x/width (next.x - (prev.x + prev.width)) — never eyeball a round Tailwind gap value.
   • If Figma MCP is down or the node can't be fetched: tell the user live verification was unavailable, then present three schema-compliant implementation options derived from the existing brief entry alone, clearly labeled as fallback options (not verified against live Figma). The stop-and-wait gate in step 3 still applies unchanged — continue only after the user selects one. Never silently build from memory.

3. Never assume there is only one valid implementation, and never skip because the section "looks simple" — a static-looking banner can hide real ambiguity (fixed asset vs ? fixed gradient vs setting?). The options are implementation approaches (e.g. , , ), not different visual interpretations — and they must differ in substance, not cosmetically. For each option, state:

Mandatory Workflow Enforcement

The Phase 3 gates cannot be bypassed, batched, or collapsed — regardless of how the request is phrased, how simple the section looks, or how confident the read of the design is.

Never combine in a single response:

• Options + Schema
• Options + Code
• Schema + Code
• Options + Schema + Code

The only valid execution order is:

1. Read Brief
2. Fetch Latest Figma (get_design_context + get_screenshot; report brief-vs-live diffs before continuing)
3. Present Three Implementation Options (exactly three; one marked Recommended)
4. Wait for User Selection
5. Present Schema (schema + explanation only)
6. Wait for Schema Approval
7. Build

Skipping any stage — or producing a later stage's output before the earlier stage's user response has arrived — is a workflow violation. If Figma is unreachable, stage 2 is replaced by the disclosed brief-based fallback in step 2; every remaining gate still applies unchanged.

Unresolved risks block a silent built

If a brief entry lists an unresolved risk (missing asset, ambiguous spec, needs client input) affecting a visible part of the design, don't drop the feature and mark built as if it matches Figma. Before marking built: ask the user how to proceed, or build the best faithful approximation and record it as a Known deviation (what's missing, why). built = "matches Figma except documented deviations" — never an undocumented gap.

Figma-fidelity rules (each caused a real bug — apply on every section)

These are visual/design-parity lessons specifically. For Liquid/schema/Theme-Check-class bugs (syntax, deprecated filters, invalid JSON, missing snippet refs), check CLAUDE.md's "Liquid / section error log" too — it's the other half of this project's accumulated lessons and isn't duplicated here.

• Position by the layer's own coordinates, not visual grouping. A logo/badge/mark at its own absolute position near a corner is its own absolutely-positioned element anchored to that edge, even if it visually reads as "below" other content — never fold it into a sibling's flex/gap stack. Check get_metadata for that node's actual offsets when unsure.
• Resolve calc() + translate into one final pixel offset. Figma codegen often centers/offsets via left-[calc(50%-Npx)] + -translate-x-1/2 — this is ONE computation: final = (parentWidth/2 - N) - (layerWidth/2). Get real parentWidth from get_metadata (usually the section's own frame, not the inner page-width column). Ship the single resolved value as left-[Npx] (negative if it bleeds off-canvas). Never simplify to left-0 because it "looks roughly aligned" — it silently ships the wrong slice of the asset.
• A merchant-uploaded image_picker does NOT inherit Figma's internal asset math (exact width/left/top/rotation/opacity from codegen) — those numbers describe Figma's own source asset, not whatever the merchant uploads (different dimensions/aspect ratio/crop). For any layer whose schema setting is an image_picker (not a bundled fixed asset): keep CSS to positioning that's asset-independent (a bleed offset reflecting where the slot sits, e.g. -top-112), skip forced width/opacity/exact left/rotation, and confirm against a live rendered screenshot — not Figma's codegen numbers. Applies to rotation too: Figma's exact rotation degrees describe how its own source photo needed to turn — meaningless for an unrelated upload.
• Transparent-edge decorative/background images need the section's own bg color behind them — add style="background-color: rgb(var(--color-background));" (or the active scheme var) so any transparent/edge area blends regardless of what the merchant uploads.
• Never commit a raster fallback asset for a blank image_picker. Repo policy: assets/ holds SVG icons only — no photo/background raster "looks right until upload" fallbacks. Blank state = plain color-scheme background (or neutral placeholder), never a baked-in stand-in photo.
• A global section's Figma mock only shows one template's context. Header/footer (or anything enabled_on every page) may show a page-specific treatment (e.g. transparent floating header over a homepage hero) that's wrong elsewhere. Scope it (e.g. ), don't apply unconditionally.

QA is separate and manual

Only when the user explicitly asks does the qa agent audit against the same domain skills and write findings into the brief's QA section. A section becomes passed only after user-run QA clears it. Until then, built = "implemented, not yet QA'd". (Full mode-separation rule: CLAUDE.md "Two modes".)

Skill loading (keep development lean)

• Load only the skills the current section needs (static banner → shopify-liquid+tailwind-css+performance; no shopify-javascript unless interactive).
• Don't re-read a skill already in context for this task. Re-read only on domain change or if the skill file itself changed.

Status values

pending → built → passed (QA cleared) or blocked (QA found issues). Only an explicit QA run moves a section past built.

Reference files

• references/brief-template.md — before writing any section brief.
• references/design-tokens.md — when mapping Figma styles to tokens.