# Liquid & Shopify Best Practices

Read this index first. Load only the files relevant to your current task.

## 1. Liquid Performance — CRITICAL

| File                            | Pattern                                             |
| ------------------------------- | --------------------------------------------------- |
| `liquid-filter-early.md`        | Filter and assign before loops                      |
| `liquid-cache-assigns.md`       | Assign once, reuse — avoid repeated filters         |
| `liquid-limit-loops.md`         | Always use limit: on for loops                      |
| `liquid-avoid-nested-loops.md`  | Flatten nested loops with Liquid filters            |
| `liquid-break-continue.md`      | break/continue for early loop exit                  |
| `liquid-map-join.md`            | map + join instead of string concatenation          |
| `liquid-whitespace-control.md`  | Strip whitespace with {%- -%} tags (and exceptions) |
| `liquid-multi-statement.md`     | Use {% liquid %} block for multi-statement logic    |
| `liquid-blank-checks.md`        | Always use != blank for presence checks             |
| `liquid-default-filter.md`      | Use \| default: for optional fallbacks              |
| `liquid-render-over-include.md` | render is faster and safer than include             |
| `liquid-snippet-data.md`        | Pass only needed values to snippets                 |
| `liquid-render-params.md`       | Assign filtered values before passing to render     |
| `liquid-elsif-chain.md`         | elsif chain over multiple if blocks                 |
| `liquid-assign-over-capture.md` | assign over capture for simple values               |

## 2. Asset Loading — HIGH

| File                           | Pattern                                   |
| ------------------------------ | ----------------------------------------- |
| `loading-defer-scripts.md`     | defer/async on non-critical scripts       |
| `loading-lazy-images.md`       | Native lazy loading for below-fold images |
| `loading-preload-critical.md`  | Preload hero images and fonts             |
| `loading-responsive-images.md` | srcset for per-viewport image sizes       |

## 3. DOM Optimization — HIGH

| File                          | Pattern                                                    |
| ----------------------------- | ---------------------------------------------------------- |
| `dom-minimize-elements.md`    | Eliminate wrapper divs, flatten nesting, use semantic HTML |
| `liquid-background-layers.md` | Separate background/content layers with z-index scale      |

## 4. Shopify Section Conventions — HIGH

| File                            | Pattern                                                           |
| ------------------------------- | ----------------------------------------------------------------- |
| `liquid-no-section-root.md`     | Never use `<section>` as root — Shopify wraps automatically       |
| `liquid-block-rendering.md`     | Output `{{ block.shopify_attributes }}` on every block wrapper    |
| `liquid-static-blocks.md`       | `content_for 'block'` vs `'blocks'` — static vs dynamic rendering |
| `liquid-doc-tags.md`            | `{% doc %}` header with `@param` and `@example` for snippets      |
| `liquid-schema-content.md`      | All visible content from schema settings, never hardcoded         |
| `liquid-translation-strings.md` | Use `{{ 'key' \| t }}` for all user-facing text                   |
| `liquid-schema-locales.md`      | `en.default.schema.json` for editor labels — separate namespace   |

## 5. CSS & Styling — MEDIUM

| File                     | Pattern                                  |
| ------------------------ | ---------------------------------------- |
| `css-prefer-tailwind.md` | Tailwind utilities over CSS variables    |
| `css-critical-inline.md` | Inline critical CSS, async load the rest |

## 6. Alpine.js — MEDIUM

| File                        | Pattern                                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `alpine-core-directives.md` | Full directives reference (x-data, x-show, x-if, x-for, x-bind, x-on, x-model, etc.)                         |
| `alpine-magics-globals.md`  | Magics ($el, $refs, $store, $dispatch, $watch, $nextTick) + globals (Alpine.data, Alpine.store, Alpine.bind) |
| `alpine-transitions.md`     | Transition helpers, CSS class syntax, collapse plugin                                                        |
| `alpine-plugins.md`         | All plugins: intersect, focus, persist, mask, sort, anchor, morph, resize                                    |
| `alpine-debounce.md`        | Debounce expensive watchers/handlers                                                                         |
| `alpine-static-data.md`     | Move static data outside reactive scope                                                                      |
| `alpine-defer-heavy.md`     | Defer heavy content with $nextTick                                                                           |
| `alpine-separate-scopes.md` | Split x-data into separate concerns                                                                          |
| `alpine-cleanup.md`         | Clean up listeners in destroy()                                                                              |

## 7. Schema Design — MEDIUM

| File                             | Pattern                                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------- |
| `schema-section-settings.md`     | Lean settings, map to Tailwind in template; image_picker has built-in alt; `visible_if` |
| `schema-blocks-over-settings.md` | Blocks for repeatable content, not numbered settings                                    |
| `schema-block-allowlist.md`      | `@theme` / `@app` / specific types — control which blocks a section accepts             |
| `schema-header-grouping.md`      | Group settings under `{"type":"header"}` entries                                        |
| `schema-presets-with-blocks.md`  | Seed presets with default blocks so sections render on first drop                       |

## 8. Accessibility

See `a11y/README.md` for comprehensive WCAG 2.2 & RGAA patterns (cross-platform).