@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.cursor/commands/add-field.md

@@ -0,0 +1,83 @@
+---
+description: Add a new setting/field to an existing section — updates section, page JSON, and snippets
+alwaysApply: false
+---
+
+# /add-field
+
+Add a new setting to an existing section. Updates all affected files.
+
+## Usage
+```
+/add-field <theme_name> <section_name>
+```
+Describe: what the field controls, type, where it appears visually.
+
+---
+
+## Pre-flight
+Open: section file, page JSON that uses it, related snippets.
+
+---
+
+## Stage 1 — Determine Field Spec
+State before editing:
+```
+FIELD SPEC
+━━━━━━━━━━━━━━━━━━━━━━
+Type:        [text/richtext/url/image_picker/select/checkbox/range/color/menu]
+ID:          [snake_case_id]
+Level:       [section setting / block setting — which block type]
+Label key:   t:sections.<n>.settings.<id>.label
+Default:     [correct format for type]
+Renders at:  [line / location in HTML]
+Schema after: [existing field it goes after]
+```
+Ask: "Proceed?" before editing.
+
+**Choose `text` vs `richtext`:**
+- Renders in `<h1>`–`<h6>` or as title/eyebrow/badge/button label → `text`
+- Renders as paragraph, description, or multi-line body copy → `richtext`
+- Heading blocks must never use `richtext`
+
+---
+
+## Stage 2 — Update Schema
+Add field using correct custom syntax:
+
+- text: `{ "type": "text", "id": "x", "label": "t:...", "default": "t:..." }` — headings, titles, labels
+- richtext: `{ "type": "richtext", "id": "x", "label": "t:...", "default": "<p>t:...</p>" }` — descriptions, body copy
+- url: `{ "type": "url", "id": "x", "label": "t:...", "default": { "display_name": "t:...", "handle": "/" } }`
+- image_picker: `{ "type": "image_picker", "id": "x", "label": "t:...", "default": { "url": "placeholder.webp", "enable_customisation": true } }`
+- select: `{ "type": "select", "id": "x", "label": "t:...", "options": [...], "default": { "display_name": "t:...", "value": "option" } }`
+- checkbox: `{ "type": "checkbox", "id": "x", "label": "t:...", "default": false }`
+- range: `{ "type": "range", "id": "x", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40, "label": "t:..." }`
+- color: `{ "type": "color", "id": "x", "label": "t:...", "default": "#000000" }`
+- menu: `{ "type": "menu", "id": "x", "label": "t:...", "default": { "display_name": "t:...", "handle": "" } }`
+
+## Stage 3 — Add Liquid Assign
+Add to `{% liquid %}` block:
+- text/range/color/checkbox → `assign x = section.settings.x`
+- url/menu → `assign x = section.settings.x` (render as `{{ x.handle }}`)
+- select → `assign x = section.settings.x` (render as `{{ x.value }}`)
+- image → `assign x = section.settings.x` (render as `{{ x.url }}`)
+
+Wrap optional fields: `{% if x != blank %}...{% endif %}`
+
+## Stage 4 — Update Page JSON
+Add field with correct inline value format to the relevant section in page JSON.
+
+## Stage 5 — Update Snippets
+If field value is passed to a `{% render %}` call → update the snippet too.
+
+---
+
+## Output
+List all files changed, lines modified.
+Always remind:
+```
+⚠️ Add translation keys to i18n/en.schema.json:
+  "t:sections.<n>.settings.<id>.label": "Your Label"
+  "t:sections.<n>.settings.<id>.default": "Default Text"
+```
+→ NEXT: `/qa-section <theme_name> <section_name>`

package/ts-dist/mocks/init-theme/.cursor/commands/add-theme-setting.md

@@ -0,0 +1,200 @@
+---
+description: Add a new global or component setting to theme schema + theme.json + i18n
+alwaysApply: false
+---
+
+# /add-theme-setting
+
+Add one or more fields to **theme-level** settings (`settings/schema.json`), defaults in **`settings/theme.json`**, and translation keys in **`i18n/en.schema.json`**.
+
+Use this for product card options, view transitions, blog card defaults, navigation behaviour, etc.  
+**Not** for section `{% schema %}` — use `/add-field` for sections.
+
+## Usage
+```
+/add-theme-setting <theme_name>
+```
+
+Describe in chat:
+
+- **Group:** which settings block to extend, e.g. `theme` (main theme + product card block), `social_media`, `message_bar`, or **new group** name slug (e.g. `view_transitions`).
+- **Meta (for new group only):** `global_settings` (token-sync candidate) or `component_settings` (merchant/feature toggles, not overwritten by `/sync-theme-settings`).
+- **Field(s):** type, id (`snake_case`), label meaning, default, min/max/step for range, options for select.
+
+---
+
+## Pre-flight
+
+1. Read `settings/schema.json` — list top-level groups (`name`, `meta`, `settings` length).
+2. Read `settings/theme.json` — note every key under `presets` (update **all** presets with the new key so nothing breaks).
+3. Read `i18n/en.schema.json` — find matching `settings_schema.<group_slug>` for label paths.
+
+---
+
+## Stage 1 — Theme field spec (before editing)
+
+Print and confirm:
+
+```
+THEME FIELD SPEC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Theme:       <theme_name>
+Group:       <existing group slug OR new: view_transitions>
+Meta:        <component_settings | global_settings> (new groups only)
+Fields:
+  1. id: enable_view_transitions | type: checkbox | default: false
+  2. id: page_transition_style   | type: select   | options: none, fade, slide
+Label keys:  t:settings_schema.<group>.settings.<id>.label
+             (+ options__N for select)
+theme.json:  Add key + default to EVERY preset under presets.{}
+Proceed? [y]
+```
+
+**Id rules:** unique across **all** presets’ keys in `theme.json` (flat merge of settings from every group).
+
+---
+
+## Stage 2 — Update `settings/schema.json`
+
+### Existing group
+
+Insert the new field object into that group’s `settings` array (after a related field or before closing). Use correct types:
+
+| Type | Schema shape |
+|------|----------------|
+| `text` | `id`, `label` (t:), optional `placeholder` (t:) |
+| `checkbox` | `id`, `label` (t:), `default` boolean in schema |
+| `range` | `id`, `label` (t:), `min`, `max`, `step`, `unit`, `default` number |
+| `color` | `id`, `label` (t:), `default` hex |
+| `select` | `id`, `label` (t:), `options` array `{ "value", "label": "t:..." }`, `default` `{ "value", "label": "t:...options__N..." }` matching first option’s label key |
+| `header` | `type: "header"`, `content`: "t:..." (section divider in UI) |
+
+Match existing theme patterns (see `settings/schema.json`).
+
+### New group
+
+Append a new object to the root array:
+
+```json
+{
+  "name": "t:settings_schema.<group_slug>.name",
+  "settings": [
+    { "type": "header", "content": "t:settings_schema.<group_slug>.settings.section_header.content" },
+    { ...fields... }
+  ],
+  "meta": "component_settings"
+}
+```
+
+- **`global_settings`** — only if the field should be updated from Figma via `/sync-theme-settings` (then add mapping in that command’s doc).
+- **`component_settings`** — default for feature toggles, transitions, card layout options not driven by token export.
+
+---
+
+## Stage 3 — Update `settings/theme.json`
+
+For **each** key in `presets` (e.g. `Default` and any others):
+
+- Add the new setting id with the correct inline value:
+  - checkbox → `true` / `false`
+  - range/number → number
+  - color → `"#RRGGBB"`
+  - select → `{ "value": "none", "label": "t:settings_schema.<group>.settings.<id>.options__1.label" }` (same shape as existing selects)
+  - text → `""` or default string
+
+Never remove or rename unrelated keys.
+
+---
+
+## Stage 4 — Update `i18n/en.schema.json`
+
+Under `settings_schema`, ensure the group exists:
+
+**Existing group** (e.g. `theme`): add under `settings.<id>`:
+
+```json
+"<id>": {
+  "label": "Human-readable label"
+}
+```
+
+For **select**, add `options__1`, `options__2`, … under that id.
+
+**New group** `<group_slug>`:
+
+```json
+"<group_slug>": {
+  "name": "View transitions",
+  "settings": {
+    "section_header": { "content": "Animations" },
+    "enable_view_transitions": { "label": "Enable view transitions" },
+    "page_transition_style": {
+      "label": "Page transition",
+      "options__1": { "label": "None" },
+      "options__2": { "label": "Fade" },
+      "options__3": { "label": "Slide" }
+    }
+  }
+}
+```
+
+All schema `label` / `content` / `placeholder` fields must still use **`t:`** keys pointing to these paths (e.g. `t:settings_schema.view_transitions.settings.enable_view_transitions.label`).
+
+---
+
+## Stage 5 — Wire-up (**required** unless user says **schema only**)
+
+A theme setting is **not done** until it changes storefront behaviour (or is intentionally “schema only” for a later PR).
+
+| Setting intent | Typical wire-up |
+|----------------|-----------------|
+| Toggle (feature on/off) | `layouts/theme.liquid` / `accounts.liquid`: conditional script, `data-*` on `<html>`, or `{% if settings.x %}…{% endif %}` |
+| Color / range / spacing | `snippets/theme-settings.liquid` → `:root { --token: {{ settings.id }} }` |
+| Select (behaviour) | JS reads `settings` via inline assign in layout or CSS custom property |
+| URL / text | Liquid where consumed (header, footer, snippet) |
+
+**Checklist before marking complete:**
+
+1. [ ] **Read path:** Document how Liquid/JS/CSS reads `settings.<id>` (same id as schema).
+2. [ ] **Layouts:** Main storefront layout(s) load any new asset or conditional block.
+3. [ ] **Accounts layout:** If the setting affects global chrome, mirror in `accounts.liquid` when applicable.
+4. [ ] **Opt-out:** Only skip wire-up if the user explicitly requests **schema only**.
+
+---
+
+## Stage 6 — Figma-driven globals (optional)
+
+If the new field should be filled by **`/sync-theme-settings`**:
+
+1. Add a row to the mapping table in `.cursor/commands/sync-theme-settings.md` (field id → `figma-variables.json` path).
+2. Re-run `/sync-theme-settings <theme_name>` after designer exports tokens.
+
+Fields that are **not** in the sync mapping stay as whatever you put in `theme.json`.
+
+---
+
+## Output
+
+```
+✅ THEME SETTING(S) ADDED + WIRED
+
+Files changed:
+  - settings/schema.json
+  - settings/theme.json
+  - i18n/en.schema.json
+  - layouts / snippets / assets (wire-up — list each)
+
+IDs added: <list>
+Runtime: [how settings.<id> is consumed]
+
+NEXT:
+  - If token-mapped: extend /sync-theme-settings mapping + re-run sync
+```
+
+---
+
+## Notes
+
+- **`/add-field`** = section schema only. **`/add-theme-setting`** = theme customizer schema.
+- **`/sync-theme-settings`** overwrites only fields listed in its mapping for **global_settings** groups; it does not add new keys automatically.
+- Keep **snake_case** ids consistent between schema, theme.json, and Liquid/CSS/JS references.

package/ts-dist/mocks/init-theme/.cursor/commands/assemble-page.md

@@ -0,0 +1,72 @@
+---
+description: Generate page JSON from completed sections
+alwaysApply: false
+---
+
+# /assemble-page
+
+Generate the page JSON from all completed sections. Run after all sections are built and QA'd.
+
+## Usage
+```
+/assemble-page <theme_name> <page_name>
+```
+
+---
+
+## Step 1 — Check Built Sections
+- Read audit plan for this page
+- List which sections exist in `sections/`
+- Warn about any missing sections, ask: "Proceed with available or wait?"
+
+## Step 2 — Read Section Schemas
+For each section: read `{% schema %}` to extract all setting IDs and types.
+
+## Step 3 — Generate Page JSON
+
+```jsonc
+{
+  "layout": "theme",
+  "sections": {
+    "<section_key>": {
+      "type": "<section_filename>",
+      "settings": {
+        "heading": "Section Heading",
+        "cta_url": { "display_name": "Shop Now", "handle": "/collection" },
+        "banner_image": { "url": "banner.webp", "enable_customisation": true },
+        "layout_type": { "display_name": "Left", "value": "left-alignment" },
+        "nav_menu": { "display_name": "Main Menu", "handle": "main-menu" },
+        "show_heading": true,
+        "padding_top": 40,
+        "padding_bottom": 40,
+        "overlay_color": "#000000"
+      },
+      "blocks": {
+        "<block_key>": {
+          "type": "<block_type>",
+          "settings": {}
+        }
+      },
+      "block_order": ["<block_key>"]
+    }
+  },
+  "order": ["<section_key_1>", "<section_key_2>"]
+}
+```
+
+### Inline value rules:
+- text → plain string
+- url → `{ "display_name": "Label", "handle": "/path" }`
+- image_picker → `{ "url": "file.webp", "enable_customisation": true }`
+- select → `{ "display_name": "Label", "value": "option-value" }`
+- menu → `{ "display_name": "Label", "handle": "handle-name" }`
+- checkbox → boolean
+- range/number → number
+- color → hex string
+
+## Step 4 — Save
+Write to `pages/<page_name>.json`
+If file exists → show diff, ask for confirmation before overwriting.
+
+## Step 5 — Confirm
+List sections included, skipped, and next steps.

package/ts-dist/mocks/init-theme/.cursor/commands/audit-page.md

@@ -0,0 +1,57 @@
+---
+description: Audit a Figma page and produce a section build plan before writing any code
+alwaysApply: false
+---
+
+# /audit-page
+
+Analyse a Figma page and produce a structured section inventory.
+NO CODE is written — only a build plan. User approves before any section is built.
+
+## Usage
+```
+/audit-page <theme_name> <page_name>
+```
+Provide the Figma page frame via MCP or screenshot.
+
+---
+
+## Step 1 — Read the Figma Page
+Scan top to bottom. For each section identify:
+- Section name (descriptive slug e.g. `hero-banner`, `category-grid`)
+- Type: `section` (full layout block) or `snippet` (reusable UI element)
+- Figma frame name (exact name in Figma)
+- Reference match: scan `sections/` for closest existing file
+  - Found → REUSE + REDESIGN with path
+  - Not found → NEW
+
+## Step 2 — Output Build Plan
+
+```
+Page: <page_name> — <theme_name>
+
+SECTION BUILD PLAN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  | Section Name      | Figma Frame        | Reference                              | Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1  | header            | —                  | snippets/header.liquid  | SHARED (skip)
+2  | hero-banner       | Homepage/Hero      | sections/banner.liquid  | REUSE + REDESIGN
+3  | category-grid     | Homepage/Category  | sections/cat-grid.liquid| REUSE + REDESIGN
+4  | featured-products | Homepage/Featured  | none                                    | NEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SUMMARY
+  SHARED (skip): 1 | REUSE + REDESIGN: 2 | NEW: 1
+
+SUGGESTED BUILD ORDER: 2 → 3 → 4
+```
+
+## Step 3 — Ask for Approval
+```
+Does this plan look correct?
+YES → proceed | EDIT → adjust a row | /build-section <n> → jump to a section
+```
+Do NOT write any code until user confirms.
+
+## Step 4 — On Approval
+Remind: `Run /build-section <theme_name> <section_name> — one section at a time.`

package/ts-dist/mocks/init-theme/.cursor/commands/build-page-sections.md

@@ -0,0 +1,110 @@
+---
+description: Batch-build all sections from an approved audit plan — with integrated design verification
+alwaysApply: false
+---
+
+# /build-page-sections
+
+Build **every section** listed in an approved `/audit-page` plan in one run.
+Each section follows the full build process including design spec extraction and self-compare verification.
+
+## Usage
+```
+/build-page-sections <theme_name> <page_name>
+```
+
+Provide desktop and mobile Figma URLs (or node IDs) when prompted.
+
+---
+
+## Pre-flight
+
+1. Confirm `figma-variables.json` exists. If missing → STOP.
+2. Look for the approved audit plan for `<page_name>` in the conversation history.
+   - If no plan exists → STOP: run `/audit-page <theme_name> <page_name>` first.
+3. List sections to build from the plan. Skip rows marked **SHARED (skip)**.
+4. For REUSE + REDESIGN rows, note the reference section path.
+5. For NEW rows, note there is no reference — build from Figma only.
+6. Read `.cursor/rules/design-spec-extraction.mdc` — the extraction protocol to follow for every section.
+
+---
+
+## Build Loop
+
+For each section in the plan's **SUGGESTED BUILD ORDER**:
+
+### Step 1 — Fetch Figma Frames (BOTH desktop AND mobile)
+- Use the Figma MCP `get_design_context` tool with the section's node ID.
+- **Always fetch both desktop and mobile frames.** If the plan includes separate desktop and mobile node IDs, fetch both.
+- If no node ID is available for a section, ask the developer to select the frame in Figma and provide the URL.
+
+### Step 2 — Build the Section (Full /build-section with Design Verification)
+Run the complete `/build-section` logic (Stages 1–8):
+
+1. **Read reference section** (if REUSE/REDESIGN) — extract schema, logic, loops, renders, JS.
+2. **Extract detailed design spec from Figma** — Follow the Design Spec Extraction Protocol (`.cursor/rules/design-spec-extraction.mdc`). Extract EXACT values for every visible element. Resolve all `var()` from `figma-variables.json`. Produce the Design Spec Table. **DO NOT SKIP THIS.**
+3. **Map Figma values to tokens** — font sizes → Tailwind classes, colours → CSS variables, spacing → Tailwind. Update the spec table's Tailwind/CSS column.
+4. **Build HTML structure** — semantic HTML + Tailwind + CSS variables. Dynamic content via Liquid assigns. **Use the Design Spec Table as the blueprint — every row must appear in code.**
+5. **Add schema** — custom syntax (not Shopify). All labels use `t:` keys. Heading/title fields → `text`; body/description → `richtext` (never `richtext` on heading blocks). Include `padding_top`/`padding_bottom` with Figma-accurate defaults. At least one preset.
+6. **Add style block + script** — `{% style %}` for dynamic values, script tag if JS component needed.
+7. **Self-compare against Design Spec Table** — For every row in the spec, verify the corresponding HTML element has the exact Tailwind class / CSS variable. Fix any mismatches before saving. Produce a self-compare summary.
+8. **Code QA** — every `section.settings.X` has a schema field, no raw hex, no raw px fonts, loops have empty states, images have all attrs, labels use `t:` keys, heading fields use `text` not `richtext`.
+
+### Step 3 — Write File
+Save to `sections/<section_name>.liquid`.
+
+### Step 4 — Log Result
+Record one of:
+- `BUILT` — section created successfully (include spec match percentage)
+- `SKIPPED` — SHARED section, no build needed
+- `FAILED` — could not build (missing Figma data, unresolved tokens, etc.)
+
+Proceed to the next section. Do not stop the batch for warnings — log them and continue.
+
+---
+
+## After All Sections
+
+### i18n Keys
+Collect all `t:sections.<name>.settings.*` and `t:sections.<name>.blocks.*` keys from every built section. Add them to `i18n/en.schema.json` under the appropriate `sections.<name>` paths.
+
+### Summary Report
+
+```
+BUILD PAGE SECTIONS — <page_name> (<theme_name>)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#  | Section               | Status  | Spec Rows | Match % | Reference
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1  | header                | SKIPPED | —         | —       | shared
+2  | hero-banner           | BUILT   | 24        | 100%    | sections/hero-banner.liquid
+3  | product-carousel      | BUILT   | 18        | 97%     | sections/product-carousel-section.liquid
+4  | featured-collection   | BUILT   | 15        | 100%    | none (NEW)
+...
+
+OVERALL DESIGN ACCURACY: <percentage>% across all sections
+
+SUMMARY
+  Built: <n>  |  Skipped: <n>  |  Failed: <n>
+
+⚠️ UNMAPPED TOKENS (review):
+  - [section]: [token name] → used [fallback]
+
+⚠️ UNRESOLVED SPEC ITEMS:
+  - [section]: [element] → [property] could not be verified
+
+NEXT STEPS:
+  1. /qa-sections <theme_name>                — batch QA all built sections
+  2. /compare-section per section             — only for sections with <100% match
+  3. /assemble-page <theme_name> <page>       — generate page JSON
+```
+
+---
+
+## Notes
+
+- This command uses the same self-compare verification as `/build-section`. Most design accuracy issues are caught and fixed during the build itself.
+- If a section build fails, the batch continues. Fix failed sections individually with `/build-section`.
+- The developer can interrupt the batch at any time. Already-written files are kept.
+- Section groups (`header-group.json`, `footer-group.json`) are NOT built by this command — they are config files that reference sections.
+- The Design Spec Table for each section is logged but not saved to disk. Run `/compare-section` to regenerate it for any section that needs further review.