---
description: Liquid, section, and block schema conventions (optional, legacy — mirrors AGENTS.md's "## Custom rules")
globs: ["**/*.liquid"]
alwaysApply: false
---

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

## 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 `<img src>`.
- 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.