Theme Development Best Practices

Production Readiness Checklist

Before handing off a theme to a merchant or submitting to the Theme Store, verify every item below. These practices prevent support tickets, security issues, and performance regressions.

Architecture

• Online Store 2.0 JSON templates for all page types
• Section-based architecture — no monolithic template files
• Snippets for every repeated UI pattern (cards, icons, badges)
• Global design tokens in settings_schema.json exposed as CSS variables
• Section groups for header and footer in theme.liquid

Liquid & Security

• Use {% render %} exclusively — zero {% include %} tags
• Use routes object for every internal link
• | escape on all user/merchant content in HTML attributes
• Check != blank before rendering optional metafields and settings
• Never expose API secrets in Liquid, JavaScript, or theme files

Accessibility & i18n

• Skip-to-content link as first focusable element
• All images have descriptive alt text (empty alt for decorative)
• Form inputs have associated <label> elements
• Color contrast meets WCAG AA — do not rely on color alone for state
• All merchant-facing strings use locales/ and the | t filter

Tooling & Process

• shopify theme check passes with zero errors
• Git history with meaningful commits and tagged releases
• Develop on dev store, stage on unpublished theme, then publish
• Document section settings with clear schema labels and info text
• Lighthouse performance 90+ on homepage, collection, and product templates

# Pre-deploy command sequence
shopify theme check
shopify theme package
git status  # ensure clean working tree
git tag v$(date +%Y.%m.%d)
shopify theme push --unpublished --theme "Pre-release QA"