## Project overview A Shopify theme built for submission to the Shopify Theme Store. Scaffolded from Shopify's **Skeleton Theme** — not Dawn, not Horizon, since neither is Theme-Store-eligible (see the handbook's Scaffold Setup Guide). We follow **Horizon's architecture** as a conceptual reference: nested theme blocks, `@theme`/`@app` block targeting, `{% stylesheet %}`/`{% javascript %}` tags. The actual codebase starts from Skeleton Theme, not a Horizon fork. ## Source of truth & certainty requirements These rules govern *how* every other rule in this file gets applied — read this section as load-bearing, not optional context. - **Official Shopify documentation is the only acceptable source for a factual claim about Shopify's platform, APIs, Liquid, or Theme Store policy.** Acceptable sources: `shopify.dev` (architecture, Liquid reference, Theme Store requirements), `help.shopify.com`, and Shopify's own official repos (e.g. `github.com/Shopify/*`). A third-party blog post, forum answer, or tutorial is not an acceptable source for a factual claim, even if it's convenient or seems plausible — it may be outdated, subtly wrong, or describe a deprecated pattern. - **Do not guess about anything checkable.** If a Liquid object's properties, a filter's exact behavior, a schema field's valid values, or a Theme Store policy detail isn't something you're certain of, say so explicitly and check the official source before proceeding — do not present a guess as a fact. Use the [Shopify AI Toolkit](/ai-assisted-development/shopify-ai-toolkit/)'s doc search when available; otherwise state the uncertainty and ask. - **Plan before acting, for anything non-trivial.** State what you're about to build/change and why, before writing code — not as a formality, but so a wrong assumption gets caught as a one-line correction instead of a rewrite. This is the same discipline the [Figma-to-code workflow](#figma-to-code-workflow) below applies specifically to design-to-code tasks; it applies more generally to any non-trivial change. - If a plan or a claim turns out to be wrong once you check the real documentation or the real codebase, say so and correct course — don't quietly proceed on a premise you've already found reason to doubt. ## Commands ```bash shopify theme dev --store .myshopify.com # local preview, hot reload (Chrome only) shopify theme check # lint Liquid against Theme Check rules shopify theme push --unpublished # push to a new unpublished theme shopify theme package # build the submission-ready zip node scripts/generate-ai-rules.mjs # (re)creates CLAUDE.md + .github/copilot-instructions.md as symlinks to AGENTS.md — does not touch this file ``` ## Hard constraints - No UI framework (React/Vue/Svelte) renders storefront markup. Liquid is the templating layer, full stop. - No Sass/SCSS, no pre-minified committed CSS/JS. Native CSS with custom properties only. - Every schema string goes through `locales/*.schema.json` (`t:` prefix) — never hardcoded English. - A section defines blocks locally OR accepts theme blocks (`@theme`) — never both. - The main product section and featured product section must accept `@app` blocks. - `metaobject`/`metaobject_list` settings: standard Shopify definitions only, never custom or app-owned. - Before generating code, check whether an equivalent section/block/snippet already exists — reuse over duplication. - If a request conflicts with a Shopify Theme Store requirement, flag the conflict instead of silently complying. - If a request is ambiguous, ask a clarifying question rather than guessing an implementation. ## Figma-to-code workflow When given a Figma frame/screenshot and asked to build a section, block, or snippet: **plan first** (decompose content vs. chrome, decide which artifact type it actually needs, list settings/blocks), **then build**, **then run `shopify theme check`**, **then fix any offenses**, **then report a short summary** of what was built and any decisions made. Full process: [Figma to Code Workflow](/ai-assisted-development/figma-to-code-workflow/). For the repeatable version of this exact loop, use the `/figma-to-liquid` custom command — see [Claude Code Custom Commands](/ai-assisted-development/claude-code-custom-commands/). ## Before finishing any task 1. Run `shopify theme check` and resolve any new offenses. 2. Confirm the change doesn't regress a Theme Store requirement — accessibility and Lighthouse scores especially. 3. If the task touched a section/block schema, confirm every setting has a `label` and goes through `t:` locale keys. ## When uncertain Flag a conflict with a Theme Store requirement instead of silently working around it. Ask a clarifying question instead of guessing when a request is ambiguous — this codebase would rather wait five minutes for an answer than ship a guess that fails Theme Store review. See "Source of truth & certainty requirements" above — the same no-guessing standard applies to factual claims about the platform itself, not just ambiguous requests. ## Liquid & schema conventions - A section either defines blocks locally in its own schema, OR accepts theme blocks via `"blocks": [{ "type": "@theme" }]` — never both. - Every theme block needs at least one entry in `"presets"`, or it will never appear in the editor's block picker. - Restrict a section's accepted blocks to specific types when the section has one clear purpose; use `"@theme"` only for genuinely general-purpose containers (e.g. a Group block). - Always include `{ "type": "@app" }` alongside `{ "type": "@theme" }` in the main product section and featured product section — required for Theme Store review. - Use `{% render %}` for snippets (they receive explicit variables); use a theme block when the content needs merchant-editable settings and reordering. Never use `{% include %}` (deprecated). - Write a `{%- doc -%}` block on every snippet describing its parameters, in [LiquidDoc](https://shopify.dev/docs/storefronts/themes/tools/liquid-doc) format. - Use the `routes` object for all internal links (`{{ routes.root_url }}`), never hardcoded paths like `/` or `/products/`. - Use `image_url` + explicit `width`/`height` + `loading="lazy"` (except above-the-fold) for every image — never a bare ``. - Reference `metaobject`/`metaobject_list` settings only with standard Shopify definitions — never a custom or app-owned `metaobject_type`. - `settings_data.json` defaults must reference resources that exist on every fresh store install — never a resource that only exists in the demo store. - Full detail: [Liquid Style Guide](/style-guides/liquid/) in the handbook. ## CSS & JavaScript conventions - Scope CSS/JS to the component that needs it using `{% stylesheet %}` and `{% javascript %}` tags inside the section/block file — don't add everything to one global bundle. - A setting that maps to one CSS property → expose it as a CSS custom property (`style="--gap: {{ block.settings.gap }}px"`). A setting that changes several properties together → expose it as a class (`select` setting mapping to `.variant--name`), not several separate variables. - Use CSS logical properties (`margin-inline-start`, `padding-inline-end`) instead of physical ones (`margin-left`, `padding-right`) so layout works correctly in RTL languages. - Ship JS as native ES modules, built as Web Components for anything stateful/interactive. No bundler magic at runtime — the browser resolves the module graph. - Don't add a dependency for something under ~50 lines of vanilla JS or native CSS can do (a carousel via `scroll-snap`, a modal via `

`). - Never introduce React/Vue/Svelte component syntax for storefront-facing markup. - Every interactive element must be keyboard operable with a visible focus state — this is a Theme Store requirement, not optional polish. - Full detail: [CSS Style Guide](/style-guides/css/) and [JavaScript & Web Components](/style-guides/javascript-and-web-components/) in the handbook.