npm - similarbuild - Versions diffs - 0.1.0 - Mend

similarbuild 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/templates/skills/sb-build-shopify/references/shopify-build-rules.md ADDED Viewed

@@ -0,0 +1,563 @@
+# Shopify Section Build Rules
+Everything `sb-build-shopify` needs to compose a production-grade `.liquid` file ready to drop into a Shopify theme's `sections/` folder. The output must (a) render correctly inside Dawn / Online Store 2.0 themes without theme-CSS bleed clobbering it, and (b) expose the merchant-facing values (text, image, color, link, toggle) as `{% schema %}` settings so the merchant can edit them from the theme editor without touching code.
+These rules are non-negotiable — they encode the Shopify theme stack's particular failure modes and the editor-customization promise that makes Shopify sections worth shipping in the first place.
+If the host project provides these files, prefer them — they reflect the user's most recent curated knowledge:
+- `<plugin>/memory/patterns.md` (overrides patterns A-H below — adapt to Liquid)
+- `<plugin>/memory/anti-patterns.md` (overrides anti-patterns #1-9 below)
+- `<plugin>/memory/design-knowledge.md` (subset is usually passed by the orchestrator instead)
+- `<plugin>/presets/shopify-section.yaml` (overrides the Dawn theme reset and known overrides below)
+When they're absent (early in the framework's life), use everything below as the source of truth.
+## Composition contract
+The output is a **single `.liquid` file** containing exactly:
+1. Optional `{% style %}{% endstyle %}` block (Shopify-native CSS injection — preferred over `<style>` because it allows Liquid expressions inside CSS).
+2. The scoped markup, with `{{ section.settings.* }}` Liquid placeholders for every editable value.
+3. Optional `<script>` block for vanilla-JS interactivity (no frameworks).
+4. A `{% schema %}...{% endschema %}` JSON block at the end. **This is mandatory** — without it Shopify will refuse to register the section.
+No `<html>`, no `<head>`, no `<body>` wrappers. No `<link rel="preconnect">` or `<link rel="stylesheet">` for Google Fonts — Shopify owns `<head>` and the theme already loads fonts via `font_face` filter or the theme's font settings. If a custom font is genuinely needed, expose it as a `font_picker` setting and consume it via `{{ section.settings.font | font_face }}` inside `{% style %}`.
+The scope class IS the boundary. Shopify will additionally wrap the rendered section in `<div id="shopify-section-{{ section.id }}" class="shopify-section">`, which gives a second layer of natural scoping.
+## Scope class naming
+- Pick a kebab-case name from the section type detected in `inspection.sectionType` and a short content hint (e.g. `sb-hero-mobile`, `sb-pdp-variant`, `sb-faq`). Prefix with `sb-` so the class is recognizably ours and unlikely to collide with the theme's own classes.
+- The scope class appears on the outermost element and prefixes EVERY selector inside `{% style %}`.
+- BEM-ish modifiers: `.{scope}__title`, `.{scope}__cta`, `.{scope}--variant-active`. Pick what reads cleanly.
+## Defensive specificity (anti-pattern #5b — non-negotiable)
+EVERY selector that styles user-visible content (typography, color, layout, spacing, borders) MUST chain the scope class as ancestor — not just as the element's own class.
+```css
+/* WRONG — single class, theme overrides will win */
+.sb-hero__title { font-size: 32px; }
+/* RIGHT — chained scope, beats theme specificity */
+.sb-hero .sb-hero__title { font-size: 32px; }
+```
+Optionally chain Shopify's own wrapper for an extra specificity boost when the theme is especially aggressive:
+```css
+.shopify-section .sb-hero .sb-hero__title { font-size: 32px; }
+```
+This costs nothing and wins against Dawn's and most third-party themes' typography overrides.
+## `!important` policy
+Dawn (and most OS 2.0 themes) injects `!important` on these properties via the theme's typography and section padding rules. Match them only on the four font properties when applied to critical text:
+- `font-family` — overridden by `--font-heading-family` / `--font-body-family` rules
+- `font-size` — set by typography scale CSS variables
+- `font-weight` — set by `--font-heading-weight` / `--font-body-weight`
+- `color` — set on links and headings via theme color schemes
+Do NOT spray `!important` everywhere. Specifically: do NOT `!important` margins, paddings, widths, heights, backgrounds, transforms, transitions. Theme `section-spacing` rules use CSS variables, not `!important`, so chained-scope specificity alone wins.
+## Reset universal
+First rule inside `{% style %}`, always:
+```liquid
+{% style %}
+.{scope}, .{scope} * {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+{% endstyle %}
+```
+This neutralizes the most common theme bleed without touching properties Dawn needs.
+## Full-bleed container (escape Dawn's `page-width` cap)
+When the section spans viewport edge-to-edge, Dawn's `.page-width` wrapper caps it at the theme's `--page-width` (default 1200px). Escape with:
+```css
+.{scope} {
+  width: 100vw;
+  margin-left: calc(50% - 50vw);
+}
+```
+This works regardless of how the parent template wrapped the section. Do NOT use negative margins of fixed pixel values — they break on mobile breakpoints.
+## Mobile-first + desktop breakpoint
+Base styles target mobile (390px viewport). Desktop overrides go in:
+```css
+@media (min-width: 1000px) {
+  /* desktop-only overrides */
+}
+```
+1000px is the threshold the framework standardizes on (sibling skill `sb-build-wp` uses the same). Tablets in portrait get the mobile layout (safe), landscape tablets and small laptops get desktop.
+## Schema settings — the editable promise
+This is the central differentiator from `sb-build-wp`. Identify every value in the inspection that a merchant might reasonably want to edit, and lift it into `{% schema %}` as a setting. The Liquid template references the setting; the JSON schema declares its type, label, and default.
+### What to lift into settings (and the right type)
+| Source in inspection                                              | Liquid setting type | Default                                                  |
+| ----------------------------------------------------------------- | ------------------- | -------------------------------------------------------- |
+| Headings, sub-headings, single-line copy                          | `text`              | the literal string from `inspection.dom`                 |
+| Multi-paragraph body copy or copy with inline links               | `richtext`          | wrapped in `<p>...</p>`                                  |
+| CTA labels                                                        | `text`              | the literal label                                        |
+| CTA / link destinations                                           | `url`               | the original href if same-origin, else `/`               |
+| Hero / content images                                             | `image_picker`      | no default (the merchant uploads — use a base64 SVG placeholder in the Liquid `{% else %}` branch, see below) |
+| Visible color values that match an inspection token               | `color`             | the literal hex                                          |
+| Visual on/off toggles (show/hide a sub-element)                   | `checkbox`          | `true` (matches the inspected state)                     |
+| Numeric values worth tuning (padding scale, items shown)          | `range`             | inspected value, with sensible `min`/`max`/`step`        |
+| Choice between a small finite set (left / center / right)         | `select`            | inspected value as `default`                             |
+Pick `richtext` over `text` whenever the source contains a link, bold, or italic — `richtext` lets the merchant preserve those without HTML knowledge. Pick `text` for short single-line strings.
+`image_picker` settings have **no `default`**. The fallback for the `{% else %}` branch is a **base64-inlined SVG placeholder** (a small neutral-grey rectangle). Do NOT emit the dev's local `assetsMap.assets[url].localPath` here — that path:
+(a) does not resolve in `sb-validate-render` (no document base for `file://`), so the hero renders as a black rectangle and inflates `compare-visual` diff%;
+(b) is the developer's filesystem path, completely broken in a real merchant install.
+Use this exact data URI (208 bytes — generic 1170×900 grey, neutral fill `#d4d4d4`, mid-slice preserve-aspect):
+```
+data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTcwIDkwMCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgc2xpY2UiPjxyZWN0IHdpZHRoPSIxMTcwIiBoZWlnaHQ9IjkwMCIgZmlsbD0iI2Q0ZDRkNCIvPjwvc3ZnPg==
+```
+```liquid
+{% if section.settings.hero_image %}
+  <img src="{{ section.settings.hero_image | image_url: width: 1200 }}" alt="{{ section.settings.hero_image.alt | default: section.settings.heading | escape }}" width="{{ section.settings.hero_image.width }}" height="{{ section.settings.hero_image.height }}" loading="eager" fetchpriority="high">
+{% else %}
+  <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTcwIDkwMCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgc2xpY2UiPjxyZWN0IHdpZHRoPSIxMTcwIiBoZWlnaHQ9IjkwMCIgZmlsbD0iI2Q0ZDRkNCIvPjwvc3ZnPg==" alt="" width="1170" height="900" loading="eager">
+{% endif %}
+```
+The `{% else %}` `<img>` uses `alt=""` (decorative — it's a placeholder, not real content) and matches the wrapper's `aspect-ratio` so the layout shifts gracefully when the merchant uploads the real image. Same data URI applies whether the branch renders an `<img>` or sets `background-image: url(...)` in `{% style %}` (see Hero rules).
+### Naming conventions for setting `id`
+- snake_case, semantic, never UI-driven (`heading` not `top_text`, `cta_label` not `button_1_text`).
+- Stable across schema revisions — once shipped, renaming an `id` orphans the merchant's edits.
+### Ordering inside `settings`
+Group related settings with `header` separators so the editor sidebar reads top-down:
+```json
+{
+  "type": "header",
+  "content": "Heading"
+},
+{ "type": "text", "id": "heading", "label": "Heading", "default": "Welcome" },
+{ "type": "richtext", "id": "subheading", "label": "Sub-heading", "default": "<p>...</p>" }
+```
+### Presets — non-negotiable
+Every section ships with at least one preset. Without a preset, merchants cannot insert the section from "Add section" in the theme editor — it stays invisible. Use the inspected values as the preset's defaults.
+```json
+"presets": [
+  { "name": "Hero — clone of source", "category": "Image" }
+]
+```
+`category` is purely organizational in the editor sidebar. Reasonable values: `Image`, `Text`, `Banners`, `Promotional`.
+## Defensive specificity against Dawn / OS 2.0
+The Shopify wrapper `<div id="shopify-section-{{ section.id }}" class="shopify-section">` gives you a free outer scope. Two acceptable forms:
+```css
+/* Form 1 — chained custom scope (recommended, theme-agnostic) */
+.{scope} .{scope}__title { ... }
+/* Form 2 — chained custom scope inside Shopify's wrapper (extra defense) */
+.shopify-section .{scope} .{scope}__title { ... }
+```
+Use Form 1 by default. Use Form 2 only when you explicitly need to override a Dawn rule that wins via `.shopify-section` ancestor.
+Do NOT use the dynamic id selector (`.shopify-section-{{ section.id }}`) for scoping — the id is per-render, and the same section markup may be reused across pages.
+## Asset substitution
+For every `<img>` or `<source>`, the URL must come from `assetsMap.assets[originalUrl].localPath` — NEVER the original CDN URL, never an inline `data:` URI for raster, never a hand-drawn SVG approximation (anti-pattern #8).
+For SVGs: Shopify accepts SVG uploads as theme assets, BUT until the merchant uploads, the inline SVG markup from `assetsMap.assets[url].inline` is the fastest path to a working default. Inline it directly for icons; for hero or content images, prefer the file-based path.
+If a URL appears in `assetsMap.failed[]`, you have two choices:
+1. Drop the image entirely (preferred for decorative).
+2. Use a `<div>` placeholder with a literal background-color from inspection tokens.
+Never fabricate an asset. If a hero image failed, surface that to the orchestrator via a comment in the output: `<!-- sb-build-shopify: hero asset failed download -->`.
+### Responsive images via Shopify's `image_url` filter
+Shopify generates and serves variants automatically through the `image_url` filter — never hardcode a `srcset` for merchant-uploaded images. The pattern:
+```liquid
+<img
+  src="{{ section.settings.hero_image | image_url: width: 1200 }}"
+  srcset="
+    {{ section.settings.hero_image | image_url: width: 400 }} 400w,
+    {{ section.settings.hero_image | image_url: width: 800 }} 800w,
+    {{ section.settings.hero_image | image_url: width: 1200 }} 1200w,
+    {{ section.settings.hero_image | image_url: width: 1600 }} 1600w
+  "
+  sizes="(min-width: 1000px) 50vw, 100vw"
+  alt="{{ section.settings.hero_image.alt | default: section.settings.heading | escape }}"
+  width="{{ section.settings.hero_image.width }}"
+  height="{{ section.settings.hero_image.height }}"
+  loading="lazy">
+```
+For the LCP / hero image, swap `loading="lazy"` for `loading="eager" fetchpriority="high"`.
+For the `{% else %}` fallback branch, use the **base64 SVG placeholder** documented in "Schema settings — `image_picker`". No `srcset` — the placeholder is a single asset, and `width` / `height` should match the placeholder's intrinsic dimensions (1170×900) so the layout doesn't shift when the merchant uploads. Do NOT emit `assetsMap.assets[url].localPath` here — see anti-pattern #16.
+## Hero rules (anti-pattern #1)
+NEVER use `100vh` for hero height. Mobile browser chrome makes `100vh` taller than the visible viewport, causing the hero to clip below the fold. Use:
+```css
+.{scope} .{scope}__hero {
+  aspect-ratio: 1 / 1.3;
+  max-height: 700px;
+}
+@media (min-width: 1000px) {
+  .{scope} .{scope}__hero {
+    aspect-ratio: 16 / 9;
+    max-height: 720px;
+  }
+}
+```
+Prefer `background-image` on the container over an `<img>` with `height: 100%` (anti-pattern #2). Dawn injects `img { max-width: 100%; height: auto; }` which clobbers the `<img>` approach.
+For background images set via Liquid setting, use the same `{% if %}{% else %}` fallback as the `<img>` form — the SVG data URI is the placeholder when the merchant hasn't uploaded yet:
+```liquid
+{% style %}
+.{scope} .{scope}__hero {
+  {% if section.settings.hero_image %}
+    background-image: url({{ section.settings.hero_image | image_url: width: 1600 }});
+  {% else %}
+    background-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTcwIDkwMCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgc2xpY2UiPjxyZWN0IHdpZHRoPSIxMTcwIiBoZWlnaHQ9IjkwMCIgZmlsbD0iI2Q0ZDRkNCIvPjwvc3ZnPg==');
+  {% endif %}
+  background-size: cover;
+  background-position: center;
+}
+{% endstyle %}
+```
+The fact that `{% style %}` allows Liquid expressions inside CSS is exactly why we use it instead of `<style>`. Never emit a developer filesystem path (`/Users/...`, `C:\Users\...`) into `url(...)` — see anti-pattern #16.
+## Fonts
+Do NOT emit `<link rel="preconnect">` or `<link rel="stylesheet">` for Google Fonts. Shopify owns `<head>` and the theme already loads fonts. Two acceptable patterns:
+1. **Use the theme's font** (default — match Dawn's `--font-heading-family` / `--font-body-family` via `font-family: inherit` on headings, then chain-scope-override the weight/size/family only on text we control). Cleanest, least chance of breaking the merchant's brand.
+2. **Expose a `font_picker` setting** when the inspection's font is genuinely critical and unlikely to be in the theme:
+```json
+{ "type": "font_picker", "id": "heading_font", "label": "Heading font", "default": "assistant_n4" }
+```
+```liquid
+{% style %}
+{{ section.settings.heading_font | font_face: font_display: 'swap' }}
+.{scope} .{scope}__title {
+  font-family: {{ section.settings.heading_font.family }}, {{ section.settings.heading_font.fallback_families }};
+}
+{% endstyle %}
+```
+`font_face` filter automatically emits `font-display: swap`. Never use Google Fonts links inside a Shopify section.
+## Design knowledge — applied automatically
+These come from the `designKnowledge` subset the orchestrator passed in. When that subset is absent or thin, use these defaults — they are baseline web standards, not opinions.
+### Accessibility
+- Every `<img>` MUST have an `alt` attribute. For settings-driven images: `alt="{{ section.settings.hero_image.alt | default: section.settings.heading | escape }}"`. For decorative images: `alt=""` literal (no Liquid).
+- Every `<button>` MUST have `type="button"` (so it doesn't submit a parent form).
+- Buttons that are icon-only MUST have `aria-label="..."` describing the action. If the label might be reworded by the merchant, expose an `aria_label` text setting alongside.
+- Heading hierarchy: a section that starts with H2 cannot contain an H1. Don't skip levels. The orchestrator may tell you this is a sub-section that should start at H2 — respect that.
+- Use `<nav>` for navigation regions. Do NOT emit `<main>` from a section.
+- Use `<dialog>` for modals — close with `dialog.close()`, open with `dialog.showModal()`. No library.
+### Performance
+- The hero image gets `loading="eager"` AND `fetchpriority="high"`. Every other image gets `loading="lazy"`.
+- Use `width` and `height` attributes on every `<img>` (from `inspection.imgUrls[].naturalWidth/Height` for fallback path, or `{{ image.width }}`/`{{ image.height }}` for setting-driven). Prevents layout shift.
+- Do NOT preload anything. Shopify's theme handles preloading at the page level.
+### Web standards
+- Responsive images: always via `image_url: width: N` for setting-driven, hardcoded single-size for local fallback.
+- Use `<details>/<summary>` for FAQ collapsibles. Reset summary's marker.
+## fixHints (when present)
+`fixHints` arrives as a JSON array from `sb-review-checks` after a failed validation cycle. Each hint has the shape:
+```json
+{ "area": "string", "issue": "string", "fix": "string", "severity": "high|medium|low" }
+```
+When fixHints are present, you are NOT building from scratch — you are patching a previous build. Apply each fix surgically:
+- Re-read your previous output (the orchestrator passes its path).
+- For each fixHint, identify the exact selector, markup, or schema entry it references and apply the fix.
+- Keep everything else identical — don't refactor, don't rename setting `id`s, don't restructure the schema. The reviewer's diff should be the only diff.
+- High-severity fixes are mandatory. Medium are strongly recommended. Low are optional unless they conflict with high-severity ones.
+## Patterns (A-H — adapted for Shopify)
+These are the canonical recipes adapted to Liquid + schema. When `<plugin>/memory/patterns.md` exists, prefer it.
+### A. Sticky Header with announcement bar
+```liquid
+<header class="sb-hdr">
+  {% if section.settings.show_announcement %}
+    <div class="sb-hdr__bar">{{ section.settings.announcement_text }}</div>
+  {% endif %}
+  <nav class="sb-hdr__nav" aria-label="Main">
+    <a href="{{ section.settings.logo_link | default: '/' }}" class="sb-hdr__logo">
+      {% if section.settings.logo %}
+        <img src="{{ section.settings.logo | image_url: width: 200 }}" alt="{{ shop.name | escape }}" width="100" height="40">
+      {% endif %}
+    </a>
+    <button class="sb-hdr__menu-btn" type="button" aria-label="Open menu" aria-expanded="false">☰</button>
+  </nav>
+</header>
+```
+Settings: `show_announcement` (checkbox), `announcement_text` (text), `logo` (image_picker), `logo_link` (url).
+### B. Full-bleed Hero (aspect-ratio, background-image, settings-driven)
+Use `background-image` on the container via `{% style %}` interpolation. See Hero rules above.
+### C. Carousel mobile / Grid desktop (scroll-snap → grid)
+Identical CSS to `sb-build-wp` Pattern C. The repeating cards become `blocks` in the schema:
+```json
+"blocks": [
+  {
+    "type": "product",
+    "name": "Product card",
+    "settings": [
+      { "type": "image_picker", "id": "image", "label": "Image" },
+      { "type": "text", "id": "title", "label": "Title", "default": "Product" },
+      { "type": "text", "id": "price", "label": "Price", "default": "$24" },
+      { "type": "url", "id": "link", "label": "Link" }
+    ]
+  }
+]
+```
+Iterated in Liquid:
+```liquid
+<div class="sb-products">
+  {% for block in section.blocks %}
+    <article class="sb-products__item" {{ block.shopify_attributes }}>
+      {% if block.settings.image %}
+        <img src="{{ block.settings.image | image_url: width: 600 }}" alt="{{ block.settings.title | escape }}" loading="lazy">
+      {% endif %}
+      <h3>{{ block.settings.title }}</h3>
+      <p>{{ block.settings.price }}</p>
+    </article>
+  {% endfor %}
+</div>
+```
+`{{ block.shopify_attributes }}` is required — without it, the editor cannot link the block UI to the rendered element.
+### D. Image-with-text overlap (`::before` band)
+Same CSS as `sb-build-wp` Pattern D. Image source comes from a `image_picker` setting.
+### E. Defensive button (chain class + appearance + !important on font props)
+```css
+.{scope} .{scope}__cta.{scope}__cta {
+  appearance: none;
+  background: {{ section.settings.cta_bg_color | default: '#000' }};
+  color: {{ section.settings.cta_text_color | default: '#fff' }};
+  font-family: inherit !important;
+  font-weight: 700 !important;
+  font-size: 16px !important;
+  border: 0;
+  padding: 14px 28px;
+  border-radius: 999px;
+  cursor: pointer;
+}
+```
+The `{% style %}` Liquid interpolation makes button colors live-editable from the editor.
+### F. FAQ collapsible (`<details>/<summary>` + blocks)
+```liquid
+<div class="sb-faq">
+  {% for block in section.blocks %}
+    <details class="sb-faq__item" {{ block.shopify_attributes }}>
+      <summary class="sb-faq__q">{{ block.settings.question }}</summary>
+      <div class="sb-faq__a">{{ block.settings.answer }}</div>
+    </details>
+  {% endfor %}
+</div>
+```
+`question` is `text`, `answer` is `richtext`.
+### G. Trust banner with modal
+`<dialog>` and vanilla JS — same pattern as `sb-build-wp` Pattern G. The headline and body inside `<dialog>` come from settings.
+### H. Variant card (radio + photo)
+Real product photos from `assetsMap`, settings-driven, no SVG illustrations.
+## Anti-patterns (1-9 fallback)
+1. **Hero `100vh`** — clips on mobile. Use `aspect-ratio` + `max-height`.
+2. **`<img>` with `height: 100%` for full-bleed hero** — Dawn's `img { height: auto }` clobbers it. Use `background-image` on the container.
+3. **Guessing overlay opacity** — read the exact alpha from `inspection.tokens` or computed style.
+4. **`.scope a { color: inherit }` clobbers button color** — buttons use `<button>`, not `<a>`. If a CTA must be an `<a>`, set its color literally.
+5. **`<button>` decorative without defensive specificity** — chain the class, `!important` on the four font properties (Pattern E).
+6. **`!important` alone without ancestor prefix** — useless. Theme has both. You need both too.
+7. **Modeling overlap-image as a sibling box** — it's a `::before` on the section.
+8. **Replicating an image as inline SVG** — download the actual asset. Inline SVG only when source already was SVG.
+9. **Hardcoding `srcset` for setting-driven images** — use `image_url: width: N` and let Shopify generate the variants.
+### Shopify-specific anti-patterns
+10. **Schema setting `id` rename** — once shipped, renaming `id` orphans merchant edits. Pick stable, semantic ids upfront.
+11. **`image_picker` with `default`** — invalid. `image_picker` does not accept `default`. Use a `{% if %}{% else %}` Liquid fallback.
+12. **Missing `presets`** — section becomes uninstallable from the editor. Always ship at least one.
+13. **Missing `{{ block.shopify_attributes }}` on iterated block elements** — editor cannot link block UI to rendered element. Mandatory.
+14. **Google Fonts `<link>` inside the section** — Shopify owns `<head>`. Use `font_face` filter or theme inheritance.
+15. **Hardcoded CDN URLs in markup** — never. For setting-driven images use the `image_url` filter; for fallbacks use the base64 SVG placeholder (anti-pattern #16).
+16. **Developer filesystem paths in fallbacks** — never emit `/Users/...`, `C:\Users\...`, or any absolute disk path into `<img src>`, `url(...)`, or `src=` for the `{% else %}` branch of an `image_picker` setting. The path (a) doesn't resolve in `sb-validate-render` (no `file://` document base, so the build screenshot is black and inflates `compare-visual` diff%), and (b) is the dev's local filesystem, completely broken in a real merchant install. The correct fallback is the 208-byte base64 SVG placeholder defined in "Schema settings — image_picker fallback" above.
+## Theme reset (preset fallback — shopify-section.yaml)
+When `<plugin>/presets/shopify-section.yaml` exists, prefer its `theme_reset` block. Otherwise these are the known overrides Dawn / OS 2.0 themes inject at the section level:
+```css
+/* What Dawn / typical OS 2.0 themes inject (informational — do NOT include in your output) */
+.shopify-section { --section-padding-top: 36px; --section-padding-bottom: 36px; }
+.shopify-section img { max-width: 100%; height: auto; vertical-align: middle; }
+.shopify-section h1, .shopify-section h2, .shopify-section h3 {
+  font-family: var(--font-heading-family);
+  font-weight: var(--font-heading-weight);
+}
+.shopify-section button { font-family: inherit; }
+.shopify-section a { color: rgb(var(--color-link)); text-decoration: underline; }
+```
+This is what you are defending against. Every selector in your output that styles a property on this list MUST win on specificity (chained scope) and may need `!important` (font properties only).
+## Output skeleton
+```liquid
+{% style %}
+  /* 1. Reset */
+  .{scope}, .{scope} * { box-sizing: border-box; margin: 0; padding: 0; }
+  /* 2. Scope container (full-bleed if applicable) */
+  .{scope} { width: 100vw; margin-left: calc(50% - 50vw); }
+  /* 3. Element styles, mobile-first, with defensive specificity.
+     Liquid interpolations live here for setting-driven values. */
+  .{scope} .{scope}__title { font-size: 32px !important; font-weight: 700 !important; }
+  .{scope} .{scope}__hero {
+    aspect-ratio: 1 / 1.3;
+    max-height: 700px;
+    {% if section.settings.hero_image %}
+      background-image: url({{ section.settings.hero_image | image_url: width: 1600 }});
+    {% else %}
+      background-image: url('data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTcwIDkwMCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgc2xpY2UiPjxyZWN0IHdpZHRoPSIxMTcwIiBoZWlnaHQ9IjkwMCIgZmlsbD0iI2Q0ZDRkNCIvPjwvc3ZnPg==');
+    {% endif %}
+    background-size: cover;
+    background-position: center;
+  }
+  /* 4. Desktop overrides */
+  @media (min-width: 1000px) {
+    .{scope} .{scope}__hero { aspect-ratio: 16 / 9; max-height: 720px; }
+  }
+{% endstyle %}
+<section class="{scope}">
+  <h1 class="{scope}__title">{{ section.settings.heading | escape }}</h1>
+  {% if section.settings.cta_label != blank %}
+    <a href="{{ section.settings.cta_link | default: '/' }}" class="{scope}__cta">
+      {{ section.settings.cta_label | escape }}
+    </a>
+  {% endif %}
+</section>
+<script>
+  /* optional vanilla JS */
+</script>
+{% schema %}
+{
+  "name": "Hero (cloned)",
+  "tag": "section",
+  "class": "{scope}-wrapper",
+  "settings": [
+    { "type": "header", "content": "Content" },
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Welcome" },
+    { "type": "image_picker", "id": "hero_image", "label": "Hero image" },
+    { "type": "text", "id": "cta_label", "label": "CTA label", "default": "Shop now" },
+    { "type": "url", "id": "cta_link", "label": "CTA link" }
+  ],
+  "presets": [
+    { "name": "Hero — clone of source", "category": "Image" }
+  ]
+}
+{% endschema %}
+```
+If there's no JS, omit the `<script>` block entirely. Settings inside the schema follow the lift-into-settings table above.
+## What "production-grade" means
+The output must score high on Lighthouse the moment it lands — not after follow-up tweaks. Concretely:
+- All images have alt + correct loading attr
+- Hero uses `loading="eager" fetchpriority="high"`
+- No `<link rel="preconnect">` or external font stylesheet (Shopify owns `<head>`)
+- No layout-shift bombs (`width`/`height` on images, `aspect-ratio` on media)
+- Buttons have type="button"
+- No console errors from missing assets (every src is a real `localPath` or settings-driven via `image_url`)
+- Schema validates as JSON (the validator parses it strictly)
+- Liquid syntax is balanced (`{% if %}` matched by `{% endif %}`, etc.)
+- Every editable value has a setting AND a Liquid placeholder referencing it
+- At least one preset
+- No setting `id` collisions; no `image_picker` with `default`; every block-iterated element has `{{ block.shopify_attributes }}`
+The structural validator (`scripts/build-shopify.mjs validate`) checks the mechanical subset of these. The rest is judgment calls.