Shopify Theme Pro

Shopify Theme Development Pro - Complete theme development, deployment, and design system management for OpenClaw agents. Use when building Shopify themes, w...

Shopify Theme Development Pro

End-to-end Shopify theme development, deployment, and design system management. Covers Liquid templating, Online Store 2.0 architecture, performance optimization, deployment workflows, and CSS design systems.

When to Use

Apply this skill when:

• Building new Shopify themes or theme sections
• Writing or refactoring Liquid templates
• Implementing theme customization features
• Deploying theme changes to development or live stores
• Optimizing theme performance (speed, accessibility, SEO)
• Creating or maintaining a CSS design system for Shopify
• Reviewing theme code for quality and standards
• Migrating themes to Online Store 2.0
• Working with Shopify CLI (development, push, pull)

Quick Start

Local Development

Start a local dev server with hot reload:

shopify theme dev --store=your-store.myshopify.com

Visit http://localhost:9292 to preview changes in real-time.

Deploy to Store

Push local changes to a theme:

shopify theme push --theme <THEME_ID>

See references/deployment.md for the full pre-flight checklist and deployment workflow.

Create New Section

Generate a section scaffold:

mkdir -p sections
touch sections/my-section.liquid

See references/liquid-patterns.md for common section patterns and schemas.

Core Concepts

Theme Architecture

Directory Structure:

theme/
├── assets/          # CSS, JavaScript, images
├── config/          # Theme settings (settings_schema.json, settings_data.json)
├── layout/          # Template wrappers (theme.liquid required)
├── sections/        # Reusable, customizable content modules
├── snippets/        # Reusable code fragments
├── templates/       # Page-type templates (JSON or Liquid)
└── locales/         # Translation files (en.default.json, etc.)

Key Principles:

• Sections are merchant-customizable modules (can include blocks)
• Snippets are reusable code fragments (not directly customizable)
• Templates wrap sections and define page layouts
• Layouts provide recurring elements (header, footer, scripts)
• Online Store 2.0 uses JSON templates to wrap sections (preferred)

Online Store 2.0 Architecture

✅ DO:

• Use JSON templates (allows sections on any page)
• Design for app block integration
• Enable merchant customization via settings schemas
• Allow sections to be reordered and toggled

❌ DON'T:

• Lock sections to specific templates
• Hardcode content that should be editable
• Use legacy Liquid-only templates for new themes

JSON Template Example:

{
  "sections": {
    "header": {
      "type": "header"
    },
    "main": {
      "type": "main-product"
    }
  },
  "order": ["header", "main"]
}

Liquid Templating Essentials

Basic Syntax:

{%- # Output variables -%}
{{ product.title }}
{{ product.price | money }}

{%- # Control flow -%}
{% if product.available %}
  <button type="submit">Add to Cart</button>
{% else %}
  <span class="sold-out">Sold Out</span>
{% endif %}

{%- # Loops -%}
{% for variant in product.variants limit: 10 %}
  {{ variant.title }}: {{ variant.price | money }}
{% endfor %}

{%- # Filter chaining (processes left to right) -%}
{{ product.description | strip_html | truncate: 150 | upcase }}

Performance Tips:

• Use {%- -%} to strip whitespace and reduce HTML size
• Chain filters efficiently
• Limit loops where possible ({% for item in array limit: 10 %})
• Use the liquid tag for nested logic blocks

See references/liquid-patterns.md for advanced patterns.

Development Workflow

1. Setup

Initialize a new theme from a template:

shopify theme init

Or clone an existing theme:

shopify theme pull --theme <THEME_ID>

2. Local Development

Run the dev server:

shopify theme dev --store=your-store.myshopify.com

Changes auto-sync to the dev theme and reload the browser.

3. Quality Checks

Run Theme Check linter:

shopify theme check

Fix any errors or warnings before deploying.

4. Deployment

See the full deployment workflow in references/deployment.md. Key steps:

• Pre-flight checks (target theme, credentials, git status)
• Artifact scan (debug code, TODOs, localhost URLs)
• Push to store
• Post-push verification

shopify theme push --theme <THEME_ID>

IMPORTANT: Never push to live theme without --allow-live flag and explicit confirmation.

5. Publish

Promote a theme to live:

shopify theme publish --theme <THEME_ID>

Performance Optimization

See references/performance.md for detailed optimization strategies.

Quick Wins:

• Minimize JavaScript usage (prefer native browser features)
• Lazy load images (loading="lazy")
• Defer non-critical CSS
• Use responsive images (srcset)
• Compress assets (minify CSS/JS, optimize images)
• Implement resource hints (preload, dns-prefetch)
• Test on real mobile devices and slow connections

Avoid:

• Synchronous scripts in <head>
• Heavy JavaScript libraries for simple interactions
• Uncompressed images
• Render-blocking CSS

Accessibility Standards

Build accessibility from the ground up:

• Use semantic HTML elements
• Provide ARIA labels and roles where needed
• Ensure keyboard navigation works
• Maintain sufficient color contrast (WCAG AA minimum)
• Test with screen readers (VoiceOver, NVDA)
• Support reduced motion preferences

Example:

<button
  type="button"
  aria-label="{{ 'cart.add_to_cart' | t }}"
  aria-describedby="variant-{{ variant.id }}"
>
  {{ 'cart.add' | t }}
</button>

Design System Management

See references/design-system.md for building and maintaining a CSS design system.

Key Components:

• Brand colors (primary, secondary, accent, neutral scales)
• Typography scale (headings, body, labels)
• Spacing system (4px or 8px base unit)
• Component library (buttons, cards, grids, forms)
• Responsive breakpoints
• CSS custom properties (variables)

Approach:

• Define design tokens in assets/variables.css or config/settings_schema.json
• Build reusable component classes
• Document component usage in references/design-system.md
• Keep components merchant-customizable via theme settings

Merchant Customization

Enable merchants to customize themes without code:

Theme Settings (config/settings_schema.json):

{
  "name": "Colors",
  "settings": [
    {
      "type": "color",
      "id": "color_primary",
      "label": "Primary Color",
      "default": "#000000"
    },
    {
      "type": "font_picker",
      "id": "font_heading",
      "label": "Heading Font",
      "default": "helvetica_n4"
    }
  ]
}

Section Settings:

{% schema %}
{
  "name": "Featured Collection",
  "settings": [
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    },
    {
      "type": "range",
      "id": "products_to_show",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4,
      "label": "Products to show"
    }
  ],
  "blocks": [
    {
      "type": "heading",
      "name": "Heading",
      "settings": [
        {
          "type": "text",
          "id": "heading",
          "label": "Heading"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Featured Collection"
    }
  ]
}
{% endschema %}

Shopify CLI Reference

Development:

• shopify theme init — Create new theme from template
• shopify theme dev — Local dev server with hot reload
• shopify theme list — List all themes on the store
• shopify theme open — Open theme in Shopify admin

Deployment:

• shopify theme push — Push local changes to store
• shopify theme pull — Pull remote changes to local
• shopify theme publish — Set theme as live
• shopify theme share — Generate shareable preview link
• shopify theme package — Create distributable ZIP

Quality:

• shopify theme check — Run linter
• shopify theme check --auto-correct — Auto-fix issues

Flags:

• --store <store.myshopify.com> — Target store
• --theme <THEME_ID> — Target specific theme
• --allow-live — Allow pushing to live theme (requires confirmation)
• --only <glob> — Push specific files only
• --ignore <glob> — Skip specific files
• --nodelete — Don't delete remote files missing locally

Ajax API for Interactivity

Common use cases:

• Add to cart without page reload
• Update cart counter dynamically
• Product quick view
• Search suggestions

Example (Add to Cart):

fetch(`${window.Shopify.routes.root}cart/add.js`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: variantId,
    quantity: 1
  })
})
.then(response => response.json())
.then(item => {
  console.log('Added to cart:', item);
  // Update cart UI
})
.catch(error => console.error('Error:', error));

Get Cart Contents:

fetch(`${window.Shopify.routes.root}cart.js`)
  .then(response => response.json())
  .then(cart => console.log('Cart:', cart));

See Shopify Ajax API docs for all endpoints and response schemas.

Code Quality Standards

✅ DO:

• Use version control (Git)
• Write clear, maintainable code
• Document complex logic with comments
• Follow Liquid style conventions
• Use Theme Check in CI/CD pipelines
• Test on multiple devices and browsers

❌ DON'T:

• Obfuscate code
• Manipulate search engines deceptively
• Hardcode merchant-specific data
• Ignore Theme Check warnings
• Skip accessibility testing

Testing Checklist

Before deploying to production:

• Run shopify theme check with no critical errors
• Test on mobile devices (iOS and Android)
• Verify accessibility with screen reader
• Check performance scores (Lighthouse: 90+ recommended)
• Test all customization options in theme editor
• Verify translations in all supported locales
• Test cart and checkout flow end-to-end
• Validate on slow 3G network
• Check browser compatibility (last 2 major versions)
• Review security best practices (HTTPS, CSP headers)

Common Patterns

See references/liquid-patterns.md for detailed examples:

• Modular section development
• Reusable snippet patterns
• Product card components
• Dynamic section rendering
• Metafield access patterns
• Custom form handling

Resources

• Official Docs: https://shopify.dev/docs/themes
• Liquid Reference: https://shopify.dev/docs/api/liquid
• Theme Check: https://shopify.dev/docs/storefronts/themes/tools/theme-check
• CLI Reference: https://shopify.dev/docs/themes/tools/cli
• Ajax API: https://shopify.dev/docs/api/ajax
• Best Practices: https://shopify.dev/docs/themes/best-practices

Navigation

• references/liquid-patterns.md — Common Liquid patterns and section schemas
• references/design-system.md — CSS design system guidelines
• references/deployment.md — Full deployment workflow and pre-flight checklist
• references/performance.md — Performance optimization strategies

---

Version: 1.0 (Combined from shopify-theme-dev + shopify-theme-push) Last Updated: 2026-03-13