similarbuild 0.1.0

package/templates/skills/sb-build-shopify/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sb-build-shopify
+description: Composes a standalone Shopify section `.liquid` file from a live-page inspection plus extracted assets, with editable `{% schema %}` settings, defensive specificity against Dawn / OS 2.0, mobile-first CSS, and a11y/perf defaults baked in. Use when the SimilarBuild orchestrator (`/build-page`, `/build-site`, `/clip-section`) requests a Shopify build with `--target shopify`, or when the user asks to 'build shopify section' from an inspection + assets bundle.
+---
+
+# sb-build-shopify
+
+## Overview
+
+Produces the single `.liquid` file a merchant drops into their theme's `sections/` folder — a `{% style %}` block scoped to one root class, the matching markup with `{{ section.settings.* }}` placeholders for every editable value, optional `<script>`, and a mandatory `{% schema %}` JSON block declaring the editable fields and at least one preset. The merchant can then insert the section from "Add section" in the theme editor and edit text, colors, images, links, and toggles without touching code. The fragment must survive Dawn / Online Store 2.0's section-level CSS overrides without any post-paste tweaking.
+
+Unlike the upstream skills (`sb-inspect-live`, `sb-extract-assets`) where a script does ~95% of the work, **this skill is creative composition**. The LLM picks the pattern, names the classes and setting `id`s, structures the markup, and decides which values to lift into `{% schema %}` settings vs. hardcode. The `scripts/build-shopify.mjs` helper handles only the deterministic plumbing: structural validation (Liquid tag balance, schema JSON parsing, anti-pattern checks) and formatted persistence to disk.
+
+Act as a Shopify theme specialist. You know exactly which Dawn / OS 2.0 overrides bite (typography via `--font-heading-family` / `--font-body-family` CSS variables; `img { max-width: 100%; height: auto }`; section-padding scale via `--section-padding-*`) and you defend against all of them with chained-scope selectors and surgical `!important` on the four font properties only. You design the schema so a non-technical merchant can edit copy, images, and colors from the theme editor sidebar. You do NOT touch HTML for Elementor, Liquid for Webflow, or any other target — that's a different skill's job.
+
+## Inputs
+
+| Argument          | Required | Notes                                                                                         |
+| ----------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `inspection`      | yes      | Path to `inspection.json` from `sb-inspect-live`. Drives section type, tokens, DOM structure. |
+| `assetsMap`       | yes      | Path to `assets-map.json` from `sb-extract-assets`. Source of every fallback image path and inline SVG. |
+| `outputPath`      | yes      | Where the final `.liquid` is written (parent dirs created automatically). Single-file output. |
+| `designKnowledge` | no       | Subset of `<plugin>/memory/design-knowledge.md` filtered by the orchestrator (a11y/perf rules relevant to this section). When absent, use the defaults in `references/shopify-build-rules.md`. |
+| `fixHints`        | no       | JSON array from `sb-review-checks` after a failed validation cycle. When present, you are patching a previous build, not building from scratch. |
+| `previousLiquidPath` | no    | Path to the previous build (only meaningful with `fixHints`). Read it, apply the targeted patches, do not refactor untouched code. |
+
+The orchestrator passes these as concrete paths or inline values — there is no CLI for this skill, the LLM drives.
+
+## Output
+
+A single `.liquid` file written to `outputPath`. The file is a Shopify section fragment containing in order:
+
+1. Optional `{% style %}{% endstyle %}` block: universal reset → scope container (full-bleed if applicable) → mobile-first element styles with chained-scope selectors → `@media (min-width: 1000px)` desktop overrides. Liquid expressions inside the CSS are allowed and expected (background-image URLs, color settings).
+2. The scoped markup (`<section class="{scope}">...</section>` or appropriate semantic root), with `{{ section.settings.* }}` placeholders for every editable value.
+3. Optional `<script>` block for vanilla JS interactivity.
+4. Mandatory `{% schema %}{% endschema %}` JSON block with `name`, optional `tag` / `class`, `settings` array, optional `blocks` array, and a non-empty `presets` array.
+
+No `<html>`, `<head>`, `<body>`, no Google Fonts `<link>` (Shopify owns `<head>`).
+
+## On Activation
+
+1. **Read the inputs.** Parse `inspection.json` (capture `sectionType`, `tokens`, `dom`, `pseudoElements`, `imgUrls`) and `assets-map.json` (the URL → localPath / inline-SVG dictionary). If `fixHints` is given, also read `previousLiquidPath`.
+
+2. **Load the build rules.** Read `references/shopify-build-rules.md` — composition contract, schema-settings lift table (which inspected values become which setting types), defensive-specificity rule, !important policy, full-bleed escape, mobile-first breakpoint, asset-substitution rule, hero rules (no 100vh), font policy (no Google Fonts `<link>`, use `font_face` filter or theme inheritance), a11y/perf defaults, patterns A-H adapted to Liquid + blocks, anti-patterns 1-9 plus Shopify-specific 10-15. Treat it as your reference manual for this build.
+
+3. **Layer in user-curated knowledge if present.** When `<plugin>/memory/patterns.md`, `<plugin>/memory/anti-patterns.md`, or `<plugin>/presets/shopify-section.yaml` exist in the host project, load them and let them OVERRIDE the matching defaults from `shopify-build-rules.md` — they reflect the user's most recent learning. Skip silently when missing.
+
+4. **Compose the .liquid.** Pick the pattern that matches `inspection.sectionType` (and the markup shape — inspect `dom` and `pseudoElements`). Apply every non-negotiable from `shopify-build-rules.md`:
+
+   - Scope class (kebab-case, `sb-`-prefixed) on the outermost element, chained as ancestor on EVERY selector inside `{% style %}`.
+   - Universal reset at the top.
+   - Full-bleed container if the section spans viewport-edge.
+   - Mobile-first base + `@media (min-width: 1000px)` overrides.
+   - Every fallback `<img src>` resolved through `assetsMap.assets[url].localPath`. Settings-driven images use `{{ image | image_url: width: N }}`.
+   - SVGs inlined from `assetsMap.assets[url].inline` for icons; file path for hero/content.
+   - No 100vh, no fabricated SVG, no Google Fonts `<link>`.
+   - Lift every editable value into a `{% schema %}` setting (use the type table in the rules — text, richtext, color, image_picker, url, checkbox, select, range, font_picker). Replace the hardcoded literal with `{{ section.settings.<id> }}`. For `image_picker`, pair with a `{% if %}{% else %}` Liquid fallback to the local path (no `default` field).
+   - Heading hierarchy unbroken, alt on every `<img>`, type="button" on every `<button>`, icon-only buttons get `aria-label`.
+   - At least one preset in the schema. `category` reasonable (Image, Text, Banners, Promotional).
+   - If the section has repeating elements (cards, FAQ entries), model them as `blocks` and emit `{{ block.shopify_attributes }}` on every iterated element.
+
+5. **If `fixHints` are present, patch surgically.** Read the previous output, apply each fixHint to the specific selector, markup, or schema entry it names, and keep everything else untouched. Do not rename setting `id`s — that orphans merchant edits. High-severity hints are mandatory; low-severity are optional unless they conflict.
+
+6. **Validate.** Write the composed `.liquid` to a temp file and run:
+
+   ```bash
+   node {skill-root}/scripts/build-shopify.mjs validate --liquid-file <tmp>
+   ```
+
+   The script reports structural errors (missing `{% schema %}`, invalid schema JSON, missing `name` / `presets`, `image_picker` with `default`, duplicate setting `id`s, unbalanced Liquid tags, missing alt/type, `data:image/svg+xml` raster impostors, `100vh` heights, Google Fonts `<link>`, block loop without `{{ block.shopify_attributes }}`) and warnings (no reset, no defensive-specificity selectors, hardcoded CDN URLs, missing `loading` attrs, `<style>` with Liquid that should be `{% style %}`). Exit code 0 means errors are clean. If it exits 3, fix the flagged issues and re-validate. Warnings are advisory.
+
+7. **Persist.** Pipe the validated `.liquid` into:
+
+   ```bash
+   node {skill-root}/scripts/build-shopify.mjs write --output-path <outputPath>
+   ```
+
+   The script formats with prettier when available (graceful skip when not installed), writes to `outputPath` (single file, no directory layout), and returns `{path, bytes, formatted, validatedSchema, schemaErrors}` JSON. `validatedSchema: true` confirms the persisted schema parsed clean.
+
+8. **Return the result** to the orchestrator: the absolute path to the written file, the validator's report (errors + warnings), and a short note on which pattern was applied and which settings were lifted into the schema. Do not return the file's contents.
+
+## Failure modes
+
+| Symptom                                              | Likely cause                                       | What to surface                                                            |
+| ---------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
+| Validator returns errors after first compose         | Missed a non-negotiable from the rules             | Fix and re-validate (up to 2 attempts). If still failing, surface the report. |
+| Schema JSON fails to parse                           | Trailing comma, unescaped quote, comment in JSON   | Strip comments, balance braces, re-validate. JSON is strict — no leniency. |
+| `assetsMap.failed[]` includes a critical asset       | Source 404 / network failure during extract        | Drop the image (decorative) or use a literal-color placeholder (hero). Never fabricate. Comment in the output. |
+| `inspection.widgetBlocked: true`                     | Bot challenge on inspect — DOM is unreliable       | Stop. Tell the orchestrator the inspection is unusable. Do not compose from a blocked page. |
+| Pattern doesn't match any section in `inspection.dom`| Section type detected but markup is ambiguous      | Pick the closest pattern from A-H, document the choice in a comment, surface to the orchestrator. |
+| Prettier missing                                     | Optional dep not installed                         | Non-fatal — `write` reports `formatted: false, formatterSkippedReason: "prettier-not-installed"`. Output is still written. |
+| liquidjs missing                                     | Optional dep not installed                         | Non-fatal — full Liquid parse skipped, regex tag-balance check still runs. |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/build-shopify.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.
+- `<plugin>/memory/...` and `<plugin>/presets/...` are paths inside the SimilarBuild plugin install — read them when present, fall back to bundled defaults when absent.
+
+## Optional npm dependencies
+
+- `prettier` — formats the output before write. Skipped gracefully if missing.
+- `liquidjs` — full Liquid parse during validate. Skipped gracefully if missing; regex tag-balance check still runs and catches the common breakage.