Shopify Theme Development Guidelines

Liquid Development

Valid Filters

Valid Tags

Validation Rules

• Use

  {% liquid %}

  for multiline code
• Maintain proper closing order
• Use object dot notation
• Apply defensive coding practices

Theme Architecture

Directory Structure

• sections/

  - Customizable page areas

• blocks/

  - Configurable elements

• layouts/

  - Repeated content

• snippets/

  - Reusable fragments

• config/

  - Settings

• assets/

  - Static files

• locales/

  - Translations

• templates/

  - Page structure specifications

UX Principles

• Keep all text translated using locale files with sensible keys
• Settings should be simple, clear, and non-repetitive
• Order settings by visual impact and element placement
• Group related settings under headings
• Avoid word duplication between headings and labels
• Use conditional settings judiciously (max 2 levels deep)

HTML Standards

• Use semantic HTML with modern features
• Implement ID naming as CamelCase
• Append block/section IDs appropriately
• Ensure interactive elements remain focusable
• Use

  tabindex="0"

  sparingly

CSS Guidelines

• Avoid ID selectors; maintain 0-1-0 specificity with single class selectors
• Use CSS variables for redundancy reduction
• Never hardcode colors; employ color schemes
• Apply BEM naming conventions
• Use mobile-first media queries with

  screen

  descriptor
• Limit nesting to first level except for media queries

JavaScript Principles

• Minimize external dependencies; prioritize native browser features
• Avoid

  var

  ; prefer

  const

  over

  let

• Use

  for...of

  loops instead of

  forEach()

• Implement module patterns to avoid global scope pollution
• Prefix private methods with

  #

• Group scripts by feature area

Performance Optimization

• Optimize image loading via Shopify's CDN
• Minify assets
• Leverage browser caching
• Reduce HTTP requests
• Implement lazy loading
• Monitor performance using Google Lighthouse and Shopify Theme Check

Example Section Schema

{% schema %}
{
  "name": "Section Name",
  "tag": "section",
  "class": "section-class",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "t:sections.section_name.settings.heading.label",
      "default": "Default Heading"
    }
  ],
  "blocks": [],
  "presets": [
    {
      "name": "t:sections.section_name.presets.name"
    }
  ]
}
{% endschema %}