Getting Started

TL;DR: What this handbook is, who it’s for, and how to use it.

This handbook is the one place our team goes to learn how to build a Shopify theme from scratch. It also covers how to get that theme approved on the Shopify Theme Store. It walks you through everything, from your first day on the project to the day you submit the finished theme for review.

This handbook assumes you’ve already worked on a Shopify theme before. See What This Handbook Covers for exactly who this is (and isn’t) written for. The examples use Solis, our current Theme Store project, but everything here applies to any Shopify theme we build in the future. This handbook won’t get retired once Solis ships.

What you’ll build

We build things the way Horizon does. Horizon is Shopify’s modern, block-based way of building themes, introduced in 2025. “Block-based” means the page is built from small, reusable pieces called blocks (think of a button, an image, or a text section) that a merchant can add, remove, or rearrange in the theme editor.

Horizon uses nested theme blocks (blocks placed inside other blocks), @theme/@app block targeting, and {% stylesheet %}/{% javascript %} tags. This is the current best-practice way to build a Shopify theme. Every code example in this handbook uses it instead of the older Dawn-era model, which only worked with sections and didn’t support this kind of nesting.

How this handbook is organized

#	Section	What it answers
1	Getting Started	You’re here. Everything you need installed on your machine, and everything already set up in the repo, before you write any code: editor, Prettier, AI rules, Git conventions.
2	Theme Store Requirements	What Shopify requires before they’ll list your theme. Bookmark this one, you’ll come back to it constantly.
3	Codebase Structure	How a theme’s files and folders fit together.
4	Scaffold Setup Guide	Step-by-step: build your first section and block by hand.
5	AI-Assisted Development	How we actually build most things from here on: Claude Code, Figma to code, custom commands, subagents, hooks.
6	GitHub Workflow	Branch off, open a PR, review, and CI, the loop you’ll use for everything from here on.
7	CSS	Units, cascade, custom properties, and CSS inside a Shopify theme.
8	JavaScript	State, events, web components, and the `{% javascript %}` tag.
9	Style Guides	Liquid conventions, clean code principles, third-party libraries.
10	Design System & Configuration	Figma tokens and the three-tier token model.
11	Config & Global Settings	`settings_schema.json`, `settings_data.json`, and the conventions around both.
12	Presets	Default values for themes, sections, and blocks.
13	Colors	Palettes, color schemes, design tokens, contrast.
14	Fonts	Font settings, type scale, typography tokens.
15	Spacing	Spacing scale and tokens, in settings and in CSS.
16	Assets Management	Icons, responsive images, video, 3D/AR, and asset performance.
17	Internationalization & Locales	RTL, locale files, and translation.
18	Performance	Performance strategy, the critical rendering path, budgets and audits.
19	Accessibility	Building accessibility into a section from the start, and keeping it consistent theme-wide.
20	Quality & Validation	Linting, testing, and the checklist before you open a PR.
21	Publishing to Theme Store	Packaging, submitting, and what happens after.
22	Tooling & Config	Project files, packaging exclusions, optional build setups.
23	Learning Articles	Deeper dives on CSS, JS, Liquid, locales, maintainable code.
24	Reference	Cheatsheet, glossary, tools directory.

Read section 1 in full before you touch any code, it’s the setup you need in place first. Then read sections 2 to 4 in order, once, at the start of the project. After that, use this handbook as a reference instead of reading it front to back. Jump to whatever section answers your current question, or use the search bar (top left) to find a topic fast.

A realistic first week

If you’re joining the Solis project without any background on it, here’s roughly how your first week should go. This isn’t a strict schedule. It’s here so you know what “on track” looks like.

Day	What you should be doing
1	Read section 1 in full: get your Partner account, dev store, and Shopify CLI in place, install your editor and its extensions, and read through what’s already configured for you (Prettier, AI rules, Git conventions) (see Prerequisites & Setup onward).
2	Read section 2. Clone the Solis repo, get `shopify theme dev` running, and spend real time in the existing codebase, sections, blocks, config, before you write anything of your own.
3	Read section 3, then section 4. Build one small, low-risk section end to end (see Your First Section & Block) to try out the whole loop: code, then preview, then PR.
4	Pair on a real ticket with a more senior teammate if one’s available. Skim AI-Assisted Development for how we use AI tools day to day.
5	Open your first real PR against a real ticket. Expect review comments. That’s the process working, not a sign that you did something wrong.

Do / Don’t

✅ Do	❌ Don’t
Work through section 1 in full before you write any code, even if you’re eager to jump in. Confirming your editor, tools, and understanding of our AI rules and Git conventions actually work costs you far less time now than discovering a gap mid-PR.	Skipping straight to coding. The way we build things here (theme blocks, section groups) is different enough from a typical web project that skipping the reading leads to code you’ll have to rework later.
Read `AGENTS.md` on day one, as part of section 1 (see Setting Up AI Rules). It’s already in the repo and already governs how your AI tool behaves the moment you clone. Don’t wait until you’ve already written a dozen files the “wrong” way that now need fixing.	Learning Shopify themes from random blog posts instead of this handbook or shopify.dev. Many public tutorials, even ones that look recent, still teach Dawn’s older, section-only patterns. Follow them, and you’ll pick up patterns we don’t use.
Ask in the team channel before you guess on anything Shopify-specific. A five-minute question beats a half-day detour built on a wrong assumption.	Assuming “it works on my dev store” means “it’s done.” A change that works with your test data can still fail Theme Store review the moment it hits an empty collection or a 200-character title. Check Theme Store Requirements before you call anything finished.
Keep this handbook open in a tab while you work. It’s meant to be checked often, not read once and forgotten.	Not asking when you’re uncertain. If a requirement or pattern in this handbook seems to conflict with what you’re being asked to build, flag it. Don’t quietly guess and hope it’s fine.