shopify-theme-pro

# 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