Shopify Theme Handbook

Companion tool

Need a fast, tickable QA pass or a one-page scan of the 22 Theme Store rules? Use the Theme Store Checklist — a lightweight companion site kept separate from this handbook.

What’s in this handbook

Section	Covers
1. Getting Started	What this handbook covers, prerequisites, your first local preview
2. Theme Store Requirements	Every Shopify requirement, in plain English, with code examples
3. Codebase Structure	Folders, theme blocks, sections, naming conventions, modern platform features
4. Scaffold Setup Guide	Step by step: empty folder → working section and block
5. AI-Assisted Development	How we build most things from here on: AGENTS.md, Figma MCP, Claude commands, Shopify’s own AI Toolkit
6. GitHub Workflow	Branching, PR review, CI automation — the loop you’ll use for everything from here on
7. CSS	Units (rem/em/62.5%), cascade & specificity, custom properties, architecture & naming, stylesheet/style tags, modern features, performance
8. JavaScript	Architecture & state/events, Web Components (both patterns), the {% javascript %} tag, theme editor events, modern features, performance
9. Style Guides	Liquid, clean code, third-party libraries
10. Design System & Configuration	Figma tokens, the three-tier token model
11. Config & Global Settings	settings_schema.json & settings_data.json rules/conventions, what’s required vs. optional
12. Presets	Theme, section, and block presets — real-world examples, benefits, and every rule marked mandatory or optional
13. Colors	Color palettes, color schemes, color tokens, Liquid color filters, color accessibility — everything color, dev and merchant perspective
14. Fonts	font_picker settings, the type scale, the font object and font_face/font_modify, font accessibility & performance
15. Spacing	The spacing scale, range settings, logical properties — everything spacing, dev and merchant perspective
16. Assets Management	Icons, responsive images, video, 3D/AR media — rendering, performance, and maintainability for every media type
17. Internationalization & Locales	i18n/RTL requirements, locale file management, and how settings_schema.json’s t: keys resolve into them
18. Performance	Performance strategy, the critical rendering path, budgets, built in from the start, not added later
19. Accessibility	Accessibility built into a section from the start, and kept consistent theme-wide
20. Quality & Validation	Linting, manual QA, the pre-submission checklist
21. Publishing	Partner Dashboard, store setup, packaging, review, life after approval
22. Tooling & Config	Project files, Theme-Store-only packaging, optional Tailwind/Alpine setup
23. Learning Articles	Step-by-step deep dives: Liquid objects, maintainable code
24. Reference	Cheatsheet, glossary, and a curated tools directory

New here? Start with sections 1 to 4, in order. After that, use search (⌘K) to find whatever you need.

Examples throughout use Solis, our current Theme Store project. But this handbook applies to any Shopify theme we build.