@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/design-tokens.md

@@ -0,0 +1,105 @@
+# SKILL: Design Tokens
+# Save this as a Cursor Notepad named: design-tokens
+# Usage in chat: @design-tokens
+
+How to correctly map Figma values to Tailwind classes and CSS variables in this theme system.
+Always use this when reading Figma output — never use raw values inline.
+
+---
+
+## Figma MCP variable resolution (do this first)
+When using **Figma MCP** (e.g. get_design_context), the response contains `var(--variable-name, fallback)`. The fallback may be from a different mode (e.g. TWICE). To use the theme’s mode (e.g. B2BIZMART):
+
+1. **Look up** the variable name in `figma-variables.json`: split the name on `/` and traverse (e.g. `radius/xl` → `json["radius"]["xl"]`).
+2. If the node has **`$value`**, use that value.
+3. If not found, use the **fallback** from the MCP response.
+4. Then map this **resolved** value to Tailwind/CSS using the tables below.
+
+See `.cursor/rules/figma-mcp-resolution.mdc` for the full rule.
+
+---
+
+## The Rule
+❌ Never output: `style="font-size: 48px; color: #1a1a1a"`
+✅ Always output: `class="text-5xl" style="color: var(--color-heading)"`
+
+---
+
+## CSS Variables (always use these for color)
+| Role | Variable |
+|------|----------|
+| Primary brand | `var(--color-primary)` |
+| Text on primary bg | `var(--color-on-primary)` |
+| Headings / dark text | `var(--color-heading)` |
+| Page / card background | `var(--color-background)` |
+| Border / divider | `var(--color-border)` |
+| Header bar background | `var(--color-header-bg)` |
+| Section horizontal padding | `var(--section-padding-x, 16px)` |
+
+For theme-specific colors not in this list → check `figma-variables.json` in the current theme folder (and resolve Figma MCP vars from it first when using MCP).
+
+---
+
+## Typography → Tailwind
+| Figma px | Tailwind | Use for |
+|----------|----------|---------|
+| 12px | `text-xs` | Labels, captions |
+| 14px | `text-sm` | Secondary text, meta |
+| 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:
+| Figma | Tailwind |
+|-------|----------|
+| 400 | `font-normal` |
+| 500 | `font-medium` |
+| 600 | `font-semibold` |
+| 700 | `font-bold` |
+| 800 | `font-extrabold` |
+
+---
+
+## Spacing → Tailwind (1 unit = 4px)
+| Figma px | Tailwind gap/p/m |
+|----------|-----------------|
+| 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
+| Figma px | 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 from Figma MCP, resolve 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 the build output so it can be added to the token map if needed.

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/page-json-contract.md

@@ -0,0 +1,58 @@
+# SKILL: Page JSON contract
+# Usage in chat: @page-json-contract
+
+How page JSON relates to section schema. Use when running `/assemble-page` or `/validate-page`.
+
+---
+
+## Page JSON shape
+
+```json
+{
+  "layout": "theme",
+  "sections": {
+    "<section_key>": {
+      "type": "<section_filename_without_.liquid>",
+      "settings": { ... },
+      "blocks": { "<block_key>": { "type": "<block_type>", "settings": {} } },
+      "block_order": ["<block_key>", ...]
+    }
+  },
+  "order": ["<section_key_1>", "<section_key_2>", ...]
+}
+```
+
+- **section_key:** arbitrary key (e.g. `hero`, `product_details`). Must be unique in the page.
+- **type:** must exactly match a section file name under `sections/` (e.g. `product-details` for `product-details.liquid`).
+- **blocks:** only present if the section schema defines `"blocks": { ... }`. Each key in `blocks` is a block instance; `type` must match a block type in that section’s schema.
+- **block_order:** array of block keys; every key must exist in `blocks`. Order determines render order.
+- **order:** array of section keys; every key must exist in `sections`. Order determines section order on the page.
+
+---
+
+## Settings value formats (inline in page JSON)
+
+| Schema type   | Page JSON value format |
+|---------------|------------------------|
+| text          | string                 |
+| url           | `{ "display_name": "t:...", "handle": "/path" }` |
+| image_picker  | `{ "url": "file.webp", "enable_customisation": true }` |
+| media_picker  | `{ "url": "video.mp4", "is_video": true }` |
+| select        | `{ "display_name": "t:...", "value": "option-value" }` |
+| menu          | `{ "display_name": "t:...", "handle": "menu-handle" }` |
+| checkbox      | true / false            |
+| range/number  | number                  |
+| color         | hex string e.g. "#000000" |
+
+All user-facing strings use `t:` keys. Section and block setting IDs in page JSON must match the section’s `{% schema %}`.
+
+---
+
+## Validation (for /validate-page)
+
+- For each entry in `order`, the key exists in `sections`.
+- For each `sections.<key>.type`, the file `sections/<type>.liquid` exists.
+- For each section that has `blocks` and `block_order`, every entry in `block_order` exists in `blocks`.
+- For each `blocks.<key>.type`, that type is defined in the section’s schema under `"blocks": { "<block_type>": { ... } }`.
+
+Reference this skill when assembling or validating page JSON.

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/qa-accessibility.md

@@ -0,0 +1,35 @@
+# SKILL: QA Accessibility
+# Usage in chat: @qa-accessibility
+
+Checklist for auditing section accessibility when running `/qa-section` or reviewing a section manually.
+
+---
+
+## Images
+- Every `<img>` has a non-empty `alt`. Use meaningful description (e.g. product name, CTA context); decorative images may use `alt=""`.
+- Avoid images of text for critical content; if used, `alt` must convey the same information.
+
+## Headings
+- Logical order: do not skip levels (e.g. h1 → h3). Use h1 once per section/page for main title.
+- Headings describe the content that follows.
+
+## Forms and controls
+- Every form control has an associated label: use `<label for="id">` or `aria-label` / `aria-labelledby`.
+- Groups of controls (e.g. variant options, sort options): use `<fieldset>` + `<legend>` or `role="group"` with `aria-labelledby` pointing to a visible label element (e.g. `<div id="...">`).
+- Required fields indicated (e.g. `aria-required="true"` or visible "required" text).
+
+## Focus and keyboard
+- No `outline: none` (or similar) without a visible focus style (e.g. `outline: 2px solid var(--color-primary)` or `ring-2`).
+- Interactive elements (links, buttons, custom controls) are focusable and have a visible focus indicator.
+- Focus order follows visual order where possible.
+
+## Buttons and links
+- Icon-only buttons/links have a descriptive `aria-label` (e.g. "Add to cart", "Close menu", "Previous slide").
+- Links that open in new tab: consider `target="_blank"` + `rel="noopener"` and optionally announce in `aria-label` for screen readers.
+
+## Landmarks
+- Section has a sensible structure; if it’s a main content region, consider `role="region"` and `aria-labelledby` for the section heading where it improves navigation.
+
+---
+
+Use this skill when running the ACCESSIBILITY row of `/qa-section` or when asked to review a section for a11y.

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/reference-lookup.md

@@ -0,0 +1,94 @@
+# SKILL: Reference Lookup
+# Save this as a Cursor Notepad named: reference-lookup
+# Usage in chat: @reference-lookup
+
+How to find and use existing theme sections as references when building new sections.
+
+---
+
+## Step 1 — Find the Reference
+Look for an equivalent section in this theme:
+```
+sections/    ← look for existing sections with similar purpose
+snippets/    ← look for reusable snippets
+```
+
+Match by purpose, not filename. Examples:
+| Building | Look for reference named |
+|----------|------------------------|
+| hero-banner | banner, hero, slider, masthead |
+| category-grid | category, collection-grid, product-listing |
+| featured-products | featured, products, product-grid |
+| testimonials | testimonials, reviews, quotes |
+| footer | footer |
+| header | header |
+
+---
+
+## Step 2 — What to Extract
+Open the reference file and extract ONLY these parts:
+
+### Keep exactly as-is
+- Schema field IDs (e.g. `heading`, `cta_url`, `bg_image`) 
+- Schema field types
+- `{% liquid %}` assign variable names
+- Loop variable names (e.g. `{% for product in products %}`)
+- `{% render %}` snippet calls (these are shared infrastructure)
+- JS web component tag names (e.g. `<product-card>`)
+- Conditional logic patterns
+
+### Adapt (keep structure, update values)
+- Schema labels → update `t:` key path to new section name
+- Schema defaults → update `t:` key path to new section name
+- CSS class names → replace with new Figma-based Tailwind classes
+- HTML structure → replace with new Figma layout
+
+### Discard
+- Inline hardcoded colors from old theme
+- Old theme's specific layout classes
+- Deprecated workarounds or comments marked as fixes
+
+---
+
+## Step 3 — When No Reference Exists
+If no matching section exists in this theme:
+1. Look for the closest partial match (e.g. use a card section as base for a different card layout)
+2. Build schema from scratch using schema.mdc rules
+3. Mark in your build notes: "NEW — no reference, built from schema.mdc"
+
+---
+
+## Quick Reference: Common Section Patterns
+
+### Settings every section should have
+```jsonc
+{ "type": "text", "id": "heading" }
+{ "type": "checkbox", "id": "show_section", "default": true }
+{ "type": "range", "id": "padding_top" }
+{ "type": "range", "id": "padding_bottom" }
+```
+
+### Settings for sections with images
+```jsonc
+{ "type": "image_picker", "id": "section_image", 
+  "default": { "url": "placeholder.webp", "enable_customisation": true } }
+```
+
+### Settings for sections with video
+```jsonc
+{ "type": "media_picker", "id": "video_media",
+  "default": { "url": "video.mp4", "is_video": true } }
+```
+
+### Settings for sections with CTAs
+```jsonc
+{ "type": "text", "id": "cta_text" }
+{ "type": "url", "id": "cta_url",
+  "default": { "display_name": "t:...", "handle": "/" } }
+```
+
+### Settings for sections with menus
+```jsonc
+{ "type": "menu", "id": "section_menu",
+  "default": { "display_name": "t:...", "handle": "" } }
+```

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/section-anatomy.md

@@ -0,0 +1,109 @@
+# SKILL: Section Anatomy
+# Save this as a Cursor Notepad named: section-anatomy
+# Usage in chat: @section-anatomy
+
+Every section file must follow this exact anatomy. Use this as the structural checklist.
+
+---
+
+## Complete Section File Structure (top to bottom)
+
+```liquid
+{{-- 1. SCRIPT TAGS (if JS component needed) --}}
+<script src="{{ 'component-name.js' | asset_url }}" defer></script>
+
+{{-- 2. STYLE BLOCK (dynamic CSS scoped to this section) --}}
+{% style %}
+  #section-{{ section.id }} {
+    padding-top: {{ section.settings.padding_top }}px;
+    padding-bottom: {{ section.settings.padding_bottom }}px;
+  }
+{% endstyle %}
+
+{{-- 3. LIQUID ASSIGNS (all settings extracted at top) --}}
+{% liquid
+  assign heading        = section.settings.heading
+  assign sub_heading    = section.settings.sub_heading
+  assign cta_text       = section.settings.cta_text
+  assign cta_url        = section.settings.cta_url
+  assign bg_image       = section.settings.bg_image
+  assign show_section   = section.settings.show_section
+%}
+
+{{-- 4. CONDITIONAL VISIBILITY --}}
+{% if show_section %}
+
+{{-- 5. SECTION WRAPPER --}}
+<section id="section-{{ section.id }}" class="section-name w-full">
+  <div class="max-w-container-theme mx-auto" style="padding-left: var(--section-padding-x, 16px); padding-right: var(--section-padding-x, 16px);">
+
+    {{-- 6. SECTION CONTENT --}}
+    {% if heading != blank %}
+      <h2 class="text-4xl font-bold" style="color: var(--color-heading);">{{ heading | escape }}</h2>
+    {% endif %}
+
+    {{-- 7. LOOPS WITH EMPTY STATE --}}
+    {% if items.size > 0 %}
+      {% for item in items %}
+        {{-- item markup --}}
+      {% endfor %}
+    {% else %}
+      <p class="text-center" style="color: var(--color-heading);">No items found.</p>
+    {% endif %}
+
+  </div>
+</section>
+
+{% endif %}
+
+{{-- 8. SCHEMA (always at the very bottom) --}}
+{% schema %}
+{
+  "name": "t:sections.<name>.name",
+  "tag": "section",
+  "class": "section",
+  "settings": [
+    {
+      "type": "text",
+      "id": "heading",
+      "label": "t:sections.<name>.settings.heading.label",
+      "default": "t:sections.<name>.settings.heading.default"
+    },
+    {
+      "type": "checkbox",
+      "id": "show_section",
+      "label": "t:sections.<name>.settings.show_section.label",
+      "default": true
+    },
+    {
+      "type": "range",
+      "id": "padding_top",
+      "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40,
+      "label": "t:sections.<name>.settings.padding_top.label"
+    },
+    {
+      "type": "range",
+      "id": "padding_bottom",
+      "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40,
+      "label": "t:sections.<name>.settings.padding_bottom.label"
+    }
+  ],
+  "blocks": [],
+  "presets": [
+    { "name": "t:sections.<name>.presets.default.name" }
+  ]
+}
+{% endschema %}
+```
+
+---
+
+## Rules
+- Script tags → TOP of file
+- Style block → after scripts, before assigns
+- All assigns → in one `{% liquid %}` block at top
+- Conditional visibility → wrap entire section if needed
+- Schema → ALWAYS last, never in the middle
+- Padding settings → ALWAYS included in every section
+- Every loop → MUST have empty state
+- Every heading/text → check `!= blank` before rendering