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:

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

shopify-theme-pro

Safety Notice

Copy this and send it to your AI assistant to learn