shopify-store-builder

name	shopify-store-builder
description	Use when user wants to build, redesign, or clone a Shopify store using StorePipe MCP. Triggers on requests involving Shopify theme design, product creation, store setup, or cloning an existing store's design. Requires StorePipe MCP connector.

Shopify Store Builder

Version 1.2.0 (2026-04-04)

Changelog:

• v1.2.0: Added Nano Banana MCP for AI image generation, one-line installer
• v1.1.0: Added verification protocol (Firecrawl + store password), 17 Shopify-specific gotchas, pre-deploy checklist, mandatory HTML-first workflow, CSS !important rules, font loading fix
• v1.0.0: Initial release — clone/redesign/build modes, StorePipe MCP integration, brand discovery flow

Shopify expert skill powered by StorePipe MCP. Builds, redesigns, or clones Shopify stores — from brand identity to live staging theme.

When to Use

• User wants to create a new Shopify store design
• User wants to redesign their existing Shopify store
• User wants to clone/replicate another Shopify store's design
• User asks to create products, collections, or theme customizations via MCP
• User mentions StorePipe, Shopify theme, or store building

Required MCP Connectors

• StorePipe MCP — theme editing, product creation, image uploads
• Firecrawl MCP — store analysis for Clone mode AND visual verification of deployed themes
• Nano Banana MCP (optional) — AI image generation via Google Gemini 2.5 Flash. Use for generating product images, hero banners, lifestyle photos, and brand assets when cloning or building stores. Install via: npx nano-banana-mcp (requires a Gemini API key from https://aistudio.google.com/app/apikey)

Nano Banana MCP Setup

To add Nano Banana for AI image generation, add this to your Claude Code MCP settings:

{
  "mcpServers": {
    "nano-banana": {
      "command": "npx",
      "args": ["nano-banana-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Available tools:

• generate_image — Create images from text descriptions (product shots, hero images, lifestyle photos)
• edit_image — Modify existing images with text prompts
• continue_editing — Iteratively refine the last generated image
• get_last_image_info — Check current image state

When to use Nano Banana in this skill:

• Clone mode: generate product images that match the reference site's photography style
• New build mode: create hero banners, product shots, and lifestyle images matching the brand identity
• When the user doesn't have their own product photography yet
• To create placeholder images that match a specific aesthetic (minimalist jewelry on white, lifestyle shots, etc.)

IMPORTANT: Store Verification Requirements

Before starting any theme work, check if the store is password-protected (development/staging mode). If it is, you MUST tell the user:

"Your Shopify store is password-protected. To verify the theme looks correct after deployment, I need two things:

1. Your store password — so I can access the storefront and verify the design visually
2. Firecrawl MCP connected — I use Firecrawl's browser interaction to enter the password and inspect the rendered page

Without these, I can deploy the theme but cannot verify it matches the target design. You would need to check manually and report issues back to me."

If the user doesn't have Firecrawl: Explain that Firecrawl is needed for the visual verification loop and recommend they connect it from the MCP registry. Without it, the workflow becomes: build → deploy → user checks manually → user reports issues → fix blindly → repeat (slower and less accurate).

Flow

digraph flow {
  rankdir=TB;
  start [label="User request" shape=doublecircle];
  mode [label="Which mode?" shape=diamond];
  clone [label="A: Clone store" shape=box];
  redesign [label="B: Redesign existing" shape=box];
  fresh [label="C: Build from scratch" shape=box];
  scrape [label="Scrape reference\n(Firecrawl)" shape=box];
  audit [label="Audit existing store\n(StorePipe read tools)" shape=box];
  brand [label="Brand Discovery\n(3 rounds of questions)" shape=box];
  scope [label="Scope Selection\n(products, theme, SEO, config)" shape=box];
  html [label="Build HTML mockup\n(user approves)" shape=box];
  convert [label="Convert to Shopify\n(Liquid + CSS)" shape=box];
  verify [label="Verify via Firecrawl\n(computed styles check)" shape=box];
  fix [label="Fix issues" shape=box];
  review [label="Review + Preview Link" shape=doublecircle];

  start -> mode;
  mode -> clone [label="clone a store"];
  mode -> redesign [label="has store, wants new look"];
  mode -> fresh [label="starting fresh"];
  clone -> scrape -> scope;
  redesign -> audit -> brand -> scope;
  fresh -> brand -> scope;
  scope -> html -> convert -> verify;
  verify -> fix [label="issues found"];
  fix -> verify [label="re-verify"];
  verify -> review [label="all pass"];
}

Step 1: Mode Selection

Present three options:

Mode	When	What happens
A) Clone	User has a reference store URL	Scrape with Firecrawl, analyze design, recreate 1:1 for their brand
B) Redesign	User has existing store	Audit current store via MCP, then build new design
C) New build	Starting from zero	Brand discovery, then build everything

Step 2: Brand Discovery (Modes B & C)

Three conversational rounds, 2-3 questions each:

Round 1 — Basics: What do you sell? Who buys it? Brand name? Round 2 — Personality: 3 brand words? 2-3 admired brands? Price range? Round 3 — Visuals: Brand colors? Logo? Photography vibe?

Synthesize into a Brand Identity Summary with colors (hex), fonts, photography style, positioning. Get user confirmation before proceeding.

Step 3: Scope Selection

User picks from: Products & Collections, Theme Design, SEO & Content, Store Configuration. They can pick all or subset — confirm before executing.

Step 4: Execution

Products & Collections

• Propose full product list with names, prices, categories — get one confirmation, then batch-create
• Use create_product, upload_file for images, create smart collections by tag
• Assign product and collection images via GraphQL mutations

Theme Design (most critical)

4B.1 — Propose pages: Homepage, collection, product, about, contact. User confirms which ones.

4B.2 — MANDATORY: Design in HTML first:

• Build a complete standalone HTML file with all CSS inline/embedded
• Use real images from reference site (for clone mode) or Unsplash
• Apply exact design tokens: fonts, colors, spacing, layout
• Save as homepage-v2.html (or similar) in project directory
• Open in user's browser via start "" "path/to/file.html" command
• Wait for user approval before converting to Shopify
• This prevents wasted iterations — HTML is fast to iterate, Shopify is slow

4B.3 — Convert to Shopify (ONLY after user confirms HTML):

1. create_staging_theme from current live theme
2. upload_theme_image for every image into assets/ folder
3. Create each section as a .liquid file with {% schema %}
4. Create inline <style> in hero section to hide default theme header/footer
5. Update templates/index.json to wire all sections
6. get_staging_preview and share the link

4B.4 — MANDATORY: Verify via Firecrawl (if available):

1. Scrape the staging preview URL
2. Enter store password via firecrawl interact
3. Use page.evaluate(getComputedStyle) to verify critical properties
4. Check each fix against expected values
5. Loop until all checks pass
6. See "Verification Protocol" section below for details

Section requirements:

• Every text, image, link, color = a settings field (editable in customizer)
• Repeating elements (testimonials, features) = blocks
• Include presets so sections appear in "Add section" menu
• Prefix CSS classes (e.g., .brand-hero) to avoid conflicts
• HTML entities only — never raw Unicode (★ not ★)
• Always loading="lazy" and meaningful alt text on images

SEO & Content

• Generate meta titles/descriptions for products and pages
• Create About, FAQ, blog posts with brand-voice copy

Store Configuration

• Guide navigation, shipping, payment setup

Mode A: Clone Store (Detailed)

Scrape with Firecrawl

Scrape 4 pages: homepage, collection, product, about. Extract:

• Section order, types, headings, layouts
• Color palette (exact hex values from CSS)
• Typography (font families)
• Navigation structure
• Product card style
• Footer structure
• Overall aesthetic

Also use page.evaluate to extract exact computed styles:

// Extract design tokens from reference site
firecrawl interact -c "
const data = await page.evaluate(() => {
  const hero = document.querySelector('h1, .hero__heading, [class*=hero] h1');
  const nav = document.querySelector('nav a, [class*=nav] a');
  const btn = document.querySelector('.btn, button, [class*=cta]');
  const r = {};
  if (hero) { const cs = getComputedStyle(hero); r.hero = { font: cs.fontFamily, size: cs.fontSize, weight: cs.fontWeight, style: cs.fontStyle, color: cs.color }; }
  if (nav) { const cs = getComputedStyle(nav); r.nav = { font: cs.fontFamily, size: cs.fontSize, weight: cs.fontWeight, letterSpacing: cs.letterSpacing }; }
  if (btn) { const cs = getComputedStyle(btn); r.btn = { bg: cs.backgroundColor, color: cs.color, border: cs.border, padding: cs.padding }; }
  return r;
});
JSON.stringify(data, null, 2);
"

Present analysis to user with plan for their brand adaptation. Get confirmation.

Clone Principles

Element	Approach
Layout	Pixel-perfect replica — same spacing, grid, sections, hover effects, animations
Text	Same copy structure adapted for user's brand name and products. Same tone and length
Images	Use reference site images during development. User replaces with own images later
Logo	Generated in same style (wordmark, monogram, etc.) for user's brand name
Design tokens	Extract and reuse exact colors, fonts, border-radius, shadows from reference CSS
Goal	Side-by-side, both stores look like same agency designed them

Image Recreation (using Nano Banana MCP)

If Nano Banana MCP is connected, use it to generate original images:

For each reference image:

1. Analyze: subject, pose, angle, lighting, color temperature, background, mood, aspect ratio
2. Write exact-match prompt reproducing the same scene
3. Use generate_image from Nano Banana to create the image
4. Use continue_editing to refine until it matches the reference style
5. Upload the generated image to Shopify via upload_theme_image

If Nano Banana is NOT available:

• Use reference site images during development (for local preview only)
• Unsplash fallback with specific keywords
• Tell the user to replace with their own product photography before publishing

5. Upload via upload_theme_image

Verification Protocol

When Firecrawl + Store Password Available

After deploying to staging, run this verification loop:

# 1. Scrape the staging preview
firecrawl scrape "https://STORE.myshopify.com/?preview_theme_id=THEME_ID" --format screenshot

# 2. Enter store password
firecrawl interact "Enter 'PASSWORD' in the password field and click submit"

# 3. Verify computed styles (THE SOURCE OF TRUTH)
firecrawl interact -c "
const data = await page.evaluate(() => {
  const r = {};
  const h1 = document.querySelector('.PREFIX-hero__heading');
  if (h1) { const cs = getComputedStyle(h1); r.hero_font = cs.fontFamily; r.hero_style = cs.fontStyle; }
  const btn = document.querySelector('.PREFIX-btn-solid-white');
  if (btn) { const cs = getComputedStyle(btn); r.btn_bg = cs.backgroundColor; r.btn_color = cs.color; }
  r.swatch_count = document.querySelectorAll('.PREFIX-pcard__swatch').length;
  const css = Array.from(document.querySelectorAll('link[rel=stylesheet]')).map(l => l.href).filter(h => h.includes('PREFIX'));
  r.css_loaded = css.length > 0;
  const fonts = Array.from(document.querySelectorAll('link[href*=fonts]')).length;
  r.fonts_loaded = fonts > 0;
  return r;
});
JSON.stringify(data, null, 2);
"

# 4. Stop session when done
firecrawl interact stop

CRITICAL: Do NOT trust Firecrawl AI agent's visual descriptions for style checks. The AI reads the accessibility tree (text-only), not visual rendering. Always use page.evaluate(getComputedStyle) for reliable verification.

What to verify:

• Google Fonts <link> tag loaded in DOM
• Custom CSS file loaded in DOM
• Hero heading uses correct font-family
• Hero heading is italic (if expected)
• CTA buttons have correct background-color
• Product swatches render (count > 0)
• Default theme header hidden
• Default theme footer hidden
• All section images loading

When Firecrawl NOT Available

Tell the user:

"I've deployed the theme to staging. Since I can't verify it visually without Firecrawl and your store password, please check the preview link and let me know what doesn't match. Screenshots are very helpful for me to fix issues quickly."

Step 5: Review & Launch

Present summary: products created, theme preview link, SEO status, content created. Provide launch checklist (preview → publish → domain → payments → test order).

Rules

1. Never publish a theme. Always staging. Merchant publishes manually.
2. Never skip confirmation. Show plan, get approval, then execute.
3. Never use raw Unicode in Liquid. HTML entities only.
4. Upload images before referencing. No external URLs in theme code.
5. Dynamic sections always. Every section gets {% schema %} for customizer.
6. Prefix CSS classes. Avoid base theme conflicts.
7. Be opinionated. Propose specific designs, don't ask open-ended layout questions.
8. Group work. Batch-create products after one approval, not one-by-one.
9. Clone = pixel-perfect. Match everything: layout, spacing, colors, fonts, animations.
10. Plan before executing. Always present what you'll build and get confirmation first.
11. HTML first, always. Never convert to Shopify without user-approved HTML mockup.
12. Verify after deploy. Always run the verification protocol if Firecrawl is available.

Shopify-Specific Gotchas (CRITICAL)

These are hard-won lessons. Every one of these has caused bugs in real builds.

CSS Issues

Gotcha	Why it Happens	Fix
@import url() for Google Fonts gets stripped	Shopify's asset pipeline strips @import from CSS files	Always load Google Fonts via <link> tag in the hero/first section's Liquid file, NOT in the CSS
Base theme CSS overrides custom styles	Shopify themes (Horizon, Dawn, etc.) have aggressive CSS with high specificity	Add !important to ALL custom styles — fonts, backgrounds, colors, padding, display, flex properties
CSS custom properties (var(--x)) not working	Base theme may redefine the same variables	Use !important on the property value, or use hardcoded values instead of variables for critical styles
SVG logos/images render at natural size	SVGs without explicit dimensions expand to fill container	Always set height, width: auto, and max-width with !important on SVG images

Font Loading

Gotcha	Fix
Google Fonts not rendering	Load via <link rel="preconnect"> + <link href="...css2?family=..."> in the FIRST section's Liquid file
Font specified but not italic	Must include font-style: italic !important separately — font-family alone doesn't make it italic
Inter font everywhere despite custom font set	Base theme loads Inter as default — your font-family needs !important

Template & Section Issues

Gotcha	Fix
Default theme header/footer still showing	Add inline <style> in hero section: #header-group, .shopify-section-group-header-group { display:none!important; } AND body>footer, .shopify-section-group-footer-group { display:none!important; } AND reset body { --header-height:0px!important; --header-group-height:0px!important; }
Content pushed down by hidden header	Reset --header-height and --header-group-height CSS vars to 0px !important
collection setting type doesn't work in index.json	Use text field with collection handle instead. collection type only works from the theme customizer UI
Empty product grid (no products in collection)	Always provide fallback product_card blocks with images from theme assets
Product images not showing	Products need images attached via Shopify admin. Use upload_file then associate, OR use fallback blocks with theme asset images
col.image | image_url crashes on nil	Always check col.image != blank before calling image_url

Asset Issues

Gotcha	Fix
External image URLs in Liquid	Never reference external URLs. Always upload_theme_image first, then use {{ 'filename.jpg' | asset_url }}
Section filename conflicts with base theme	Always prefix: avax-hero.liquid not hero.liquid
Press/logo SVGs too large	Force height: 22px !important; width: auto !important; max-width: 160px !important;

Liquid Logic Issues

Gotcha	Fix
block.settings.value != blank not working for empty strings	Use triple check: value != blank and value != "" and value != empty
Swatch colors not rendering	Assign to local variable first: {%- assign sw = block.settings.swatch_1 -%} then check
Unicode characters breaking Liquid	Use HTML entities: ★ not ★, — not —, & not &

Pre-Deploy Checklist

Run through this checklist BEFORE declaring the theme done:

• Google Fonts loaded via <link> tag (not @import)
• All CSS properties have !important where they override base theme
• Default header hidden via inline <style> in first section
• Default footer hidden via inline <style> in first section
• --header-height and --header-group-height reset to 0px
• All images uploaded to assets/ via upload_theme_image
• No external image URLs in any Liquid file
• All section filenames prefixed (e.g., avax-hero.liquid)
• All section CSS classes prefixed (e.g., .avax-hero__heading)
• Fallback blocks exist for product sections (in case collections are empty)
• {% schema %} includes presets for every section
• Collection handles in index.json use text type, not collection type
• SVG images have explicit dimensions set
• Footer has no "Powered by Shopify" leak

Common Mistakes

Mistake	Fix
Using Unicode in Liquid	Use ★ ◆ —
External image URLs in theme code	Upload to assets/ first via upload_theme_image
@import url() for fonts in CSS file	Use <link> tag in Liquid section HTML
CSS without !important	Base theme wins specificity war — always use !important
collection setting in index.json	Use text field with collection_handle
col.image | image_url on nil image	Check col.image != blank first
Same section filename as base theme	Prefix with brand: avax-hero.liquid not hero.liquid
Forgetting to hide default header/footer	Inline <style> in first section with display:none!important
Trusting Firecrawl AI visual descriptions	Use page.evaluate(getComputedStyle) instead — it reads actual CSS values
Not checking if store is password-protected	Ask for password + Firecrawl at the start of every project