@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.cursor/rules/qa-section.mdc

@@ -0,0 +1,134 @@
+---
+
+description: Audit a built section for schema correctness, token compliance, and empty states
+alwaysApply: false
+---
+
+
+# /qa-section
+
+Audit a completed section file against all rules.
+Run this after /build-section before moving to the next section.
+
+## Usage
+```
+/qa-section <theme_name> <section_name>
+```
+
+---
+
+
+## Pre-flight — Files to Read Automatically
+
+Before running any checks, read ALL of these without being asked:
+
+1. `sections/<section_name>.liquid` — the section file
+2. Every snippet referenced via `{% render 'snippet-name' %}` inside the section
+   - Read `snippets/<snippet-name>.liquid` for each one
+   - Repeat recursively — if a snippet renders another snippet, read that too
+3. `figma-variables.json` — to verify token usage and resolve Figma MCP variables when applicable
+
+Never ask the developer to paste file contents — read them directly from the workspace.
+Apply all checks below to the section file AND every snippet found.
+When reporting issues, always prefix with the filename:
+  `[hero-banner.liquid line 23]` or `[product-card.liquid line 8]`
+
+---
+
+
+## Checks
+
+### Schema Checks
+- [ ] Every `section.settings.X` referenced in Liquid has a matching field in `{% schema %}`
+- [ ] Every schema field uses correct custom syntax (not standard Shopify)
+  - url → `{ "display_name": "t:...", "handle": "..." }` not `"/path"`
+  - image_picker → `{ "url": "...", "enable_customisation": true }` not `"/image.jpg"`
+  - media_picker (video) → `{ "url": "video.mp4", "is_video": true }`
+  - select default → `{ "display_name": "t:...", "value": "..." }` not `"value"`
+  - menu → `{ "display_name": "t:...", "handle": "..." }`
+- [ ] All labels use `t:` translation keys — no hardcoded English strings
+- [ ] All defaults use `t:` translation keys where applicable
+- [ ] Schema has `padding_top` and `padding_bottom` range settings
+- [ ] Schema has at least one entry in `"presets": []`
+- [ ] If blocks are used: `"block_order"` exists and matches block keys
+- [ ] Local blocks: `type` is bare name; settings schema inline in section `{% schema %}`
+- [ ] Theme blocks: `type` is `zc_theme__<name>`; section schema opts in via `@theme` or specific entry; `blocks/<name>.liquid` exists with `"presets"`
+- [ ] Theme-block sections render with `{% render_blocks %}` or mixed sections delegate via `{% render block %}`
+- [ ] Heading/title fields and heading blocks use `text` — not `richtext`
+- [ ] Body/description fields use `richtext` where multi-line formatting is needed; rendered with `| raw`
+
+### Liquid Checks
+- [ ] All loops have empty state `{% else %}` or `{% if size > 0 %}` guard
+- [ ] All user output is escaped: `{{ value | escape }}`
+- [ ] Uses `{% render %}` not `{% include %}`
+- [ ] Dynamic values are assigned via `{% liquid assign %}` block at top
+- [ ] Section is wrapped with `id="section-{{ section.id }}"`
+
+### CSS / Token Checks
+- [ ] No raw hex color values in inline styles → must use `var(--color-*)`
+- [ ] No raw px font-size in inline styles → must use Tailwind text classes
+- [ ] Spacing uses Tailwind classes not inline px (except via `{% style %}` block)
+- [ ] `{% style %}` block scopes rules to `#section-{{ section.id }}`
+- [ ] **Tailwind vs style block:** Static values in `{% style %}` (fixed px, gap, font-size, border-radius, padding, margin, line-height) should be implemented as Tailwind classes on the elements. Use `{% style %}` only for: (1) **dynamic** values from section/block settings (e.g. `{{ section.settings.padding_top }}px`, `{{ section_settings.gap }}px`), (2) CSS custom properties / theme variables, (3) **state or complex selectors** that require `#section-{{ section.id }}` (e.g. `.open`, `[aria-pressed="true"]`, `.productimage.active`). If the section has many static rules in the style block, report **TAILWIND / STYLE ⚠️ REVIEW** and add to "Remaining issues": *"Static styles in {% style %} — consider refactoring to Tailwind (run /refactor-section &lt;theme_name&gt; &lt;section_name&gt; or move rules to Tailwind classes; keep in style block only dynamic schema values and state selectors)."*
+
+### Image Checks
+- [ ] All `<img>` tags have: `src`, `alt`, `width`, `height`, `loading` attributes
+- [ ] Above-the-fold images use `loading="eager"`, all others `loading="lazy"`
+- [ ] Image src uses `{{ section.settings.field.url }}` not `| img_url`
+
+### Accessibility Checks
+- [ ] All `<img>` have non-empty, meaningful `alt`
+- [ ] Heading order: no skipped levels (e.g. h1 → h3)
+- [ ] Form controls: `<label>` or `aria-label` / `aria-labelledby`; groups use `fieldset`/`legend` or `role="group"` + `aria-labelledby`
+- [ ] No `outline: none` without visible focus style on interactive elements
+- [ ] Icon-only buttons/links have descriptive `aria-label`
+
+### Performance Checks
+- [ ] Above-the-fold images: `loading="eager"`, width/height to avoid layout shift
+- [ ] Other images: `loading="lazy"`, width/height; flag very large dimensions vs display size
+
+### HTML Validity Checks
+- [ ] No nested `<form>` elements — if a section wraps content in a `<form>`, verify that no rendered snippets (e.g. product-card, add-to-cart) also output `<form>` tags inside it. Browsers silently drop inner `<form>` tags, breaking JS that queries by form class/ID. Fix: close the outer `<form>` before the region that renders inner forms, or convert inner forms to `<div>` with JS-only submission.
+- [ ] No `<a>` nested inside `<a>` — interactive elements must not be nested
+- [ ] No block elements (`<div>`, `<p>`, `<form>`) inside inline elements (`<span>`, `<a>` in inline context)
+- [ ] All opened tags are closed; verify structural balance of conditional blocks (`{% if %}...{% endif %}`) that emit opening/closing tags
+
+### JS Checks
+- [ ] If a JS component is used, script tag exists with `defer`
+- [ ] Script uses `{{ 'filename.js' | asset_url }}`
+
+---
+
+
+## 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
+HTML VALIDITY    ✅ PASS / ❌ FAIL
+JS               ✅ PASS / N/A
+
+ISSUES FOUND:
+❌ [line X] section.settings.cta_url rendered as .handle but schema uses type "text" — should be type "url"
+❌ [line X] Hardcoded color #1a1a1a found — replace with var(--color-heading)
+⚠️ [line X] Loop has no empty state fallback
+
+AUTO-FIXING issues that are unambiguous...
+[list of fixes applied]
+
+Remaining issues require manual review:
+[list of issues that need human decision]
+```
+
+**TAILWIND / STYLE:** Mark **✅ PASS** when most styling is in Tailwind and `{% style %}` contains only dynamic schema values and state/selector rules. Mark **⚠️ REVIEW** when `{% style %}` contains many static rules (fixed px, gap, font-size, border-radius, padding, margin, line-height) that could be Tailwind classes; then add to "Remaining issues" the recommendation to refactor (run `/refactor-section <theme_name> <section_name>` with instruction "use Tailwind classes for static styles", or move static rules to Tailwind; keep in style block only dynamic values and state selectors).
+
+Auto-fix unambiguous issues directly in the file.
+Flag anything that requires a judgment call for the developer to resolve.

package/ts-dist/mocks/init-theme/.cursor/rules/redesign-section.mdc

@@ -0,0 +1,147 @@
+---
+
+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>
+```
+Provide the updated Figma frame via MCP or screenshot.
+
+---
+
+
+## Pre-flight
+1. Open `sections/<section_name>.liquid`
+2. Open all related snippets referenced via `{% render %}` in this section
+3. Confirm Figma frame is available
+4. Check `figma-variables.json` exists
+   - If missing → STOP, tell user to run `/extract-tokens` or add the designer-exported file first
+5. **When using Figma MCP:** resolve every `var(--name, fallback)` via `figma-variables.json` first (path by `/`; use `$value` if present, else fallback). See `.cursor/rules/figma-mcp-resolution.mdc`.
+
+---
+
+
+## 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 — Read Figma Frame
+Extract ONLY visual/layout information. **Resolve all var() from Figma MCP using figma-variables.json first** (see figma-mcp-resolution.mdc): look up variable name path in `figma-variables.json`; use `$value` if present, else MCP fallback.
+
+### Use
+- Layout direction (row / column / grid)
+- Number of columns, grid gaps
+- Element hierarchy and nesting
+- Typography → resolve from JSON then map via figma-variables.json / Tailwind
+- Colors → resolve from JSON then map to CSS variables
+- Spacing → resolve from JSON then map to Tailwind classes
+- Border radius, shadows → resolve from JSON then map via figma-variables.json
+- New visual elements that didn't exist before → flag 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-QA
+After editing, 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-*)
+
+---
+
+
+## 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/rules/schema-sync.mdc

@@ -0,0 +1,110 @@
+---
+description: Every schema setting (section, block, or theme) must be reflected as a default value in the corresponding JSON file.
+alwaysApply: true
+---
+
+# Schema Sync — Settings Must Match JSON Defaults
+
+Any time a setting is added or changed in a schema, the corresponding JSON file **must** be updated in the same step. There are three layers, each with its own target file.
+
+---
+
+## 1. Section settings → `pages/*.json`
+
+Settings defined directly on a section must appear under `"settings"` for that section entry in the page JSON.
+
+```json
+// ✅ pages/blog.json
+"blog_page": {
+  "type": "blog-page",
+  "settings": {
+    "title_font_size_mobile": { "display_name": "Medium", "value": "md" },
+    "title_font_size_desktop": { "display_name": "Medium", "value": "md" }
+  }
+}
+```
+
+---
+
+## 2. Block settings → `pages/*.json` (under the block)
+
+Block settings in page JSON appear under `"blocks"` → the block key → `"settings"`. The schema source depends on the block model:
+
+| Block model | Schema lives in | Page JSON `type` |
+|-------------|----------------|------------------|
+| **Local** | Section `{% schema %}` | bare name, e.g. `"product-title"` |
+| **Theme** | `blocks/<name>.liquid` | `zc_theme__<name>`, e.g. `"zc_theme__text"` |
+
+```json
+// ✅ Local block — pages/product.json
+"main": {
+  "type": "product-details",
+  "blocks": {
+    "product-title": {
+      "type": "product-title",
+      "settings": {
+        "title_font_size_mobile": { "display_name": "Medium", "value": "md" },
+        "title_font_size_desktop": { "display_name": "Medium", "value": "md" }
+      }
+    }
+  },
+  "block_order": ["product-title"]
+}
+```
+
+```json
+// ✅ Theme block — pages/index.json
+"hero": {
+  "type": "shop-now-banner",
+  "blocks": {
+    "hero-heading": {
+      "type": "zc_theme__text",
+      "settings": {
+        "text": "<p>Welcome</p>",
+        "desktop_text_size": { "display_name": "Large", "value": "text-4xl" }
+      }
+    }
+  },
+  "block_order": ["hero-heading"]
+}
+```
+
+Nested theme blocks: child block settings sync under the parent block instance's `"blocks"` → child key → `"settings"`, matching the parent block file's `{% schema %}`.
+
+When adding a setting to a **theme block**, update `blocks/<name>.liquid` schema **and** any page JSON / section preset that instantiates that block type.
+
+---
+
+## 3. Theme settings → `settings/theme.json`
+
+Settings defined in `settings/schema.json` (global theme settings) must have a matching key inside `presets.Default` in `settings/theme.json`.
+
+- `select` → `{ "value": "...", "display_name": "..." }`
+- `color` → hex string e.g. `"#FFFFFF"`
+- `range` → number e.g. `0`
+
+```json
+// ✅ settings/theme.json
+{
+  "presets": {
+    "Default": {
+      "primary_font_family": { "value": "Poppins", "display_name": "Poppins" },
+      "background_color": "#FFFFFF",
+      "page_width": 1496
+    }
+  }
+}
+```
+
+---
+
+## Value format reference
+
+| Setting type | Format in JSON |
+|---|---|
+| `select` | `{ "display_name": "Label", "value": "raw-value" }` |
+| `color` | `"#RRGGBB"` |
+| `range` | number |
+| `text` / `richtext` | plain string |
+| `checkbox` | `true` / `false` |
+| `blog` / `url` | `{ "display_name": "", "handle": "" }` |