---
description: Project context and non-negotiable constraints (optional, legacy — mirrors AGENTS.md's "## Custom rules")
alwaysApply: true
---

<!--
  OPTIONAL, LEGACY FILE — hand-maintained, not a symlink and not auto-generated.
  Source of truth: AGENTS.md's "## Custom rules" section.
  Current Cursor versions read AGENTS.md natively — you likely don't need this file at all.
  Only use this if you specifically want per-file-type scoped auto-attach (see
  Setting Up AI Rules: /getting-started/setting-up-ai-rules/). If you do,
  keep it in sync with AGENTS.md's "## Custom rules" by hand whenever that section changes.
-->

## 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 <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.