@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.cursor/commands/sync-theme-settings.md

@@ -0,0 +1,132 @@
+---
+description: Sync theme settings values from figma-variables.json into settings/theme.json
+alwaysApply: false
+---
+
+# /sync-theme-settings
+
+Read `figma-variables.json` and populate `settings/theme.json` with correct
+values for all token-driven fields. Non-token fields (social links, checkboxes,
+text content) are left unchanged.
+
+## Usage
+```
+/sync-theme-settings <theme_name>
+```
+
+---
+
+## Step 1 — Read Both Files
+
+Read these two files before doing anything:
+1. `figma-variables.json` — token source of truth
+2. `settings/theme.json` — current values to update
+
+---
+
+## Step 2 — Understand the Field Categories
+
+Settings have a `meta` field that determines how they are treated:
+
+**`global_settings`** — theme-level, driven by Figma tokens
+Update these automatically from `figma-variables.json`.
+
+**`component_settings`** — component defaults, not token-driven
+Leave these exactly as-is. Never overwrite component settings.
+
+---
+
+## Step 3 — Token Mapping Rules
+
+For every field in the `global_settings` group, apply this mapping:
+
+### Colors
+Read hex values from `figma-variables.json` using this map:
+
+| Field ID | Token Path in JSON |
+|---|---|
+| `background_color` | `color > Background 1 > Background 1 > $value > hex` |
+| `card_background` | `color > white > $value > hex` → `#FFFFFF` |
+| `primary_color` | `color > Primary Color > Primary > $value > hex` |
+| `accent_color` | `color > Secondary Color > Secondary > $value > hex` |
+| `footer_background` | `color > black > $value > hex` → `#000000` |
+| `sale_badge_color` | `color > Toast Message > Error > $value > hex` |
+
+### Spacing / Radius (range fields)
+Read numeric values from `figma-variables.json`:
+
+| Field ID | Token Path in JSON | Notes |
+|---|---|---|
+| `product_card_padding` | `Padding > P - 4 > $value` | Default card padding |
+| `product_card_gap` | `Gap > G - 3 > $value` | Default card gap |
+| `product_card_border_radius` | `radius > sm > $value` | Card radius |
+| `product_card_border_width` | `border-width > 1 > $value` | Default border |
+| `product_card_image_border_radius` | `radius > xs > $value` | Image radius |
+
+### Fields to Leave Unchanged
+Never touch these — they are not token-driven:
+
+- `product_grid_columns` — layout decision, not a token
+- `show_sidebar_filters` — feature toggle
+- `product_card_image_ratio` — layout decision
+- `product_card_show_sku` — feature toggle
+- `product_card_show_in_stock` — feature toggle
+- All `social_*` fields — merchant data
+- All `message_bar_*` fields — content, not design tokens
+- `enable_message_bar` — feature toggle
+
+---
+
+## Step 4 — Write Updated theme.json
+
+Update ONLY the `Default` preset in `settings/theme.json`.
+Keep the exact same JSON structure — only change the values of token-driven fields.
+
+After writing, print a summary:
+```
+✅ settings/theme.json updated for <theme_name>
+
+TOKEN-DRIVEN FIELDS UPDATED:
+  background_color  →  #FAFAFA  (from color/Background 1)
+  card_background   →  #FFFFFF
+  primary_color     →  #5E2BFF  (from color/Primary Color)
+  accent_color      →  #C04CFD  (from color/Secondary Color)
+  footer_background →  #000000
+  sale_badge_color  →  #FF7979  (from color/Toast Message/Error)
+  product_card_padding          →  16  (from Padding/P - 4)
+  product_card_gap              →  12  (from Gap/G - 3)
+  product_card_border_radius    →  8   (from radius/sm)
+  product_card_border_width     →  1   (from border-width/1)
+  product_card_image_border_radius → 4 (from radius/xs)
+
+UNCHANGED (non-token fields):
+  product_grid_columns, show_sidebar_filters, product_card_image_ratio,
+  product_card_show_sku, product_card_show_in_stock,
+  social_* fields, message_bar_* fields
+
+⚠️ MISMATCHES (if any):
+  footer_background — token value #000000 differs from current ""
+  sale_badge_color  — token value #FF7979 differs from current ""
+  → Review these before committing
+```
+
+---
+
+## When to Re-run
+
+Re-run `/sync-theme-settings <theme_name>` whenever:
+- Designer updates and re-exports `figma-variables.json`
+- A new color token is added that maps to a settings field
+- You start a new theme and want defaults populated from tokens
+
+---
+
+## Adding a new token-mapped field
+
+If you add a **new** `global_settings` field via `/add-theme-setting` that should be filled from Figma:
+
+1. Add the field to `settings/schema.json` and `theme.json` (via `/add-theme-setting`).
+2. **Extend this command’s mapping table** (Step 3): new row = field `id` → path in `figma-variables.json` (same pattern as existing colors/ranges).
+3. Re-run `/sync-theme-settings <theme_name>`.
+
+Fields not listed in the mapping are never overwritten by sync.

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

@@ -0,0 +1,60 @@
+---
+description: Verify page JSON references real sections and blocks
+alwaysApply: false
+---
+
+# /validate-page
+
+After `/assemble-page`, verify that the page JSON is valid: every section type exists, every block type is allowed by the section schema, and `order`/`block_order` reference real keys.
+
+## Usage
+```
+/validate-page <theme_name> <page_name>
+```
+
+---
+
+## Pre-flight
+
+1. Read `pages/<page_name>.json`.
+2. Read `sections/*.liquid` as needed to resolve section `type` and allowed block types.
+3. Read `blocks/*.liquid` as needed to resolve theme block schemas and nested children.
+
+---
+
+## Validation rules
+
+Use the contract in `.cursor/skills/page-json-contract.md`. Check:
+
+1. **order:** Every entry in `order` exists as a key in `sections`. No extra keys in `sections` that are not in `order` (optional strict check).
+2. **Section type:** For each `sections.<key>.type`, the file `sections/<type>.liquid` exists (e.g. `product-details` → `product-details.liquid`).
+3. **Blocks:** For each section that has `blocks` and `block_order`:
+   - Every key in `block_order` exists in `blocks`.
+   - For each `blocks.<key>.type`:
+     - **Local block** (bare name): declared in that section's `{% schema %}` `blocks` array with inline `settings`.
+     - **Theme block** (`zc_theme__<name>`): `blocks/<name>.liquid` exists AND the section schema lists `{ "type": "@theme" }` or that specific `zc_theme__<name>` entry.
+   - Recursively validate nested `blocks` / `block_order` on theme block instances against the parent block file's schema.
+4. **Settings keys:** Optionally spot-check that top-level keys in `settings` and `blocks.<key>.settings` match the correct schema (section schema for local blocks; `blocks/<name>.liquid` schema for theme blocks). No strict validation of value format here — that's assemble-page's job.
+
+---
+
+## Output
+
+```
+VALIDATE PAGE — <page_name>.json (<theme_name>)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ order: all keys present in sections
+✅ section "hero": type "hero-and-banners" → sections/hero-and-banners.liquid exists
+✅ section "product": type "product-details" → sections/product-details.liquid exists
+❌ section "footer": type "footer" → sections/footer.liquid NOT FOUND
+✅ section "badges": block_order keys match blocks
+✅ section "badges": local type "badge" declared in section schema
+✅ section "badges": theme type "zc_theme__text" → blocks/text.liquid exists; allowed by section schema
+❌ section "hero": block "cta" type "zc_theme__button" → blocks/button.liquid NOT FOUND
+
+SUMMARY: PASS / FAIL
+Issues: [list any ❌]
+```
+
+If FAIL, list the issues and suggest fixing the page JSON, adding the missing section/block file, or updating the section schema to opt into the theme block.

package/ts-dist/mocks/init-theme/.cursor/commands/validate-section-group.md

@@ -0,0 +1,88 @@
+---
+description: Validate a section group JSON file (header-group, footer-group, etc.)
+alwaysApply: false
+---
+
+# /validate-section-group
+
+Validate a `*-group.json` file to ensure it references real sections, has correct structure, and is wired into a layout.
+
+## Usage
+```
+/validate-section-group <theme_name> <group_name>
+```
+
+`group_name` is without the `.json` extension (e.g. `header-group`, `footer-group`).
+
+---
+
+## Pre-flight
+
+1. Read `sections/<group_name>.json`.
+2. Read all layout files in `layouts/` to find `{% sections '<group_name>' %}` references.
+
+---
+
+## Validation Rules
+
+### 1. Valid JSON Structure
+- File parses as valid JSON.
+- Required top-level keys: `name`, `type`, `sections`, `order`.
+- `name` is a `t:` translation key (e.g. `t:sections.header.name`).
+- `type` is a string (e.g. `"header"`, `"footer"`).
+- `sections` is an object with at least one section entry.
+- `order` is an array of strings.
+
+### 2. Order Array Integrity
+- Every entry in `order` exists as a key in `sections`.
+- Every key in `sections` appears in `order` (no orphan sections).
+- No duplicate entries in `order`.
+
+### 3. Section Type Existence
+- For each `sections.<key>.type`, verify `sections/<type>.liquid` exists.
+
+### 4. Settings Validation
+- For each section entry that has `settings`:
+  - Read the corresponding section's `{% schema %}` to get its field definitions.
+  - Spot-check that setting keys in the group JSON match schema field `id` values.
+  - Verify value formats match the field type:
+    - select → `{ "display_name": "...", "value": "..." }`
+    - url → `{ "display_name": "...", "handle": "..." }`
+    - image_picker → `{ "url": "...", "enable_customisation": true }`
+    - menu → `{ "display_name": "...", "handle": "..." }`
+    - checkbox → boolean
+    - range/number → number
+    - color → hex string
+    - text → string
+
+### 5. Layout Wiring
+- At least one layout file in `layouts/` contains `{% sections '<group_name>' %}`.
+- If no layout references this group → flag as warning (the group file exists but is never rendered).
+
+### 6. Translation Keys
+- `name` field uses a `t:` key.
+- That `t:` key exists in `i18n/en.schema.json`.
+
+---
+
+## Output
+
+```
+VALIDATE SECTION GROUP — <group_name>.json (<theme_name>)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+STRUCTURE        ✅ / ❌
+ORDER INTEGRITY  ✅ / ❌
+SECTION TYPES    ✅ / ❌
+SETTINGS         ✅ / ⚠️ / ❌
+LAYOUT WIRING    ✅ / ⚠️
+TRANSLATION KEYS ✅ / ⚠️
+
+ISSUES:
+  ❌ [rule] description
+  ⚠️ [rule] description
+
+SUMMARY: PASS / FAIL
+```
+
+If FAIL, list each issue with a suggested fix. If PASS with warnings, list the warnings for developer review.

package/ts-dist/mocks/init-theme/.cursor/commands/validate-theme-settings.md

@@ -0,0 +1,119 @@
+---
+description: Cross-check settings/schema.json vs settings/theme.json vs i18n/en.schema.json vs Liquid consumers
+alwaysApply: false
+---
+
+# /validate-theme-settings
+
+Audit consistency across the three theme settings files and their Liquid consumers.
+Run after `/add-theme-setting`, `/sync-theme-settings`, or before release.
+
+## Usage
+```
+/validate-theme-settings <theme_name>
+```
+
+---
+
+## Pre-flight
+
+Read all four sources:
+
+1. `settings/schema.json` — field definitions grouped by category.
+2. `settings/theme.json` — preset values (check **every** preset under `presets`).
+3. `i18n/en.schema.json` — translation keys under `settings_schema`.
+4. `snippets/theme-settings.liquid` — where `settings.*` are consumed as CSS variables.
+
+---
+
+## Checks
+
+### 1. Schema ↔ Presets Sync
+For every field `id` across all groups in `schema.json`:
+- The same key exists in **every** preset in `theme.json`.
+- If a key is in a preset but not in any schema group → flag as **orphan in preset**.
+- If a key is in schema but missing from a preset → flag as **missing from preset**.
+
+### 2. Value Type Correctness
+For each key in each preset, verify the value matches the schema field type:
+
+| Schema type | Expected preset value |
+|-------------|----------------------|
+| `checkbox` | `true` or `false` (boolean) |
+| `range` | number |
+| `color` | hex string (e.g. `"#FFFFFF"`) |
+| `text` | string |
+| `richtext` | string |
+| `image_picker` | string (URL or empty `""`) |
+| `select` | object with `display_name` and `value` keys |
+
+Flag mismatches (e.g. select with `label` instead of `display_name`, checkbox with string value).
+
+### 3. Select Convention
+For every `select` field in `schema.json`:
+- **Default** must be `{ "display_name": "...", "value": "..." }` — not `{ "label": "...", "value": "..." }`.
+- **Options** array entries must use `{ "display_name": "...", "value": "..." }`.
+- Corresponding preset value in `theme.json` must also use `{ "display_name": "...", "value": "..." }`.
+- The preset's `value` must match one of the option values in schema.
+
+### 4. Translation Key Coverage
+For every `t:settings_schema.*` reference in `schema.json` (labels, content, display_name, info, placeholder):
+- Extract the key path (e.g. `t:settings_schema.theme.settings.primary_color.label` → `settings_schema.theme.settings.primary_color.label`).
+- Verify that key exists in `en.schema.json`.
+- Flag any `t:` key referenced in schema but missing from i18n.
+
+### 5. i18n Orphans (optional, warnings only)
+For every key under `settings_schema` in `en.schema.json`:
+- Check if it is referenced by any `t:` path in `schema.json`.
+- Keys not referenced → flag as **orphan i18n key** (warning, not error).
+
+### 6. Liquid Consumer Check
+Read `snippets/theme-settings.liquid` and any layout files that reference `settings.*`:
+- For every `settings.<id>` or `settings.<id>.value` reference in Liquid:
+  - Verify `<id>` exists in `schema.json`.
+  - If the schema type is `select` and Liquid reads `settings.<id>.value`, that is correct.
+  - If the schema type is `select` and Liquid reads `settings.<id>` without `.value`, flag as potential bug (will get the whole object, not the string value).
+
+### 7. Meta Field Presence
+Every group in `schema.json` should have a `meta` field set to either `"global_settings"` or `"component_settings"`.
+- Missing `meta` → flag as warning.
+
+---
+
+## Output
+
+```
+VALIDATE THEME SETTINGS — <theme_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SCHEMA ↔ PRESETS     ✅ / ❌
+VALUE TYPES          ✅ / ❌
+SELECT CONVENTION    ✅ / ❌
+TRANSLATION KEYS     ✅ / ❌
+I18N ORPHANS         ✅ / ⚠️
+LIQUID CONSUMERS     ✅ / ⚠️
+META FIELDS          ✅ / ⚠️
+
+ISSUES:
+  ❌ [check] <id>: description (file:line if applicable)
+  ⚠️ [check] <id>: description
+
+SUMMARY
+  Schema fields: <n>
+  Preset keys (Default): <n>
+  i18n keys under settings_schema: <n>
+  Errors: <n>  |  Warnings: <n>
+
+RESULT: PASS / FAIL
+```
+
+Auto-fix unambiguous issues (e.g. `label` → `display_name` in a select) if safe.
+Flag anything requiring judgment.
+
+---
+
+## Notes
+
+- This command does NOT modify schema structure or add new fields — use `/add-theme-setting` for that.
+- Run this after any manual edit to `schema.json` or `theme.json` to catch drift.
+- Pair with `/qa-i18n` for deeper translation key analysis across sections too.

package/ts-dist/mocks/init-theme/.cursor/examples/design-instructions-template.md

@@ -0,0 +1,151 @@
+# Design Instructions Template
+
+Use this file as an optional argument to `/build-theme` or `/build-section` to provide detailed build instructions that supplement or override the Figma extraction.
+
+Pass it as the last argument:
+```
+/build-theme <theme_name> <figma_file_key> design-instructions.md
+/build-section <theme_name> <section_name> [figma_url] design-instructions.md
+```
+
+---
+
+## Frame Mapping
+
+Maps Figma frames to section file names and their order in the page JSON.
+
+| Figma Frame | Section File | Page | Order |
+|-------------|-------------|------|-------|
+| Hero Banner | `hero-banner` | index.json | 1 |
+| Product Features | `product-features` | index.json | 2 |
+| Testimonials | `testimonials-carousel` | index.json | 3 |
+| FAQ Accordion | `faq-accordion` | index.json | 4 |
+| Newsletter Signup | `newsletter-cta` | index.json | 5 |
+
+---
+
+## Image Placeholders
+
+Maps Figma image layers to ZCommerce Liquid objects or schema settings.
+
+| Figma Layer | Schema Type | Liquid Source | Fallback |
+|-------------|-------------|--------------|----------|
+| Hero Background | `image_picker` | `section.settings.hero_image` | Placeholder gradient via CSS |
+| Product Photo | product object | `product.images[0].url` | `{{ 'placeholder.webp' | asset_url }}` |
+| Testimonial Avatar | `image_picker` (block) | `block.settings.avatar` | Initials circle via CSS |
+
+**Schema syntax reminder** — image_picker defaults use ZCommerce format:
+```json
+{ "url": "placeholder.webp", "enable_customisation": true }
+```
+
+---
+
+## Animations & Transitions
+
+CSS animations and scroll-triggered effects.
+
+| Element | Trigger | Animation | Duration | Easing |
+|---------|---------|-----------|----------|--------|
+| `.hero-banner__heading` | Page load | `fadeInUp` | `0.8s` | `ease-out` |
+| `.product-features__card` | Scroll into view | `fadeInUp` | `0.6s` | `ease-out` |
+| `.testimonials__item` | Scroll into view | `fadeIn` | `0.5s` | `ease` |
+
+```css
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+```
+
+**Implementation notes:**
+- Use `IntersectionObserver` in a Web Component for scroll-triggered animations
+- Always respect `prefers-reduced-motion: reduce`
+- Use `<script defer>` — no external JS libraries
+
+---
+
+## Hover States
+
+Interactive CSS transitions on hover.
+
+| Element | Property | Default | Hover | Transition |
+|---------|----------|---------|-------|------------|
+| `.product-card` | `transform` | `none` | `translateY(-4px)` | `0.3s ease` |
+| `.product-card` | `box-shadow` | `none` | `0 8px 24px rgba(0,0,0,0.1)` | `0.3s ease` |
+| `.cta-button` | `background-color` | `var(--color-primary)` | Darken 10% | `0.2s ease` |
+| `.testimonials__dot` | `opacity` | `0.5` | `1` | `0.2s ease` |
+
+---
+
+## Component Overrides
+
+Override specific design decisions per section that differ from the Figma extraction or reference theme.
+
+| Section | Setting | Override Value | Notes |
+|---------|---------|---------------|-------|
+| `hero-banner` | Container | Full-bleed (no `max-w-container-theme`) | Image behind text, edge-to-edge |
+| `product-features` | Grid columns | 3 on desktop, 1 on mobile | Figma shows 4 but client prefers 3 |
+| `faq-accordion` | Behavior | Single-open | Only one accordion item open at a time |
+
+---
+
+## Custom CSS Variables
+
+Additional CSS custom properties beyond the standard theme tokens. Define these in the `{% style %}` block of the relevant section.
+
+| Variable | Value | Used By |
+|----------|-------|---------|
+| `--hero-overlay-opacity` | `0.4` | hero-banner |
+| `--card-hover-shadow` | `0 8px 24px rgba(0,0,0,0.1)` | product-features |
+| `--accordion-border-color` | `var(--color-border)` | faq-accordion |
+
+---
+
+## Schema Field Overrides
+
+Force specific schema field types or defaults that differ from what Figma extraction would produce.
+
+| Section | Field ID | Type | Default | Notes |
+|---------|---------|------|---------|-------|
+| `hero-banner` | `overlay_opacity` | `range` | `40` (min:0, max:100, step:5) | Controls image overlay darkness |
+| `product-features` | `columns_desktop` | `select` | `{ "display_name": "t:...", "value": "3" }` | Options: 2, 3, 4 |
+| `newsletter-cta` | `bg_style` | `select` | `{ "display_name": "t:...", "value": "gradient" }` | Options: solid, gradient, image |
+
+---
+
+## Custom Instructions
+
+Free-form build notes that the agent must follow. These take highest priority.
+
+- The hero section should use a full-bleed layout with the image behind the text overlay
+- Product feature cards should be in a 3-column grid on desktop, stacking vertically on mobile
+- The FAQ accordion should only allow one item open at a time (use a Web Component with `data-single-open`)
+- The newsletter section should have a subtle background pattern using a CSS gradient
+- All section transitions should respect `prefers-reduced-motion`
+- Use `{% render 'icon-chevron' %}` for accordion arrows — do NOT inline SVGs
+- All prices must use the `| money` filter
+- Product cards must match the existing `{% render 'product-card' %}` snippet interface — do NOT create a new card layout
+
+---
+
+## i18n Overrides
+
+Force specific translation key values instead of auto-generated ones.
+
+| Key | Value | Notes |
+|-----|-------|-------|
+| `t:sections.hero_banner.settings.heading.default` | `Discover Our Collection` | Marketing-approved copy |
+| `t:sections.newsletter_cta.settings.heading.default` | `Stay in the Loop` | — |
+| `t:sections.faq_accordion.settings.heading.default` | `Frequently Asked Questions` | — |

package/ts-dist/mocks/init-theme/.cursor/mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "chrome-devtools-mcp@latest",
+        "--viewport=1440x900",
+        "--isolated",
+        "--experimentalPageIdRouting",
+        "--no-usage-statistics"
+      ],
+      "env": {
+        "CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS": "1"
+      }
+    }
+  }
+}