@zohofinance/commerce 1.0.0 → 1.1.0

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

@@ -0,0 +1,84 @@
+---
+description: Audit a built section for schema correctness, token compliance, and empty states
+alwaysApply: false
+---
+
+# /qa-section
+
+Audit a completed section. Run after every /build-section or /redesign-section.
+
+## Usage
+```
+/qa-section <theme_name> <section_name>
+```
+
+---
+
+## Checks
+
+### Schema
+- [ ] Every `section.settings.X` in Liquid has matching schema field
+- [ ] url default → `{ "display_name": "t:...", "handle": "..." }` not `"/path"`
+- [ ] image_picker default → `{ "url": "...", "enable_customisation": true }`
+- [ ] select default → `{ "display_name": "t:...", "value": "..." }` not `"value"`
+- [ ] menu default → `{ "display_name": "t:...", "handle": "..." }`
+- [ ] All labels use `t:` keys — no hardcoded English
+- [ ] padding_top and padding_bottom settings present
+- [ ] At least one preset in `"presets": []`
+- [ ] Heading/title fields and heading blocks use `text` — not `richtext`
+- [ ] Body/description fields use `richtext` where needed; rendered with `| raw`
+
+### Liquid
+- [ ] All loops have empty state `{% else %}` or `{% if size > 0 %}` guard
+- [ ] All user output escaped: `{{ value | escape }}`
+- [ ] Uses `{% render %}` not `{% include %}`
+- [ ] Assigns in `{% liquid %}` block at top
+
+### CSS / Tokens
+- [ ] No raw hex in inline styles → must use `var(--color-*)`
+- [ ] No raw px font-size → must use Tailwind text classes
+- [ ] `{% style %}` scoped to `#section-{{ section.id }}`
+- [ ] **Tailwind vs style block:** Static values (fixed px, gap, font-size, border-radius, padding, margin) in `{% style %}` should be Tailwind classes on elements. Keep in `{% style %}` only: (1) dynamic schema values (e.g. `{{ section.settings.X }}px`), (2) CSS custom properties / theme variables, (3) state or selectors that need `#section-{{ section.id }}` (e.g. `.open`, `[aria-pressed="true"]`). If the section has many static rules in the style block, flag them and recommend refactoring (see action below).
+
+### Images
+- [ ] All `<img>` have: src, alt, width, height, loading
+- [ ] Above-fold: `loading="eager"`, all others: `loading="lazy"`
+- [ ] src uses `{{ field.url }}` not `| img_url`
+
+### Accessibility
+- [ ] All `<img>` have non-empty, meaningful `alt`
+- [ ] Heading order: no skipped levels (e.g. h1 → h3)
+- [ ] Form controls: associated `<label>` or `aria-label` / `aria-labelledby`; groups use `fieldset`/`legend` or `role="group"` + `aria-labelledby`
+- [ ] No `outline: none` without a visible focus style on interactive elements
+- [ ] Icon-only buttons/links have descriptive `aria-label`
+
+### Performance
+- [ ] Above-the-fold images use `loading="eager"` and have width/height to avoid layout shift
+- [ ] Other images use `loading="lazy"` and have width/height
+- [ ] Flag very large image dimensions vs likely display size (suggest responsive/sizes if needed)
+
+---
+
+## Output Format
+```
+QA REPORT — <section_name>.liquid
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SCHEMA           ✅ PASS / ❌ FAIL
+LIQUID           ✅ PASS / ❌ FAIL
+CSS TOKENS       ✅ PASS / ❌ FAIL
+TAILWIND / STYLE ✅ PASS / ⚠️ REVIEW
+IMAGES           ✅ PASS / ❌ FAIL
+ACCESSIBILITY    ✅ PASS / ⚠️ REVIEW / ❌ FAIL
+PERFORMANCE      ✅ PASS / ⚠️ REVIEW / N/A
+
+ISSUES:
+❌ [line X] description of issue → fix applied / needs your decision
+
+AUTO-FIXED: [list]
+NEEDS YOUR DECISION: [list]
+```
+
+**TAILWIND / STYLE:** Pass when static styling is in Tailwind classes; Review when `{% style %}` contains many static rules (fixed px, gap, font-size, etc.) that could be Tailwind. In that case, add to NEEDS YOUR DECISION: *"Static styles in {% style %} — consider refactoring to Tailwind (run `/refactor-section <theme_name> <section_name>` with instruction 'use Tailwind classes for static styles', or move rules to Tailwind; keep in style block only dynamic schema values and state selectors)."*
+
+Auto-fix unambiguous issues directly in the file.
+Flag anything requiring a judgment call.

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

@@ -0,0 +1,48 @@
+---
+description: QA every section in a theme (batch)
+alwaysApply: false
+---
+
+# /qa-sections
+
+Run the same checks as `/qa-section` on **every section** in a theme. Use before release or after a large refactor.
+
+## Usage
+```
+/qa-sections <theme_name>
+```
+
+---
+
+## Pre-flight
+
+1. List all `.liquid` files in `sections/` (exclude `.json` group files if present).
+2. For each section file (e.g. `product-details.liquid`), run the full qa-section logic: read section + all snippets it renders, then run Schema, Liquid, CSS/Token, Tailwind/Style, Images, Accessibility, Performance, JS checks.
+
+---
+
+## Output
+
+Produce one report per section, then a **summary**:
+
+```
+QA BATCH — <theme_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+<section_1>.liquid    SCHEMA ✅  LIQUID ✅  CSS ✅  TAILWIND ⚠️  IMAGES ✅  A11Y ✅  PERF ✅
+<section_2>.liquid    SCHEMA ✅  LIQUID ❌  CSS ✅  TAILWIND ✅   IMAGES ✅  A11Y ✅  PERF N/A
+...
+
+SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Sections: <n>
+PASS (all rows ✅): <m>
+REVIEW (at least one ⚠️): <k>
+FAIL (at least one ❌): <j>
+
+ISSUES BY SECTION:
+<section_2>.liquid: [list of failures]
+...
+```
+
+Optionally list only sections with at least one ❌ or ⚠️ to keep the report scannable. Suggest running `/qa-section <theme_name> <section_name>` on any failed or review sections for full detail.

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

@@ -0,0 +1,85 @@
+---
+description: Run all QA and validation commands for an entire theme in one shot
+alwaysApply: false
+---
+
+# /qa-theme
+
+Orchestrator command that runs every QA and validation check available for a theme. Use before release, after a large refactor, or when onboarding a new theme.
+
+## Usage
+```
+/qa-theme <theme_name>
+```
+
+---
+
+## Execution Order
+
+Run these checks in sequence. Each produces its own report; this command collates them into a single consolidated summary.
+
+### 1. Sections — `/qa-sections <theme_name>`
+QA every `.liquid` section file: schema, Liquid, CSS/tokens, Tailwind, images, accessibility, performance.
+
+### 2. Theme Settings — `/validate-theme-settings <theme_name>`
+Cross-check `settings/schema.json` vs `settings/theme.json` vs `i18n/en.schema.json` vs Liquid consumers.
+
+### 3. Layouts — `/qa-layout <theme_name>`
+Audit all layout files: HTML structure, asset loading, section group refs, snippet refs, layout parity.
+
+### 4. Section Groups
+List all `*-group.json` files in `sections/`.
+For each, run `/validate-section-group <theme_name> <group_name>`.
+
+### 5. Pages
+List all `.json` files in `pages/`.
+For each, run `/validate-page <theme_name> <page_name>`.
+
+### 6. Translation Keys — `/qa-i18n <theme_name>`
+Audit `t:` key coverage: missing keys, orphans, hardcoded English.
+
+---
+
+## Consolidated Report
+
+```
+QA THEME — <theme_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+MODULE                   STATUS    ERRORS  WARNINGS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Sections (<n> files)     PASS/FAIL   <n>     <n>
+Theme Settings           PASS/FAIL   <n>     <n>
+Layouts (<n> files)      PASS/FAIL   <n>     <n>
+Section Groups (<n>)     PASS/FAIL   <n>     <n>
+Pages (<n> files)        PASS/FAIL   <n>     <n>
+Translation Keys         PASS/FAIL   <n>     <n>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+OVERALL: PASS / FAIL
+
+TOTAL ERRORS:   <n>
+TOTAL WARNINGS: <n>
+
+TOP ISSUES (errors first, then warnings):
+  1. ❌ [module] description
+  2. ❌ [module] description
+  3. ⚠️ [module] description
+  ...
+
+RECOMMENDED NEXT STEPS:
+  - Fix ❌ errors before shipping
+  - Review ⚠️ warnings — fix or document as intentional
+  - For section issues: /fix-section <theme_name> <section_name>
+  - For settings issues: /add-theme-setting or manual edit
+  - For i18n issues: edit en.schema.json directly
+```
+
+---
+
+## Notes
+
+- This command is read-only — it reports issues but does not auto-fix anything. Individual sub-commands (like `/qa-section`) may auto-fix within their own scope.
+- For large themes (40+ sections), this may take several minutes. Each sub-command's progress is logged as it completes.
+- If any sub-command fails to run (e.g. missing file), log the failure and continue with the remaining checks.
+- After fixing issues, re-run `/qa-theme` to verify everything passes.

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

@@ -0,0 +1,177 @@
+---
+
+description: Redesign an existing section from new Figma — preserve all logic, replace only HTML/CSS
+alwaysApply: false
+---
+
+
+# /redesign-section
+
+Redesign an existing section using a new Figma frame.
+ONLY HTML structure and CSS classes change.
+Schema, Liquid logic, assigns, loops, and snippet calls are NEVER touched.
+
+## Usage
+```
+/redesign-section <theme_name> <section_name>
+```
+
+---
+
+
+## Pre-flight
+1. Open `sections/<section_name>.liquid`
+2. Open all related snippets referenced via `{% render %}` in this section
+3. Open `figma-variables.json` — token values for this theme
+4. Read Figma frame from active Cursor MCP selection — see below
+
+## Figma Frame — via Cursor Figma MCP
+
+Cursor reads the Figma frame from whatever is currently selected in the Figma app
+via the Figma Dev Mode MCP plugin. The developer selects the redesigned frame in
+Figma first, then runs this command in Cursor.
+
+
+If no Figma MCP context is present in the conversation:
+```
+⚠️ No Figma frame data found.
+Please:
+  1. Open your Figma file in the browser
+  2. Click on the new <section_name> frame
+  3. Re-run this command in Cursor
+```
+
+---
+
+
+## Stage 1 — Snapshot What Must NOT Change
+Before touching anything, extract and list:
+
+```
+LOCKED (do not modify):
+- Schema: all field IDs, types, defaults, labels
+- {% liquid %} assign block: all variable names
+- All {% if %} / {% unless %} / {% case %} logic
+- All {% for %} loops and their variable names
+- All {% render 'snippet-name' %} calls
+- All JS web component tag names (e.g. <app-header>)
+- {% style %} block dynamic values
+- Script tags and asset references
+```
+
+Print this list before proceeding. This is your protection layer.
+
+---
+
+
+## Stage 2 — Extract Detailed Design Spec from Figma
+
+**Follow the Design Spec Extraction Protocol** in `.cursor/rules/design-spec-extraction.mdc`.
+
+### 2a. Resolve ALL var() values first
+For every `var(--name, fallback)` in the Figma MCP data:
+- Look up in `figma-variables.json` by path → use `$value` if present, fallback otherwise
+- If neither → STOP and flag as unresolved
+
+### 2b. Extract EXACT values for EVERY visible element
+Per TEXT: font-size (px → Tailwind), font-weight, line-height, letter-spacing, color (hex → CSS var), text-align
+Per CONTAINER: layout, columns, gap (px → Tailwind), padding, margin, alignment, background (hex → CSS var)
+Per IMAGE: width, height, aspect-ratio, object-fit, border-radius (px → Tailwind)
+Per BUTTON: padding, font-size, font-weight, background, text-color, border, border-radius
+Per CARD: padding, background, border, border-radius, shadow, internal layout, children
+
+### 2c. Extract responsive differences (if mobile frame available)
+
+### 2d. Produce the Design Spec Table
+Every row = one element+property with exact Tailwind/CSS value.
+Flag any NEW visual elements that don't exist in the current section as ADDITIONS.
+
+### Ignore
+- Hidden layers
+- Hover/focus/active states
+- Absolute positions from auto-layout
+- Placeholder text
+
+---
+
+
+## Stage 3 — Identify What Changes
+Produce a change plan before editing:
+
+```
+REDESIGN CHANGE PLAN — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+REMOVING:
+- Old 2-column grid layout → replacing with 3-column
+- Old heading class text-2xl → replacing with text-4xl font-bold
+- Old card padding p-4 → replacing with p-6
+
+KEEPING (unchanged):
+- {% for product in products %} loop
+- {% render 'product-card' %} call
+- All schema fields
+- {% style %} padding block
+
+ADDING (new visual elements from Figma):
+- Badge element above heading (new HTML only, no new schema field)
+- Decorative divider between heading and grid
+
+SCHEMA CHANGES: none
+```
+
+Show this plan and ask: "Proceed with redesign?" before editing.
+
+---
+
+
+## Stage 4 — Apply Changes
+Edit the file, replacing ONLY HTML wrapper elements and Tailwind classes.
+
+Rules:
+- Keep every Liquid tag exactly as-is — only wrap or restructure HTML around them
+- Replace Tailwind classes using token map — never raw px or hex
+- Colors → always `var(--color-*)` 
+- If a new visual element needs dynamic content → note it as:
+  `⚠️ New element found in Figma: needs schema field — run /add-field after redesign`
+- Do NOT add schema fields during a redesign — keep scope clean
+
+---
+
+
+## Stage 5 — Self-Compare Against Design Spec + QA
+
+### 5a. Self-compare against the Design Spec Table from Stage 2d
+For EVERY row in the spec table:
+1. Find the corresponding HTML element in the edited code
+2. Verify the Tailwind class / CSS variable matches EXACTLY
+3. If mismatch → fix immediately
+
+### 5b. Verify the locked list from Stage 1:
+- [ ] All schema field IDs still present and unchanged
+- [ ] All assign variable names unchanged
+- [ ] All loops intact with empty state handling
+- [ ] All {% render %} calls unchanged
+- [ ] No raw hex or px values introduced
+- [ ] No inline styles added except via var(--color-*)
+- [ ] Responsive classes present for all mobile overrides in spec
+
+---
+
+
+## Output
+```
+✅ Redesign complete: sections/<section_name>.liquid
+
+CHANGED:
+- [list of HTML/class changes]
+
+UNCHANGED (verified):
+- Schema: ✅
+- Liquid logic: ✅  
+- Snippet calls: ✅
+
+⚠️ NEW ELEMENTS FOUND IN FIGMA (need schema fields):
+- Badge text above heading → run /add-field <theme_name> <section_name> after review
+
+NEXT: Run /qa-section <theme_name> <section_name> to verify output
+```

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

@@ -0,0 +1,185 @@
+---
+description: Refactor an existing section — structural HTML changes, schema updates, Tailwind classes, all in one pass
+alwaysApply: false
+---
+
+# /refactor-section
+
+Full refactor of an existing section. Handles structural HTML changes, schema
+additions/removals/renames/type changes, and Tailwind class updates in one pass.
+Liquid logic and assigns are preserved unless a field rename directly requires updating them.
+
+## Usage
+```
+/refactor-section <theme_name> <section_name>
+```
+
+Provide instructions as plain text, a Figma frame via MCP, or both.
+
+---
+
+## Pre-flight — Read Everything First
+
+Before making any changes, read ALL of these:
+
+1. `sections/<section_name>.liquid`
+2. Every snippet referenced via `{% render %}` — recursively
+3. `pages/*.json` — find any page JSON that references this section
+4. `figma-variables.json` — token values
+5. Figma MCP frame if available — read from active Cursor selection
+
+---
+
+## Stage 1 — Build Change List
+
+From the developer's instructions and/or Figma frame, build a precise change list
+before touching anything. Categorise every change:
+
+```
+REFACTOR PLAN — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SCHEMA CHANGES:
+  ADD:
+    - id: "subtitle", type: text, default: ""
+    - id: "show_divider", type: checkbox, default: false
+  REMOVE:
+    - id: "description" (currently used in HTML at line 24 — will be removed)
+  RENAME:
+    - id: "btn_text" → "cta_text" (update all Liquid references)
+  TYPE CHANGE:
+    - id: "body_text": text → richtext (update output filter: {{ }} → {{ | raw }})
+
+HTML CHANGES:
+  - Wrap heading + subtitle in new <div class="flex flex-col gap-2">
+  - Replace 2-column grid with 3-column grid (grid-cols-2 → grid-cols-3)
+  - Add new divider element below heading (conditional on show_divider)
+  - Remove description block entirely
+
+TAILWIND CHANGES:
+  - Section padding: px-4 → px-6 (from Figma / instruction)
+  - Heading: text-3xl → text-4xl font-bold
+
+SNIPPETS AFFECTED:
+  - snippets/hero-card.liquid — uses renamed field "btn_text", needs update
+
+PAGE JSON AFFECTED:
+  - pages/index.json — section "hero-banner" has "btn_text" key, needs rename
+
+LIQUID LOGIC PRESERVED:
+  - {% for %} loop unchanged
+  - {% if section.settings.show_cta %} unchanged
+  - All {% render %} calls unchanged
+```
+
+Print this plan, then proceed immediately without waiting for approval.
+
+---
+
+## Stage 2 — Apply Schema Changes
+
+Edit the `{% schema %}` block:
+
+### Adding fields
+Use your platform's custom schema syntax:
+- `text` default → `"t:sections.<section>.settings.<id>.default"`
+- `url` → `{ "display_name": "t:...", "handle": "/path" }`
+- `image_picker` → `{ "url": "file.webp", "enable_customisation": true }`
+- `select` default → `{ "display_name": "t:...", "value": "option-value" }`
+- `range` default → plain number
+- `checkbox` default → plain boolean
+- `color` default → hex string
+
+### Removing fields
+Remove the field object from schema.
+Remove all `{{ section.settings.<id> }}` references from HTML.
+Remove any `assign` statements that reference it.
+Remove from page JSON default values.
+
+### Renaming field IDs
+Update the schema `id` value.
+Find and replace ALL Liquid references:
+- `section.settings.old_id` → `section.settings.new_id`
+- `assign var = section.settings.old_id` → updated
+- Any snippet that receives this as a parameter → updated
+
+### Type changes
+Update schema type.
+Update output syntax if needed:
+- `text` → `richtext`: only for body/description fields — change `{{ val | escape }}` to `{{ val | raw }}`
+- `richtext` → `text`: only for heading/title fields — change `{{ val | raw }}` to `{{ val | escape }}`
+- Do not use `richtext` for heading blocks or fields rendered in `<h1>`–`<h6>`
+- `image_picker` → update src reference: `val.url` stays the same
+
+---
+
+## Stage 3 — Apply HTML + Tailwind Changes
+
+Restructure HTML as instructed or per Figma frame.
+
+Rules:
+- Keep all Liquid tags exactly in place — only move or rewrap HTML around them
+- All spacing/typography values → Tailwind classes from figma-variables.json
+- Colors → always `var(--color-*)`, never raw hex
+- New conditional elements → wrap in `{% if section.settings.<id> %}` using the new field
+
+---
+
+## Stage 4 — Update Affected Files
+
+### Snippets
+For any snippet that uses a renamed or removed field:
+- Update the parameter name passed via `{% render 'snippet', param: value %}`
+- Update the internal reference inside the snippet file
+
+### Page JSON
+For any page JSON that references this section:
+- Rename keys that match renamed field IDs
+- Remove keys for removed fields
+- Add keys with default values for new fields
+
+---
+
+## Stage 5 — Self-QA
+
+Before reporting done, verify:
+- [ ] All new schema fields have correct custom syntax
+- [ ] All removed fields have no remaining Liquid references
+- [ ] All renamed fields updated everywhere — section, snippets, page JSON
+- [ ] No raw hex or px values introduced
+- [ ] No inline styles added
+- [ ] All new conditional elements have matching schema fields
+- [ ] i18n keys added for any new field labels (flag if not added)
+
+---
+
+## Output
+
+```
+✅ Refactor complete: <section_name>.liquid
+
+SCHEMA:
+  Added:   subtitle, show_divider
+  Removed: description
+  Renamed: btn_text → cta_text
+  Type changed: body_text text → richtext
+
+HTML/CSS:
+  - 2-col grid → 3-col grid
+  - New subtitle element added
+  - Divider added (conditional on show_divider)
+  - Description block removed
+  - Heading: text-3xl → text-4xl font-bold
+
+FILES CHANGED:
+  - sections/<section_name>.liquid
+  - snippets/hero-card.liquid
+  - pages/index.json
+
+⚠️ NEEDS ATTENTION:
+  - i18n keys needed for new fields: subtitle, show_divider
+    Run /add-field won't help here — add manually to i18n/en.json and en.schema.json
+  - Designer should confirm 3-col layout on mobile
+
+NEXT: Run /qa-section <theme_name> <section_name>
+```