@zohofinance/commerce 1.0.0 → 1.0.1

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

@@ -0,0 +1,418 @@
+---
+
+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> [figma_url_or_node_id]
+```
+
+---
+
+
+## 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. Fetch the Figma frame automatically — 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 correct frame in Figma
+before running this command.
+
+The MCP frame data is already in your context if the developer had a frame selected.
+Look for it — it contains layout, typography, color, and spacing values.
+
+If no Figma MCP context is present:
+```
+⚠️ No Figma frame data found.
+Please:
+  1. Open your Figma file in the browser
+  2. Click on the <section_name> frame
+  3. Re-run this command in Cursor
+```
+
+**MCP fallback:** If Figma MCP is unavailable, ask: "You can paste a structured design spec (e.g. spacing, typography, colours, layout, CTA dimensions) and I'll build the section from that plus an existing section in this theme."
+
+**Both frames required:** Ask for BOTH desktop and mobile Figma frames. If only one is provided, build from that but warn: "⚠️ Missing [desktop/mobile] frame — responsive overrides may be inaccurate."
+
+---
+
+
+## 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. Extract the Element Hierarchy Tree (STRUCTURAL CONTRACT)
+Read the Figma MCP response and map out the COMPLETE structure as a nested tree.
+List EVERY element, its layout type (row/column/grid), children, and key structural properties.
+This tree defines what HTML elements must exist and how they nest.
+**If the Figma structure differs from the reference section, the Figma tree wins for HTML structure** — but preserve the reference's Liquid logic (loops, conditions, assigns).
+
+Example:
+```
+Section wrapper (column)
+├── Header row (row, justify-between)
+│   ├── Title block (column)
+│   │   ├── Heading H2
+│   │   └── Description paragraph
+│   └── Sort block (row)
+│       ├── Label text
+│       └── Dropdown
+└── Content area (row)
+    ├── Filter sidebar (column, w-300px)
+    │   └── Filter groups...
+    └── Product grid (grid, 3 cols)
+        └── Product cards...
+```
+
+### 2b. Resolve ALL var() values
+Read `figma-variables.json`.
+For every `var(--name, fallback)` in the Figma MCP data:
+- Look up the variable name by path in the JSON
+- If `$value` exists → use it
+- If not found → use the fallback
+- If neither → STOP and flag as unresolved
+
+### 2c. Extract EXACT values for EVERY visible element
+For every element in the Figma frame, extract exact resolved values:
+
+**Per TEXT element:** font-size (px → Tailwind), font-weight (number → Tailwind), line-height, letter-spacing, text-color (hex → CSS var), text-align, max-width
+
+**Per CONTAINER:** layout (flex/grid), columns, gap (px → Tailwind), padding (all sides, px → Tailwind), margin, alignment, background (hex → CSS var)
+
+**Per IMAGE:** width, height, aspect-ratio, object-fit, border-radius (px → Tailwind)
+
+**Per BUTTON/CTA:** padding (px → Tailwind), font-size, font-weight, background (hex → CSS var), text-color (hex → CSS var), border, border-radius
+
+**Per CARD:** internal padding, background, border, border-radius, shadow, internal layout/gap, children
+
+**Section-level:** padding-top, padding-bottom, background, container width, horizontal padding
+
+### 2d. Extract responsive differences from mobile frame
+If mobile frame available, extract ONLY what differs: column count, font sizes, gaps, padding, visibility, stack direction.
+
+### 2e. Produce the Design Spec Table
+Compile ALL extracted values into a structured table. This table is the BUILD CONTRACT.
+Every row in this table MUST appear in the final HTML/CSS.
+
+```
+DESIGN SPEC — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  | Element          | Property        | Desktop Value      | Mobile Override    | Tailwind/CSS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1  | Section heading  | font-size       | 48px               | 30px               | text-5xl md:text-3xl
+...
+```
+
+**Print this table before proceeding to Stage 3.** This is the reference for everything that follows.
+
+---
+
+
+## Stage 3 — Map Figma Values to Tokens
+Read `figma-variables.json`.
+
+This JSON contains all resolved token values directly — no aliases, no guessing needed.
+To find any token value:
+- Font sizes are under `font > size > <name> > $value` (e.g. `font/size/9xl → 56`)
+- Colors are under `color > <group> > <name> > $value > hex`
+- Padding under `Padding > P - N > $value`
+- Gap under `Gap > G - N > $value`
+- Radius under `radius > <name> > $value`
+
+For every value in the Design Spec Table:
+- Font size → Tailwind class from token map (e.g. 56px → `text-[56px]`)
+- Color → CSS variable from token map (e.g. #1a1a1a → `var(--color-heading)`)
+- Spacing/gap → Tailwind class from token map (e.g. 24px → `gap-6`)
+- Border radius → Tailwind class from token map (e.g. 12px → `rounded-xl`)
+- If a value is NOT in the token map → use Tailwind arbitrary value and add a comment:
+  `{{-- ⚠️ token not mapped: 22px → using text-[22px] --}}`
+
+Update the Design Spec Table's "Tailwind/CSS" column with the mapped values.
+
+---
+
+
+## Stage 4 — Build HTML Structure
+Write the HTML/Liquid markup using the Design Spec Table as your blueprint.
+
+**For each row in the spec table, apply the exact Tailwind/CSS value.** Do not deviate.
+
+Rules:
+- Use 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 from token map — never inline font-size
+- Spacing: only Tailwind spacing classes from token map
+- Responsive: use mobile-first approach. Base classes = mobile, `md:` prefix = desktop.
+  Example: `class="text-3xl md:text-5xl gap-4 md:gap-6 grid-cols-2 md:grid-cols-4"`
+- All dynamic content uses Liquid variables with placeholder assigns:
+  `{% assign heading = section.settings.heading %}`
+- Images use:
+  ```liquid
+  <img src="{{ section.settings.image_field.url }}" alt="{{ section.settings.alt | escape }}"
+       width="800" height="600" loading="lazy">
+  ```
+- Wrap section in:
+  ```liquid
+  <section id="section-{{ section.id }}" class="...">
+  ```
+
+**IMPORTANT — Match spec exactly:**
+- If the spec says `gap-6`, use `gap-6` — not `gap-4` or `gap-8`
+- If the spec says `text-5xl font-bold`, use both — do not omit font-weight
+- If the spec says `rounded-xl`, use `rounded-xl` — not `rounded-lg`
+- If the spec has mobile overrides, include responsive prefixes
+
+---
+
+
+## Stage 5 — Add Schema
+Add `{% schema %}` at the bottom of the file.
+
+For every Liquid variable used in Stage 4, create the correct schema field.
+Always use custom schema syntax from schema.mdc — never standard Shopify syntax:
+
+- url → `{ "display_name": "t:...", "handle": "/path" }`
+- image_picker → `{ "url": "file.webp", "enable_customisation": true }`
+- media_picker (video) → `{ "url": "video.mp4", "is_video": true }`
+- select → `{ "display_name": "t:...", "value": "option-value" }`
+- menu → `{ "display_name": "t:...", "handle": "" }`
+- text default → `"t:sections.<name>.settings.<id>.default"`
+- All labels → `"t:sections.<name>.settings.<id>.label"`
+
+**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
+
+Copy schema fields from the reference section first, then add any NEW fields identified in Stage 2.
+
+Always include at the end of settings:
+```jsonc
+{ "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" }
+```
+
+**Set padding_top/padding_bottom defaults from the Figma spec** — not always 40. If Figma shows 48px top and 64px bottom, use those as defaults.
+
+---
+
+
+## Stage 6 — Add Style Block and Script
+Add `{% style %}` block above the HTML:
+```liquid
+{% style %}
+  #section-{{ section.id }} {
+    padding-top: {{ section.settings.padding_top }}px;
+    padding-bottom: {{ section.settings.padding_bottom }}px;
+  }
+{% endstyle %}
+```
+
+Add script tag if the reference section used a JS component:
+```liquid
+<script src="{{ 'component-name.js' | asset_url }}" defer></script>
+```
+
+---
+
+
+## Stage 7 — Self-Compare Against Design Spec (CRITICAL — DO NOT SKIP)
+
+Before saving the file, run a compare pass using the Design Spec Table from Stage 2d.
+
+**For every row in the spec table:**
+1. Find the corresponding HTML element in your generated code
+2. Verify the Tailwind class / CSS variable matches EXACTLY
+3. If it doesn't match → fix it immediately
+
+### Check each property:
+- [ ] Font size: does the Tailwind class match the spec? (e.g. spec says `text-5xl`, code has `text-5xl`?)
+- [ ] Font weight: does the Tailwind class match? (e.g. spec says `font-bold`, code has `font-bold`?)
+- [ ] Text color: does the CSS variable match? (e.g. spec says `var(--color-heading)`, code uses it?)
+- [ ] Spacing/gap: do Tailwind gap/padding/margin classes match spec exactly?
+- [ ] Border radius: does the Tailwind class match spec?
+- [ ] Layout direction: does the flex/grid setup match spec?
+- [ ] Column count: does grid-cols match spec at each breakpoint?
+- [ ] Background color: does the CSS variable match spec?
+- [ ] Button styling: do all button properties match spec?
+- [ ] Image properties: aspect-ratio, object-fit, border-radius match?
+- [ ] Responsive overrides: are mobile-first classes with `md:` prefixes present for all mobile overrides in spec?
+
+### Produce a self-compare report:
+```
+SELF-COMPARE — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Spec rows checked: <n>
+Matches: <n>
+Mismatches found and auto-fixed: <n>
+  - [list each mismatch and what was corrected]
+Unresolvable: <n>
+  - [list any that couldn't be resolved]
+```
+
+**If ANY mismatches are found, fix them in the code BEFORE proceeding.**
+
+---
+
+
+## Stage 8 — Code QA Before Saving
+After the self-compare pass, also check:
+- [ ] Every `section.settings.X` has a matching schema field
+- [ ] No raw hex colors inline (all use `var(--color-*)`)
+- [ ] No raw px font sizes inline (all use Tailwind classes)
+- [ ] All loops have empty state handling
+- [ ] All images have width, height, alt, loading attributes
+- [ ] Video fields use `media_picker` schema with default `{ "url": "video.mp4", "is_video": true }`
+- [ ] All labels/defaults use `t:` translation keys
+- [ ] Schema has padding_top and padding_bottom settings (with Figma-accurate defaults)
+- [ ] Schema has at least one preset
+- [ ] No static px/color values in `{% style %}` block that should be Tailwind classes
+- [ ] Responsive classes present for all mobile overrides from spec
+- [ ] Heading/title fields use `text`; body/description fields use `richtext` (never `richtext` on heading blocks)
+
+---
+
+
+## Output
+Save to: `sections/<section_name>.liquid`
+
+After saving, report:
+```
+✅ Section built: sections/<section_name>.liquid
+
+DESIGN SPEC SUMMARY (from Figma):
+- [number] elements extracted, [number] properties mapped
+
+SELF-COMPARE RESULT:
+- Spec rows: <n> | Matches: <n> | Auto-fixed: <n> | Unresolvable: <n>
+
+WHAT WAS PRESERVED FROM REFERENCE:
+- [list schema fields kept]
+- [list logic/loops kept]
+
+WHAT WAS NEW FROM FIGMA:
+- [list new schema fields added]
+- [list structural changes]
+
+⚠️ UNMAPPED TOKENS (review these):
+- [any values not found in figma-variables.json]
+
+⚠️ UNRESOLVABLE MISMATCHES (need manual review):
+- [any spec rows that couldn't be matched]
+
+NEXT: Run /compare-section <theme_name> <section_name> for final Figma verification
+Or run /build-section <theme_name> <next_section_name>
+```
+
+---
+
+
+## Section File Anatomy — Required Structure (top to bottom)
+
+Every section file must follow this exact order:
+
+```liquid
+{{-- 1. SCRIPT TAGS --}}
+<script src="{{ 'component-name.js' | asset_url }}" defer></script>
+
+{{-- 2. STYLE BLOCK --}}
+{% style %}
+  #section-{{ section.id }} {
+    padding-top: {{ section.settings.padding_top }}px;
+    padding-bottom: {{ section.settings.padding_bottom }}px;
+  }
+{% endstyle %}
+
+{{-- 3. LIQUID ASSIGNS --}}
+{% liquid
+  assign heading      = section.settings.heading
+  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. CONTENT --}}
+    {% if heading != blank %}
+      <h2 class="text-4xl font-bold" style="color: var(--color-heading);">{{ heading | escape }}</h2>
+    {% endif %}
+
+    {{-- 7. LOOPS — always 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 last --}}
+{% schema %}
+{
+  "name": "t:sections.<n>.name",
+  "tag": "section",
+  "class": "section",
+  "settings": [
+    { "type": "text", "id": "heading", "label": "t:sections.<n>.settings.heading.label", "default": "t:sections.<n>.settings.heading.default" },
+    { "type": "checkbox", "id": "show_section", "label": "t:sections.<n>.settings.show_section.label", "default": true },
+    { "type": "range", "id": "padding_top", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40, "label": "t:sections.<n>.settings.padding_top.label" },
+    { "type": "range", "id": "padding_bottom", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40, "label": "t:sections.<n>.settings.padding_bottom.label" }
+  ],
+  "blocks": [],
+  "presets": [{ "name": "t:sections.<n>.presets.default.name" }]
+}
+{% endschema %}
+```
+
+### Order Rules
+- Script tags → TOP
+- Style block → after scripts, before assigns
+- All assigns → single `{% liquid %}` block
+- Schema → ALWAYS last, never in the middle
+- Every loop → MUST have `{% else %}` empty state
+- Every heading/text → check `!= blank` before rendering