@zohofinance/commerce 1.0.0 → 1.1.0

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

@@ -0,0 +1,178 @@
+---
+
+description: Build a single section for a theme using Figma + reference + token map — with integrated design verification
+alwaysApply: false
+---
+
+
+# /build-section
+
+Build ONE section at a time. Never build multiple sections in a single run.
+This command produces a section that matches the Figma design on the FIRST pass
+by extracting exact values, building to spec, and self-verifying before saving.
+
+## Usage
+```
+/build-section <theme_name> <section_name>
+```
+Provide the Figma frame for this specific section via MCP or screenshot.
+**Request BOTH desktop and mobile frames** for accurate responsive output.
+
+---
+
+
+## Pre-flight Checks
+Before writing any code, verify:
+1. `figma-variables.json` exists
+   - If missing → STOP: ask designer to export Figma variables JSON and place it here
+2. Identify the reference section from the audit plan or by scanning `sections/`
+3. Confirm Figma frame is available (MCP or screenshot)
+4. Read `.cursor/rules/design-spec-extraction.mdc` — the extraction protocol
+
+---
+
+
+## Stage 1 — Read Reference Section
+Open the reference section file from this theme's `sections/` folder.
+Extract and note down:
+- All `{% schema %}` settings (field IDs, types, defaults, labels)
+- All `{% liquid %}` assign statements
+- All conditional logic (`{% if %}`, `{% unless %}`, `{% case %}`)
+- All loops (`{% for %}`)
+- All `{% render %}` calls
+- Any JS component tag names (e.g. `<app-header>`, `<product-card>`)
+- Any `{% style %}` blocks
+
+This logic will be preserved exactly in the new section.
+
+---
+
+
+## Stage 2 — Extract Detailed Design Spec from Figma
+
+**THIS IS THE MOST CRITICAL STAGE. Do not rush it. Do not skip elements.**
+
+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, font-weight, line-height, letter-spacing, color, text-align, max-width
+Per CONTAINER: layout, columns, gap, padding, margin, alignment, background
+Per IMAGE: width, height, aspect-ratio, object-fit, border-radius
+Per BUTTON: padding, font-size, font-weight, background, text-color, border, border-radius
+Per CARD: padding, background, border, border-radius, shadow, internal layout, children
+Section-level: padding-top, padding-bottom, background, container width
+
+### 2c. Extract responsive differences from mobile frame
+Column count, font sizes, gaps, padding, visibility, stack direction.
+
+### 2d. Produce the Design Spec Table
+Every row = one element+property. This table is the BUILD CONTRACT.
+
+```
+#  | Element          | Property        | Desktop Value      | Mobile Override    | Tailwind/CSS
+```
+
+**Print this table before proceeding.** Every row MUST appear in the final code.
+
+---
+
+
+## Stage 3 — Map Figma Values to Tokens
+Read `figma-variables.json`.
+
+For every value in the Design Spec Table:
+- Font size → Tailwind class from token map
+- Color → CSS variable from token map
+- Spacing/gap → Tailwind class from token map
+- Border radius → Tailwind class from token map
+- If NOT in token map → use Tailwind arbitrary value + comment: `{{-- ⚠️ token not mapped: 22px → using text-[22px] --}}`
+
+---
+
+
+## Stage 4 — Build HTML Structure
+Use the Design Spec Table as your blueprint. For each row, apply the exact Tailwind/CSS value.
+
+Rules:
+- Semantic HTML: `<section>`, `<article>`, `<nav>`, `<header>`, `<footer>`, `<ul>/<li>`
+- Layout: Tailwind flexbox or grid — never absolute positioning
+- Colors: only `var(--color-*)` tokens — never raw hex inline
+- Typography: only Tailwind text classes — never inline font-size
+- Spacing: only Tailwind spacing classes from token map
+- Responsive: mobile-first. Base = mobile, `md:` = desktop
+- Dynamic content via Liquid assigns: `{% assign heading = section.settings.heading %}`
+
+**Match the spec table EXACTLY. Do not approximate.**
+
+---
+
+
+## Stage 5 — Add Schema
+Custom syntax from schema.mdc — never Shopify syntax.
+Set padding_top/padding_bottom defaults from the Figma spec (not always 40).
+
+**Heading vs content field types:**
+- Heading/title/eyebrow/badge/button-label fields → `type: "text"` (never `richtext`); render with `{{ field | escape }}`
+- Description/body/paragraph content → `type: "richtext"`; render with `{{ field | raw }}`
+- Heading blocks (`heading`, `title`, etc.) → `text` settings only
+
+**Blocks — choose the right model:**
+- **Repeating content unique to this section** → local block (inline `settings` in section schema)
+- **Reusable across sections** (text, button, image, carousel, accordion) → theme block in `blocks/<name>.liquid`; section schema opts in with `{ "type": "zc_theme__<name>" }`; render with `{% render_blocks %}` or `{% render block %}`
+- **Mixed** → list both in section schema; local types in `{% case %}`, theme types via `{% render block %}`
+
+---
+
+
+## Stage 6 — Add Style Block and Script
+`{% style %}` for dynamic schema values only. Static values go in Tailwind classes.
+
+---
+
+
+## Stage 7 — Self-Compare Against Design Spec (CRITICAL)
+
+For EVERY row in the Design Spec Table:
+1. Find the corresponding HTML element in the generated code
+2. Verify the Tailwind class / CSS variable matches EXACTLY
+3. If mismatch → fix immediately
+
+Produce a self-compare report:
+```
+Spec rows: <n> | Matches: <n> | Auto-fixed: <n> | Unresolvable: <n>
+```
+
+**Fix ALL mismatches before proceeding.**
+
+---
+
+
+## Stage 8 — Code QA Before Saving
+- [ ] Every `section.settings.X` has a matching schema field
+- [ ] No raw hex colors (all use `var(--color-*)`)
+- [ ] No raw px font sizes (all use Tailwind classes)
+- [ ] All loops have empty state handling
+- [ ] All images have width, height, alt, loading
+- [ ] All labels/defaults use `t:` translation keys
+- [ ] Schema has padding_top/padding_bottom with Figma-accurate defaults
+- [ ] Schema has at least one preset
+- [ ] Responsive classes present for all mobile overrides in spec
+- [ ] Heading/title fields use `text`; body/description fields use `richtext` (never `richtext` on heading blocks)
+- [ ] Theme blocks: if used, `blocks/<name>.liquid` exists with `presets`; section schema opts in; page JSON uses `zc_theme__<name>` types
+
+---
+
+
+## Output
+Save to: `sections/<section_name>.liquid`
+
+Report: section path, self-compare results, preserved reference items, new Figma items, unmapped tokens.
+
+## Section File Anatomy — Required Structure (top to bottom)
+
+Script tags → Style block → Liquid assigns → Conditional visibility → Section wrapper → Content → Loops with empty states → Schema (always last)

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

@@ -0,0 +1,47 @@
+---
+description: Autopilot — scaffold, extract tokens, audit pages, build all sections with design verification, assemble pages, and QA an entire theme from a Figma file
+alwaysApply: false
+---
+
+# /build-theme
+
+Full autopilot: takes a Figma file and a theme name and orchestrates every step from scaffold to final QA. Includes integrated design verification — sections are built to match Figma on the first pass.
+
+## Usage
+```
+/build-theme <theme_name> <figma_file_key> [<root_node_id>]
+```
+
+## Agent hierarchy — Level 0 → A → B
+
+See `.claude/skills/theme-from-figma/agent-hierarchy.md`.
+
+| Level | Role | Scope |
+|---|---|---|
+| **0** | Main orchestrator | Discover pages, bootstrap, spawn Level A |
+| **A** | Page orchestrator | Identify sections + node IDs; spawn Level B; assemble page JSON; whole-page visual verify |
+| **B** | Section builder | **One section Figma node only** → `figma-spec.json` → Liquid; lint + section visual verify |
+
+**Anti-hallucination rules** (`transcription-rules.md`):
+- No `rounded-*` unless Figma spec has `border_radius > 0`
+- Colors only from spec → token map (not sibling themes)
+- Product grids: fixed media box `w`×`h` + `object-fit` (prevents uneven card heights)
+
+## Phases
+
+0. **Discover** — `figma-discovery.md`: page map from file key
+1. **Bootstrap** — tokens, `dev-config.json`, developer approves page map
+2. **Stage 1** — Level A per page (`parallel-fanout.md`): index first, then parallel
+   - Level A → Level B per section (parallel within page)
+   - Level B: `section-builder.md` + `figma-extraction.md` + `transcription-rules.md`
+3. **Stage 2** — `verify-theme.mjs`, `build-metrics.md`, consolidation
+
+### Rules
+- Level B MUST call `get_design_context` on **section node ID only** — never parent page
+- Level B PASS = `lint-section.mjs` + `visual-diff.md` with 0 CRITICAL (section crop)
+- Level A MUST NOT write section Liquid — only assemble + whole-page visual verify
+- Both desktop and mobile Figma nodes per section
+- `figma-spec.json` is the contract — zero improvisation
+- Heading blocks and title fields → `text` only; body/description → `richtext`
+
+See `.cursor/commands/build-theme.md` and `.claude/skills/theme-from-figma/SKILL.md`.

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

@@ -0,0 +1,94 @@
+---
+
+description: Compare a built section against its Figma design and report all mismatches by severity
+alwaysApply: false
+---
+
+
+# /compare-section
+
+Compare a built section file against its Figma design source.
+Produces a structured mismatch report grouped by severity.
+Does NOT fix anything — approval required before any changes.
+Always run /qa-section first, then /compare-section, then /fix-section.
+
+## Usage
+```
+/compare-section <theme_name> <section_name>
+/compare-section <theme_name> <section_name> --visual [--page <page_name>] [--store-url <url>]
+```
+
+### Modes
+- **Default (code compare):** Extracts values from code and Figma, compares numerically. Fast, precise.
+- **Visual (`--visual`):** Delegates to the `visual-compare` subagent (`.cursor/agents/visual-compare.md`). Launches dev server, screenshots the rendered section in browser (desktop + mobile), fetches Figma screenshot, and produces a visual diff report. Requires Claude in Chrome + Figma MCP.
+- **Combined (recommended for final QA):** Run both modes sequentially.
+
+Provide design input in one of these forms (best to worst accuracy):
+1. Figma MCP frame data (exact values — preferred)
+2. Figma screenshot + browser screenshot of rendered section
+3. Figma screenshot only
+4. Written description of design intent
+
+---
+
+
+## Pre-flight — Files to Read Automatically
+
+Before comparing, 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
+   - Repeat recursively — if a snippet renders another snippet, read that too
+3. `figma-variables.json` — the token map for this theme
+4. `.cursor/rules/css.mdc` — to reference the Figma → Tailwind conversion table
+5. `.cursor/rules/design-spec-extraction.mdc` — the extraction protocol
+
+Never ask the developer to paste file contents — read them directly.
+
+---
+
+
+## Core Process
+
+### Stage 1 — Extract Code Values
+Extract current values for EVERY element: typography, spacing, layout, visual, images, buttons.
+Produce a structured list (element → property → current value).
+
+### Stage 2 — Extract Figma Values Using Design Spec Extraction Protocol
+Follow `.cursor/rules/design-spec-extraction.mdc`:
+- Resolve ALL var() from `figma-variables.json` first
+- Extract exact values per element
+- Produce the Design Spec Table
+
+### Stage 3 — Compare and Classify
+For every spec row, compare Figma value vs code value.
+Classify mismatches as 🔴 CRITICAL, 🟡 MINOR, or ⚪ SUGGESTION.
+Include a design accuracy percentage (matched / total rows).
+
+### Stage 4 — Check Responsive
+Compare mobile frame differences: columns, fonts, gaps, padding, visibility.
+
+### Stage 5 — Apply Approved Fixes
+Only after developer approval. Reference issue numbers in comments.
+
+---
+
+## Key Rules
+- Follow Design Spec Extraction Protocol for ALL Figma data
+- Always resolve var() from figma-variables.json before comparing
+- Only compare resolved px/hex values — never variable names
+- Output includes the full Design Spec Table for developer reference
+- Never change schema fields or Liquid logic — HTML/CSS only
+
+### Visual Mode (`--visual`)
+When `--visual` is passed, delegate to the `visual-compare` subagent instead of running the code compare stages. The subagent:
+1. Checks/starts the dev server
+2. Uses Claude in Chrome to screenshot the rendered section (desktop 1440px + mobile 375px)
+3. Fetches Figma screenshot via `get_screenshot`
+4. Compares visually and reports: layout, spacing, typography, colors, images, responsive
+5. Checks browser console for errors
+6. Produces a visual diff report (CRITICAL / MINOR / SUGGESTION / MOBILE-SPECIFIC)
+
+See full command in `.cursor/commands/compare-section.md`.
+See visual-compare agent in `.cursor/agents/visual-compare.md`.

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

@@ -0,0 +1,78 @@
+---
+description: Scaffold a new theme folder with all required files and structure
+alwaysApply: false
+---
+
+# /create-theme
+
+Scaffold a new theme from this theme's existing files.
+
+## Usage
+```
+/create-theme <theme_name>
+```
+
+---
+
+## Step 1 — Validate
+- If `` already exists → STOP and warn the user, do not overwrite
+- If theme_name is blank → ask the user to provide a name
+
+## Step 2 — Find Reference Theme
+- Use this theme's current layouts, snippets, settings, and config as the copy template
+- Do not look outside this theme directory for other themes
+
+## Step 3 — Create Folder Structure
+Run terminal commands to create:
+
+```
+
+  assets/
+  i18n/
+    en.json           ← copy from reference theme, keep structure, clear values
+    en.schema.json    ← copy from reference theme, keep structure, clear values
+  layouts/
+    theme.liquid      ← copy from reference theme as-is
+    accounts.liquid   ← copy from reference theme as-is
+    sitemap.liquid    ← copy from reference theme as-is
+  sections/           ← empty folder
+  blocks/             ← empty folder (reusable theme blocks)
+  snippets/           ← copy all snippets from reference theme as-is
+                         (icons, search-bar, header-sidebar, etc. are shared infrastructure)
+  pages/
+    404.json
+    blog.json
+    cart.json
+    categories.json
+    checkout.json
+    collection.json
+    index.json
+    orders.json
+    page.json
+    payment.json
+    product.json
+    sitemap.json
+  settings/
+    schema.json       ← copy from reference theme as-is
+    theme.json        ← copy from reference theme as-is
+  favicon.ico
+  package.json        ← copy from reference theme, update name field to <theme_name>
+  postcss.config.js   ← copy from reference theme as-is
+  project.json        ← copy from reference theme, update name field to <theme_name>
+  tailwind.config.js  ← copy from reference theme as-is
+```
+
+## Step 4 — Note About Tokens
+Do NOT create figma-tokens.md. Tokens are read directly from:
+```
+figma-variables.json
+```
+This file is exported by the designer from Figma and placed here manually.
+Remind the developer: ask your designer for figma-variables.json before running /build-section.
+
+## Step 5 — Confirm
+Report back:
+- ✅ Theme folder created at ``
+- ✅ Snippets copied from this theme's existing `snippets/`
+- ⚠️ Ask designer for `figma-variables.json` → place at `figma-variables.json` → run `/extract-tokens` to verify
+- ⚠️ Sections folder is empty — use `/audit-page` to plan each page before building

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

@@ -0,0 +1,137 @@
+---
+description: CSS rules — applies to all themes
+globs: ["assets/*.css", "sections/*.liquid"]
+---
+
+# CSS Rules — b2bizmart Theme
+
+## Approach
+Use **Tailwind utility classes** for layout/spacing + **CSS custom properties** for theming/colors.
+Never hardcode color hex values inline — always use CSS variables.
+
+---
+
+## CSS Custom Properties (Theme Tokens)
+```css
+var(--color-primary)           /* primary brand color */
+var(--color-on-primary)        /* text color on primary background */
+var(--color-heading)           /* heading/icon color */
+var(--color-background)        /* page/card background */
+var(--color-border)            /* border color */
+var(--color-header-bg)         /* header bar background */
+var(--section-padding-x)       /* horizontal section padding, default 16px */
+```
+
+---
+
+## Correct Pattern — Color
+```html
+<!-- ✅ Correct -->
+<div style="color: var(--color-heading); background-color: var(--color-background);">
+
+<!-- ❌ Wrong — never hardcode colors inline -->
+<div style="color: #1a1a1a; background-color: #ffffff;">
+```
+
+---
+
+## Correct Pattern — Spacing
+```html
+<!-- ✅ Use Tailwind for spacing -->
+<div class="flex items-center gap-4 px-4 py-3">
+
+<!-- ✅ Use CSS var for section-level padding -->
+<div style="padding-left: var(--section-padding-x, 16px); padding-right: var(--section-padding-x, 16px);">
+```
+
+---
+
+## Container Pattern
+```html
+<div class="max-w-container-theme mx-auto">
+```
+Use `max-w-container-theme` for page-width constrained containers.
+
+---
+
+## Responsive Patterns
+```html
+<!-- Mobile first, show on desktop -->
+<div class="hidden md:block">...</div>
+<div class="hidden md:flex items-center">...</div>
+
+<!-- Visible on mobile only -->
+<div class="md:hidden">...</div>
+```
+
+---
+
+## Dynamic CSS via Liquid Style Block
+```liquid
+{% style %}
+  #section-{{ section.id }} .header-logo {
+    height: {{ section.settings.logo_width }}px;
+  }
+  #section-{{ section.id }} {
+    padding-top: {{ section.settings.padding_top }}px;
+    padding-bottom: {{ section.settings.padding_bottom }}px;
+  }
+{% endstyle %}
+```
+
+---
+
+## Tailwind in Sections
+- Only use Tailwind's core utility classes (no custom plugins assumed)
+- Tailwind config is at `tailwind.config.js`
+- PostCSS config is at `postcss.config.js`
+
+---
+
+## Rules
+- ❌ NEVER hardcode hex colors in inline styles — use `var(--color-*)` tokens
+- ❌ NEVER use `!important` unless absolutely necessary
+- ✅ Use Tailwind for layout, flexbox, grid, spacing, typography sizing
+- ✅ Use CSS variables for all color and brand theming
+- ✅ For section-specific overrides, always scope with `#section-{{ section.id }}`
+
+---
+
+## Figma MCP Variable Resolution
+When values come from **Figma MCP** output: for every `var(--variable-name, fallback)`, look up the variable name (path split by `/`) in `figma-variables.json`. If the path exists and has `$value`, use that value (theme/mode, e.g. B2BIZMART); otherwise use the fallback. Then convert the **resolved** value using the table below. See `.cursor/rules/figma-mcp-resolution.mdc`.
+
+## Figma Value → Tailwind / CSS Variable Map
+When reading Figma output (after resolving variables from figma-variables.json when using MCP), convert resolved values using this table. Never output raw px or hex inline.
+
+### Typography → Tailwind
+| Figma px | Tailwind | Use for |
+|----------|----------|---------|
+| 12px | `text-xs` | Labels, captions |
+| 14px | `text-sm` | Secondary text |
+| 16px | `text-base` | Body text |
+| 18px | `text-lg` | Large body |
+| 20px | `text-xl` | Small headings |
+| 24px | `text-2xl` | Sub-headings |
+| 30px | `text-3xl` | Section headings |
+| 36px | `text-4xl` | Page headings |
+| 48px | `text-5xl` | Hero headings |
+| 60px | `text-6xl` | Display headings |
+| 72px+ | `text-7xl` | Giant display |
+
+Font weight: 400=`font-normal`, 500=`font-medium`, 600=`font-semibold`, 700=`font-bold`, 800=`font-extrabold`
+
+### Spacing → Tailwind (1 unit = 4px)
+4px=`gap-1/p-1`, 8px=`gap-2/p-2`, 12px=`gap-3/p-3`, 16px=`gap-4/p-4`,
+20px=`gap-5/p-5`, 24px=`gap-6/p-6`, 32px=`gap-8/p-8`, 40px=`gap-10/p-10`,
+48px=`gap-12/p-12`, 64px=`gap-16/p-16`, 80px=`gap-20/p-20`
+
+### Border Radius → Tailwind
+2px=`rounded-sm`, 4px=`rounded`, 6px=`rounded-md`, 8px=`rounded-lg`,
+12px=`rounded-xl`, 16px=`rounded-2xl`, 24px=`rounded-3xl`, 9999px=`rounded-full`
+
+### When a Value is Not in This Map
+1. If the value came from Figma MCP, ensure you resolved it via `figma-variables.json` first (use `$value` if present).
+2. Check `figma-variables.json` in the current theme folder for other mappings.
+3. Use Tailwind arbitrary value: `text-[22px]` or `gap-[18px]`
+4. Add a comment: `{{-- ⚠️ unmapped token: 22px --}}`
+5. Report it in build output so it can be added to the token map if needed.