figma-to-shopify-section

Figma → Shopify Section

Build a Shopify section from a Figma frame. Read the theme first, follow its conventions, wire the new section into a template so it renders, preview through a browser MCP, and verify visually against the Figma source before declaring done.

This skill is structured for progressive disclosure. Read the relevant references/*.md file for each phase rather than holding everything in working memory.

Hard rules (non-negotiable)

1. Never hand back unverified work. If the section can't be loaded in a browser MCP and screenshot-diffed against the Figma frame, the work is not done. Stop and ask the developer to set up what's missing.
2. Stop and warn if Figma MCP is missing. Don't try to substitute screenshots, eyeballed dimensions, or guesses. Direct the developer to install the Figma MCP server.
3. Stop and warn if no browser-control MCP is available. Without it the verify loop is impossible.
4. Stop and warn if a font in the Figma frame isn't loaded by the theme. Don't silently substitute a system font. The developer needs to license and load the right font.
5. Never auto-commit. Stage files (git add) and suggest a commit message. The developer commits.

Workflow (5 phases)

Run each phase in order. Don't skip ahead to "generate liquid" without doing the prerequisites and theme-reading phases — that's how the output drifts from the theme's conventions.

Phase 1 — Prerequisites & setup

Verify the environment before reading any Figma data. Read references/prerequisites-and-setup.md for the full check.

Quick checklist:

• Figma MCP available? (look for mcp__figma* tools in the deferred-tools list or active tool list)
• Browser-control MCP available? (Claude in Chrome mcp__claude-in-chrome__* or Chrome DevTools MCP)
• Dev server running? Detect the port — default http://127.0.0.1:9292, but check shopify.theme.toml in the theme root for an override.
• Where will this section preview? (homepage, product, collection, page) Ask if not implied by the Figma frame name.

If any fail, stop and tell the developer specifically what's missing and how to add it.

Phase 2 — Read the theme

Before generating anything, read the theme's actual conventions rather than assuming Dawn defaults. Read references/reading-the-theme.md for the full procedure.

Minimum reads:

• 2–3 existing sections/*.liquid (closest to what you're about to build) — learn their CSS approach (BEM? Tailwind? CSS variables?), JS pattern, schema style.
• config/settings_schema.json — color schemes, typography tokens, container widths the theme exposes.
• An existing templates/*.json similar to where this section will live — to know what JSON shape to emit when wiring it in.
• The existing image / video markup pattern in a sibling section — to match loading, srcset, sizes, playsinline conventions exactly.

Phase 3 — Generate

Write the section file, its CSS, its JS (only if it has interactive behavior), its snippets, and its asset SVGs. Read references/section-anatomy.md for the scaffold and schema rules. Read references/css-and-tokens.md, references/javascript-patterns.md, references/images-videos-fonts.md, references/translation-files.md for each concern.

Stamp the Figma frame ID at the top of the section file as a comment so re-runs can detect and update instead of duplicating:

{%- comment -%} figma:<file-key>:<node-id> {%- endcomment -%}

Phase 4 — Wire the preview

A section file alone renders nothing. Add it to a template JSON. Read references/preview-and-verify.md for the wiring rules and sample-content guidance.

Two strategies:

• Direct insertion — append the section to templates/index.json (or the contextually correct template) at the end of order. Simple, but pollutes the developer's real template.
• Throwaway preview template — create templates/page.preview-{section}.json and have the developer hit /pages/preview-{section}. Cleaner, but requires the page handle to exist.

Default to direct insertion unless the developer says otherwise. Always populate sample content in the section's settings (heading, image alt, button label, etc.) drawn from the Figma text layers — empty defaults look broken in preview and produce a false negative diff.

Phase 5 — Verify

The work isn't done until the verify loop passes. Read references/preview-and-verify.md § Verify for the full procedure.

In order:

1. Wait ~1.5s after the last file write (Shopify CLI hot-reload propagation), or watch the dev-server WebSocket reload event via the browser MCP console.
2. Hard-reload the preview URL (Cmd+Shift+R or Network → Disable Cache → reload). Soft reload serves stale assets.
3. Screenshot at each Figma breakpoint — typically 375 (mobile), 768 (tablet), 1440 (desktop). Match each to the corresponding Figma frame.
4. Diff each screenshot against its Figma frame. Be concrete: "button color is #1A1A1A, Figma says #0F0F0F"; "vertical padding is 32px, Figma says 40px." Vague "looks close" is a fail.
5. Read the browser console — surface any errors or warnings.
6. Read the network tab — flag any 404s on assets.
7. If shopify theme check is installed, run it and report any new issues introduced.
8. Present both screenshots side-by-side to the developer along with the diff list. Then git add the new files and suggest a commit message. Don't commit.

If the diff has any issue, iterate inside this phase — don't declare done with known mismatches.

Common mistakes this skill prevents

• Generating a section file without wiring it into a template, then telling the developer "it's ready" — they open the editor and see nothing.
• Using Dawn defaults when the theme has its own conventions.
• Inline style="color: #..." from Figma fills, hardcoding colors that should come from color_scheme settings.
• Missing the translation file write — schema labels show as raw t:sections.foo.settings.bar strings in the editor.
• Silently substituting system fonts when the Figma font isn't loaded.
• Screenshotting before hot-reload propagates → false-negative diff.
• Soft-reloading after a CSS change → stale styles in screenshot → false-negative diff.
• Calling work done after generating files without ever loading the preview URL.

When this skill does NOT apply

• The user wants a whole page (not a section) — different scope; sections compose pages, but page templates have their own JSON shape and considerations.
• The user wants a theme app extension or app block — different file structure (blocks/*.liquid in an app extension), different schema conventions.
• The Figma frame is a design system component (atom-level button, input) — extract as a snippet via a smaller scope, not a section.
• There is no Figma source — the skill assumes Figma MCP. For freehand "make me a hero section," skip this skill.

References

File	When to read
references/prerequisites-and-setup.md	Phase 1 — every run
references/reading-the-theme.md	Phase 2 — every run
references/section-anatomy.md	Phase 3 — every run
references/css-and-tokens.md	Phase 3 — when generating CSS
references/javascript-patterns.md	Phase 3 — when the section has interactive behavior
references/images-videos-fonts.md	Phase 3 — when the section has images, videos, or text with custom fonts
references/sliders.md	Phase 3 — when the section has a horizontal slider, carousel, or "swipe to see more" pattern
references/translation-files.md	Phase 3 — every run (schema labels need translation entries)
references/preview-and-verify.md	Phases 4 & 5 — every run
references/gotchas.md	When something is broken or behaves oddly

Bundled assets

Path	Purpose
examples/hero-banner/	Canonical generated section showing every convention. Read when in doubt about the expected output shape.
scripts/validate-section.sh	Bash sanity check on a generated section. Run in Phase 5 before declaring done. Usage: bash <plugin-root>/skills/figma-to-shopify-section/scripts/validate-section.sh <theme-root> <section-name>