Theme Dev

• JSON templates replace Liquid templates — merchants control section order
• Sections everywhere — not just the homepage
• App blocks — third-party apps render as sections
• Metafield connections — dynamic content without code changes

Shopify CLI

Development

shopify theme dev                    # Start local dev server with hot reload
shopify theme dev --store=my-store   # Specify store
shopify theme dev --theme-editor-sync # Sync editor changes to local

Deployment

shopify theme push                   # Push to connected theme
shopify theme push --unpublished     # Push as unpublished (preview)
shopify theme push --allow-live      # Push to live theme (use carefully)
shopify theme pull                   # Pull remote changes to local

Quality

shopify theme check                  # Lint theme for best practices
shopify theme check --auto-correct   # Auto-fix common issues

Theme Info

shopify theme list                   # List all themes on store
shopify theme info                   # Show current theme details
shopify theme open                   # Open theme in browser

Development Workflow

1. Pull latest from version control
2. Run shopify theme dev — local server at http://127.0.0.1:9292
3. Edit files — hot reload updates the browser
4. Test at multiple viewports — mobile (375px), tablet (768px), desktop (1440px)
5. Run shopify theme check — lint before committing
6. Commit and PR — never push directly to the live theme
7. Preview — push as unpublished, share preview link with client
8. Deploy — merge PR, push to live theme

Dawn-Based Customization

Dawn is Shopify's reference theme. Extend it, don't fork it.

When to Extend (Preferred)

• Adding new sections
• Modifying existing section settings
• Adding CSS overrides
• Creating new templates

When to Fork (Last Resort)

• Fundamentally changing layout structure
• Replacing the cart system
• Major navigation changes
• Client needs something Dawn doesn't support at all

Keeping the Upgrade Path

• Keep Dawn's original files intact where possible
• Add custom sections with unique names (prefixed: custom-hero.liquid)
• Override styles in a separate CSS file, not inline in Dawn's files
• Document every modification for future upgrades

Theme Settings (settings_schema.json)

Global settings that apply site-wide. Organized in groups.

[
  {
    "name": "Colors",
    "settings": [
      {
        "type": "color",
        "id": "color_primary",
        "label": "Primary color",
        "default": "#1a1a1a",
        "info": "Used for buttons, links, and accents"
      },
      {
        "type": "color",
        "id": "color_background",
        "label": "Background color",
        "default": "#ffffff"
      }
    ]
  },
  {
    "name": "Typography",
    "settings": [
      {
        "type": "font_picker",
        "id": "font_heading",
        "label": "Heading font",
        "default": "helvetica_n4"
      },
      {
        "type": "range",
        "id": "font_body_scale",
        "label": "Body font size scale",
        "min": 80,
        "max": 130,
        "step": 5,
        "default": 100,
        "unit": "%"
      }
    ]
  }
]

Setting Design Principles

• Group logically — Colors, Typography, Layout, Social, Cart
• Provide defaults — Every setting should work out of the box
• Write helpful labels — Merchant-friendly, not developer jargon
• Add info text — Explain what the setting changes
• Use appropriate types — color_scheme over color for theme consistency

Asset Management

CSS Organization

assets/
  base.css              # Reset, variables, typography
  component-header.css  # Per-component styles
  component-footer.css
  section-hero.css      # Per-section styles
  custom.css            # Custom overrides (load last)

No Framework Bloat

• Vanilla CSS with custom properties
• Use CSS Grid and Flexbox — no framework needed
• Load styles per-section when possible (reduces initial CSS)
• Minify in CI, not manually

JavaScript

assets/
  global.js             # Shared utilities, event delegation
  product-form.js       # Component-specific JS
  cart-drawer.js        # Feature-specific JS

• Vanilla JS only — no jQuery, no React, no build step
• Use defer attribute on script tags
• Event delegation over individual listeners
• Web Components for complex interactive elements

Conditional Loading

{% if section.settings.enable_video %}
  {{ 'component-video.css' | asset_url | stylesheet_tag }}
  <script src="{{ 'video-player.js' | asset_url }}" defer></script>
{% endif %}

Image Optimization

Responsive Images

{{
  product.featured_image | image_url: width: 1200 | image_tag:
    loading: 'lazy',
    decoding: 'async',
    widths: '200,400,600,800,1000,1200',
    sizes: '(min-width: 1200px) 50vw, (min-width: 750px) 33vw, 100vw'
}}

Hero Images (Above the Fold)

{{
  section.settings.hero_image | image_url: width: 1920 | image_tag:
    loading: 'eager',
    fetchpriority: 'high',
    sizes: '100vw'
}}

Rules:

• Above the fold: loading: 'eager', fetchpriority: 'high'
• Below the fold: loading: 'lazy', decoding: 'async'
• Always provide sizes attribute for responsive images
• Use widths to generate multiple srcset entries
• Shopify CDN handles format conversion (WebP/AVIF) automatically

Performance Targets

Performance Checklist

• Preload critical assets (hero image, main font)
• Defer all JavaScript with defer or async
• Load section-specific CSS only when section is rendered
• Use native lazy loading for below-fold images
• Avoid render-blocking third-party scripts in <head>
• Use font-display: swap for custom fonts
• Minimize Liquid output (whitespace stripping, minimal comments)

Accessibility

Semantic HTML

<header role="banner">
<nav aria-label="Main navigation">
<main id="main-content">
<section aria-labelledby="section-heading">
<footer role="contentinfo">

Skip Link

<a class="skip-to-content-link" href="#main-content">
  {{ 'accessibility.skip_to_content' | t }}
</a>

Focus Management

/* Visible focus indicators */
:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

/* Remove outline only for mouse users */
:focus:not(:focus-visible) {
  outline: none;
}

ARIA for Dynamic Content

<button
  aria-expanded="false"
  aria-controls="cart-drawer"
  data-cart-toggle
>
  Cart ({{ cart.item_count }})
</button>

<div id="cart-drawer" aria-hidden="true" role="dialog" aria-label="Shopping cart">
  ...
</div>

Color Contrast

• Text: minimum 4.5:1 ratio (AA)
• Large text (18px+ or 14px+ bold): minimum 3:1 ratio
• UI components and focus indicators: minimum 3:1 ratio
• Test with Lighthouse accessibility audit

Deployment

Version Control

• Use Git for all theme development
• Branch naming: feat/section-name, fix/cart-bug
• PR-based workflow — never push directly to live
• Include screenshots in PRs for visual changes

CI/CD with GitHub Actions