Shopify Theme Pro

---
name: shopify-theme-pro
description: Shopify Theme Development Pro - Complete theme development, deployment, and design system management for OpenClaw agents. Use when building Shopify themes, writing Liquid templates, pushing theme changes, deploying to stores, or managing design systems. Triggers on Shopify theme, Liquid templating, theme development, theme deployment, push theme, Shopify design system, Online Store 2.0, theme sections.
---

# 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:

```bash
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:

```bash
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:

```bash
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:**
```json
{
  "sections": {
    "header": {
      "type": "header"
    },
    "main": {
      "type": "main-product"
    }
  },
  "order": ["header", "main"]
}
```

### Liquid Templating Essentials

**Basic Syntax:**
```liquid
{%- # 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:

```bash
shopify theme init
```

Or clone an existing theme:

```bash
shopify theme pull --theme <THEME_ID>
```

### 2. Local Development

Run the dev server:

```bash
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:

```bash
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

```bash
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:

```bash
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:**
```liquid
<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`):**
```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:**
```liquid
{% 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):**
```javascript
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:**
```javascript
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