.liquid`, and all five are the same shape — one `aria-hidden` div, `class="ornament-field

__ornament"`, a `--ornament-field-weight` custom property, and `data-ornament-desktop` pointing at `assets/ornament-

.svg`, the whole thing wrapped in `{% if settings.enable_ornaments %}`. `assets/lazy-ornament.js` fetches that SVG and inlines it above 950px; below 950px the field is a pure-CSS grain and nothing is fetched. It is inlined rather than referenced from `mask-image` because an SVG used as an image renders in its own viewport and drops `vector-effect: non-scaling-stroke` — the hairlines would thicken with the section. A new section that wants one adds `assets/ornament-.svg` plus a matching `snippets/ornament-field-.liquid` copied from any of the five, and renders it. Never hand-roll a decorative layer, and never render one unconditionally: `settings.enable_ornaments` is the merchant's single off switch for all of it. Decoration that is content rather than texture goes through blocks instead — `illustration` and `stamp` are addable marks. `decorated-statement` shows the placement idiom: a private `_decor-field` container whose `_decor-image` children take their anchor slots from list order via `:nth-child`, so no child owns a position setting. ## Typography Ten typography presets are the public type API: `display`, `display-sm`, `h1`, `h2`, `h3`, `lg`, `md`, `base`, `sm`, `xs` — each merchant-tunable in theme settings (size, weight, line height, letter spacing, transform, mobile size). Text-bearing blocks expose them through their `preset` setting plus `font` (`heading` / `body`); `preset: custom` unlocks per-block overrides via `typography-style`. In CSS, consume the emitted `--font-size-*` tokens. Never invent an eleventh preset, hardcode a px font size, or re-style a preset class inside a section's CSS. ## Custom sections and blocks (update-safe customization) Shopify theme updates carry over theme-editor customizations (settings, templates, section JSON) automatically, and **non-conflicting code edits are included in the updated theme**. A brand-new file cannot conflict with anything an update changes — so custom work belongs in NEW files, never in edits to shipped ones: 1. **Prefer zero code**: compose the design as blocks inside a `Section` (section.liquid) instance in the editor or a JSON template. Survives updates, merchant-editable. 2. **Need real code?** Create `sections/custom-.liquid` (copy the closest shipped section as a starting point — `sections/section.liquid` for a generic canvas) and `assets/custom-.css`. Same for blocks: `blocks/custom-.liquid`. 3. A custom section/block MUST include at least one `preset` in its schema or it never appears in the editor's picker. A custom block with a preset automatically becomes addable inside every container that accepts `@theme` blocks. 4. **Visitor-facing text in custom code — the ladder:** 1. Expose it as a `text`/`richtext` setting with a default. The merchant's entered value becomes store data (template JSON) — update-safe, merchant-editable, and translatable with Shopify's Translate & Adapt (which translates entered VALUES; setting labels are editor-only schema and are not its concern). 2. For fixed microcopy (aria labels, generic UI verbs): reuse an existing theme key — grep `locales/en.default.json` for the string and use `{{ 'that.key' | t }}`. 3. Otherwise hardcode it in the store's primary language (see STORE.md). 4. Adding NEW keys to `locales/*.json` is the last resort: theme updates rewrite locale files, and merchant-added keys can be dropped in a conflict. If you must, log every added key in STORE.md's customizations log so it can be restored. 5. If you must edit a shipped file, keep the diff minimal and record it (file + reason + summary) in STORE.md's customizations log. ## Schema (the `{% schema %}` JSON in sections and blocks) - Edit the JSON directly, then validate with `shopify theme check` and a test push. - `visible_if` on a block setting can reference `block.settings.*` and `section.settings.*`, never a parent block's settings. `visible_if` is rejected on list-type settings. - `enabled_on` is valid on sections only — Shopify rejects it on theme block schemas. - `range`: every stored value must sit exactly on a step, and `(max - min) / step + 1` must be <= 101, or the push silently keeps the old file deployed. - **Never rename a shipped setting `id`** — saved merchant values are keyed by it. Change the `label` instead. - `info:` text is for facts a merchant cannot guess (a format, a constraint, an admin pointer). If it restates the label or narrates the preview, delete it. ## Liquid - `{% render %}`, never `{% include %}`. - The theme's own strings go through `{{ 'key' | t }}`; a key must exist in ALL six locale files (`locales/*.json` storefront, `locales/*.schema.json` editor labels) or it renders as the raw key. For NEW visitor-facing text in custom code, do NOT default to adding keys — follow the ladder in "Custom sections and blocks" (settings first; new keys last resort). - Plain `text` / `*_label` / `heading` settings rendered with `{{ }}` need `| escape`. Raw output is only for `richtext` / `inline_richtext`. Never `| escape` an `image_tag` result or a value passed as a filter argument. - **Never pipe a filter inside `image_tag` arguments** — it silently swallows every following argument (`class`, `width`, `loading` vanish; no error anywhere). Assign first (`{% assign alt = image.alt | default: '' %}`), then pass the bare variable. The same trap applies to filters piped inside `{% render %}` arguments. - List-type settings (`product_list`, `collection_list`) are drops: `drop[i]` is silently nil. Iterate with `{% for %}`, or apply `| compact` before indexing. - Iterating `section.blocks` exposes only `block.id` and `section.blocks.size` for theme blocks — `block.type` and `block.settings.x` come back blank. - `{% javascript %}` and `{% stylesheet %}` must sit at a section's top level, never inside `{% if %}` or `{% for %}`. - `inline_asset_content` silently drops files over 15 KB. ## Templates and JSON files - `rich_text` values in JSON templates allow only `

`, `

`-`

` as top-level nodes (inline tags belong inside `
`). `inline_richtext` allows no `
`. - A template or section-group JSON top-level `name` must be 50 characters or fewer — longer bounces the push for that file while everything else deploys. - Every section inside a `-group.json` needs a `block_order`, or its blocks silently vanish. ## CSS - Consume the tokens, never redeclare them. Colors and type come from custom properties (`--color-`, `--font-size-*`) generated from theme settings. Hardcoding a hex or a px font size in a section stylesheet breaks merchant control. - Font weights are 400 / 500 / 700 only — never 600. - Color schemes carry 11 roles (background, text, accent, accent_secondary, separator, overlay_text, overlay_background, and the four button roles). Apply schemes via `{% render 'color-scheme-class' %}`; keep the scheme class on a visible painted surface. - BEM naming, low specificity. Never style a theme block's selectors from a section's CSS file — context styling belongs on the block itself via a modifier class, a setting, or an exposed custom property. - Custom-property defaults go on the consuming class (`.card { --card-gap: 1rem; }`), not into the `var()` fallback — an inherited value silently beats the fallback. - Per-section styles live in `assets/
.css`, loaded with `{% render 'load-css' %}` (deferred) or `stylesheet_tag`. Never hand-roll a `media="print"` deferred link — it breaks theme-editor re-renders. `critical.css`, `deferred.css`, and `product.css` are global bundles; put new styles in per-section files instead of appending there. - Use `overflow: clip`, not `overflow: hidden`, on ancestors of scroll-driven animations — `hidden` freezes them. - Buttons: the label must be wrapped in ``, or the text paints under the radial hover fill. - Design language: no upward `translateY` on `:hover` (scale / zoom / arrow-nudge are fine); equal-height cards in a row need `height: 100%` on the card, not just parent stretch. - Images and media always reserve space (`width`/`height` attributes or `aspect-ratio`), lazy-load below the fold, and use `alt=""` when decorative. - Solutions must hold for any merchant content — long titles, many blocks, RTL locales, short viewports. Never "fix" layout by constraining content length. ## JavaScript - Modern syntax only: `const`/`let`, arrow class fields, `async/await`, `for...of`, early returns. No `var`, no `console.log`, no `static` class members (iOS Safari < 14.1). - Prefer native HTML primitives (`
`, ``, `[popover]`) and CSS over custom JS. Per-section behavior ships as a `