@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/theme-structure.md

@@ -0,0 +1,252 @@
+---
+title: "Theme Structure"
+weight: 2
+---
+
+# Theme Structure
+
+Zoho Commerce themes follow a strict folder structure. Every theme must include these main directories.
+
+## Required Folders
+
+```
+theme/
+├── assets/          # Static files (CSS, JavaScript, images)
+├── i18n/           # Translation files for multi-language support
+├── layouts/        # Main theme layouts
+├── pages/          # Page-specific default JSON configuration
+├── sections/       # Section components (.liquid files)
+├── snippets/       # Reusable template fragments
+└── settings/       # Theme-wide configuration
+```
+
+## 1. Assets Folder
+
+Contains all static files needed by the theme:
+
+```
+theme/assets/
+├── style.css             # Main stylesheet
+├── main.css              # Additional stylesheet
+├── theme-settings.css    # CSS for theme customization
+├── signin.css            # Sign-in page styles
+├── header.js             # Header component script
+├── footer.js             # Footer component script
+├── *.js                  # Page-specific scripts
+├── *.webp                # Theme images
+└── fingerprint.json      # Asset versioning (REQUIRED)
+```
+
+**Important**: All asset files must be referenced using the `asset_url` filter. Pass just the filename (e.g., `"main.css"`), not the full path. The `fingerprint.json` file is mandatory for cache busting.
+
+Example asset reference:
+```liquid
+<link rel="stylesheet" href="{{ "main.css" | asset_url }}">
+<script src="{{ "header.js" | asset_url }}" defer></script>
+```
+
+Example fingerprint.json:
+```json
+{
+  "main.css": "main-585919664682927.css",
+  "main.js": "main-59775934977548.js",
+  "logo.svg": "logo-123456789.svg"
+}
+```
+
+## 2. Internationalization (i18n) Folder
+
+Contains translation files:
+
+```
+theme/i18n/
+├── en.json        # English (default fallback)
+├── en.schema.json # Schema label translations for the theme editor
+├── ar.json        # Arabic
+├── de.json        # German
+├── es.json        # Spanish
+├── fr.json        # French
+├── id.json        # Indonesian
+├── ja.json        # Japanese
+├── ko.json        # Korean
+├── pt.json        # Portuguese
+├── th.json        # Thai
+├── vi.json        # Vietnamese
+├── zh.json        # Chinese (Simplified)
+└── zh_tw.json     # Chinese (Traditional)
+```
+
+**File structure:**
+- `en.json`: Default fallback for all translations used in templates with the `t` filter
+- `en.schema.json`: Translations for section schema labels (used with `t:` prefix)
+- Other language files: Add only the languages your store supports
+
+Example i18n/en.json:
+```json
+{
+  "header": {
+    "sign_in": "Sign In",
+    "sign_out": "Sign Out",
+    "my_orders": "My Orders"
+  },
+  "product_details": {
+    "sold_out": "Sold Out",
+    "on_sale": "On sale"
+  },
+  "pagination": {
+    "previous_btn": "<",
+    "next_btn": ">"
+  }
+}
+```
+
+## 3. Layouts Folder
+
+Contains main template structures:
+
+```
+theme/layouts/
+├── theme.liquid        # Default layout for all pages
+├── accounts.liquid     # Layout for sign-in/sign-up pages
+└── sitemap.liquid      # XML sitemap layout
+```
+
+**theme.liquid** is the main HTML document wrapper. It contains:
+- Page title rendering
+- Stylesheet and favicon inclusion
+- `{{ content_for_header }}` — server-injected head output from Zoho Commerce admin: meta tags, stylesheets, **analytics scripts** (no separate theme integration required), and related platform head content
+- Header and footer sections
+- `{{ content_for_layout }}` — renders page content
+- `{{ content_for_footer }}` — scripts that load after DOM
+
+**accounts.liquid** is the specialized layout for authentication and account pages.
+
+**sitemap.liquid** generates the XML sitemap structure for search engines.
+
+## 4. Pages Folder
+
+Contains JSON default configurations for each page type:
+
+```
+theme/pages/
+├── index.json                    # Home page defaults
+├── product.json                  # Product detail page
+├── collection.json               # Collection/category page
+├── category.json                 # Category page
+├── cart.json                     # Shopping cart
+├── checkout.json                 # Checkout page
+├── search.json                   # Search results
+├── blog.json                     # Blog post page
+├── blogs.json                    # Blog listing
+├── signin.json                   # Login page
+├── signup.json                   # Registration page
+├── forgotpassword.json           # Password reset
+├── account-profile.json          # Customer profile
+├── account-address.json          # Saved addresses
+├── account-order.json            # Order history listing
+├── account-order-detail.json     # Single order detail
+├── account-order-status.json     # Order tracking/status
+├── account-wishlist.json         # Customer wishlist
+├── orders.json                   # Orders overview
+├── payment.json                  # Payment confirmation/failure
+├── sitemap.json                  # XML sitemap
+├── page.json                     # All custom pages (single template)
+└── 404.json                      # Not found page
+```
+
+**Note**: There is no support for individual custom page JSON files. All custom pages created in the admin use the single `page.liquid` section template with defaults from `page.json`.
+
+## 5. Sections Folder
+
+Contains reusable section components:
+
+```
+theme/sections/
+├── header.liquid           # Header component
+├── header-group.json       # Header section group configuration
+├── footer.liquid           # Footer component
+├── footer-group.json       # Footer section group configuration
+├── banner.liquid           # Banner section
+├── product-details.liquid  # Product information section
+├── product-collection.liquid
+├── cart-page.liquid
+└── ...
+```
+
+**Section structure:**
+Each section `.liquid` file contains both template logic and an embedded `{% schema %}` block for configuration.
+
+Sections are the main editable components users customize in the Zoho Commerce admin.
+
+**Section group files** (`header-group.json`, `footer-group.json`) define fixed sets of sections for the header and footer areas. They are rendered in layouts using the Zoho Commerce-specific `{% sections 'header-group' %}` tag — see [Layouts](/layouts/) for details.
+
+## 6. Snippets Folder
+
+Reusable template fragments that don't have configuration settings:
+
+```
+theme/snippets/
+├── product-card.liquid               # Product listing card
+├── cart-item.liquid                  # Cart item row
+├── pagination.liquid                 # Pagination controls
+├── product-variant-picker.liquid     # Variant selection UI
+├── icon-cart.liquid                  # Cart icon
+├── icon-search.liquid                # Search icon
+└── ...
+```
+
+**Usage**: Snippets are rendered from other templates using the `render` tag:
+```liquid
+{% render 'product-card', product: product %}
+```
+
+## 7. Settings Folder
+
+Theme-wide configuration and customization options:
+
+```
+theme/settings/
+├── schema.json       # Theme settings schema
+└── theme.json        # Default theme settings values
+```
+
+**schema.json** defines customizable theme options like colors, fonts, and layout preferences. Use `meta` property to group settings:
+- `"meta": "global_settings"` — for global theme settings
+- `"meta": "component_settings"` — for component-specific settings
+
+**theme.json** provides default values for all theme settings.
+
+## Naming Conventions
+
+- Files: lowercase with hyphens (product-card.liquid, main.css)
+- Variables: snake_case (product_title, cart_items)
+- IDs: camelcase (id="productCard")
+- Classes: lowercase with hyphens (class="product-card-featured")
+
+## Best Practices
+
+1. Keep files focused and reasonably sized
+2. Use consistent naming across related files
+3. Use `asset_url` for all theme assets (pass filename only)
+4. Use `image_url` for product/collection images
+5. Comment complex or non-obvious logic
+6. Name files descriptively so they're easy to find
+7. Use translation keys (`t:` prefix) for all schema labels
+8. Include `{{ block.zcommerce_attributes }}` on block wrapper elements
+
+## Validation Checklist
+
+Before publishing your theme:
+
+- All required folders exist
+- fingerprint.json is present in assets/
+- en.json exists as translation fallback
+- en.schema.json exists for schema label translations
+- Schema IDs match values used in page JSONs
+- All assets reference use `asset_url` filter
+- All product images use `image_url` filter
+- Block elements include `zcommerce_attributes`
+- No broken links or missing references
+- Asset sizes optimized for performance
+
+

package/ts-dist/mocks/init-theme/.cursor/PLAYBOOK.md

@@ -0,0 +1,144 @@
+# Theme development playbook
+
+Use this as the single source of truth for command order and when to run each step.
+
+---
+
+## Flow 0 — Full autopilot (new theme from Figma) ⭐ RECOMMENDED
+
+Use when you have a complete Figma file with Guidelines, Website View, and Mobile View.
+This flow includes integrated design verification — sections match Figma on the first pass.
+
+| Step | Command | Notes |
+|------|---------|--------|
+| 1 | `/build-theme <theme_name> <figma_file_key>` | Scaffolds theme, extracts tokens, audits all pages, builds all sections **with design spec verification**, assembles page JSON, runs QA |
+| 2 | Review the consolidated audit plan | Only manual step — approve or edit before builds start |
+| 3 | Review the design accuracy summary | Check which sections have <100% spec match |
+| 4 | `/compare-section <theme_name> <section>` | **Only for sections with unresolved items** — most issues are now caught during build |
+| 5 | `/fix-section <theme_name> <section>` | Fix any remaining mismatches from step 4 |
+| 6 | `/qa-theme <theme_name>` | Final QA after any manual fixes |
+
+**What changed:** Steps 3-5 are now optional for most sections. The build itself includes design spec extraction, self-compare, and auto-fix — so the first output should be very close to the Figma design.
+
+---
+
+## Flow 1 — New theme / new page (step-by-step)
+
+Run in this order when you prefer manual control over each step:
+
+| Step | Command | Notes |
+|------|---------|--------|
+| 1 | `/create-theme <theme_name>` | Scaffold theme from reference |
+| 2 | `/extract-tokens <theme_name>` | Confirm `figma-variables.json` is in the theme |
+| 2b | `/sync-theme-settings <theme_name>` | Optional: fill token-mapped globals in `theme.json` |
+| 3 | `/audit-page <theme_name> <page_name>` | Plan sections from Figma; no code yet |
+| 4 | `/build-page-sections <theme_name> <page_name>` | Batch-build all sections with design verification; or use `/build-section` one at a time |
+| 5 | Review design accuracy report | Check spec match % per section |
+| 6 | `/compare-section <theme_name> <section_name>` | Only for sections with <100% match — provides detailed mismatch report |
+| 7 | Apply fixes | Reply `ALL` / `CRITICAL ONLY` / issue numbers, or run `/fix-section` |
+| 8 | `/qa-section <theme_name> <section_name>` | Re-run after fixes to verify no regressions |
+| 9 | Repeat 6–8 only for sections with issues | Most sections should be clean from step 4 |
+| 10 | `/assemble-page <theme_name> <page_name>` | Generate page JSON after all sections are built and QA'd |
+| 11 | `/validate-page <theme_name> <page_name>` | Optional: verify page JSON references real sections and blocks |
+| 12 | `/qa-theme <theme_name>` | Full theme QA: sections, settings, layouts, groups, pages, i18n |
+
+**What changed:** Step 4 now includes design spec extraction and self-compare, so steps 6-9 are only needed for edge cases.
+
+---
+
+## Flow 2 — Redesign existing section (new Figma)
+
+| Step | Command | Notes |
+|------|---------|--------|
+| 1 | `/compare-section <theme_name> <section_name>` | Provide **both** desktop and mobile Figma URLs — now outputs full Design Spec Table |
+| 2 | Apply fixes | Reply `Implement this design from Figma` or `ALL` to apply all; or use `/fix-section` with specific issues |
+| 3 | `/redesign-section` | If replacing HTML/CSS only (logic unchanged) |
+| 4 | `/qa-section <theme_name> <section_name>` | Verify schema, tokens, a11y unchanged |
+| 5 | `/compare-section` again | Confirm no remaining mismatches |
+
+---
+
+## Flow 3 — Bug fix (no design change)
+
+| Step | Command | Notes |
+|------|---------|--------|
+| 1 | **Visual bug?** Run `/compare-section` first | Get Figma-driven fix list with Design Spec Table; then apply via fix-section or approval |
+| 2 | `/fix-section <theme_name> <section_name>` | Describe: what's broken vs expected; diagnose then fix |
+| 3 | `/qa-section <theme_name> <section_name>` | Verify no regressions |
+
+---
+
+## Quality gate (every section before ship)
+
+Run these before considering a section done:
+
+```
+/qa-section       → code correctness (schema, Liquid, tokens, images, a11y)
+/compare-section  → design accuracy (spacing, typography, layout, colour) — use both Figma URLs
+/fix-section     → fix approved issues from either report
+```
+
+**Note:** If the section was built with the updated `/build-section` (which includes self-compare), the compare-section step often finds zero issues.
+
+---
+
+## Flow 4 — New theme customizer setting (global / component)
+
+| Step | Command | Notes |
+|------|---------|--------|
+| 1 | `/add-theme-setting <theme_name>` | Group + field(s) → `settings/schema.json`, every preset in `theme.json`, `i18n/en.schema.json` |
+| 2 | Wire in layout / CSS / JS | Same session or follow-up |
+| 3 | If Figma-driven global | Extend `/sync-theme-settings` mapping table, then run `/sync-theme-settings` |
+
+Use **`/add-field`** for **section** settings only.
+
+---
+
+## Flow 5 — Full theme QA (pre-release)
+
+Run `/qa-theme` to execute all checks in one shot, or run individually:
+
+| Step | Command | Notes |
+|------|---------|--------|
+| 1 | `/qa-sections <theme_name>` | All sections: schema, Liquid, tokens, images, a11y, perf |
+| 2 | `/validate-theme-settings <theme_name>` | schema.json ↔ theme.json ↔ en.schema.json ↔ Liquid |
+| 3 | `/qa-layout <theme_name>` | All layout files: HTML, assets, groups, snippets, parity |
+| 4 | `/validate-section-group <theme_name> <group>` | Per group: structure, section types, settings, layout wiring |
+| 5 | `/validate-page <theme_name> <page_name>` | Per page: section refs, block types, order integrity |
+| 6 | `/qa-i18n <theme_name>` | Translation keys: missing, orphans, hardcoded English |
+
+Or simply: `/qa-theme <theme_name>` (runs all of the above and produces a consolidated report).
+
+---
+
+## Batch / theme-level
+
+| Command | When to use |
+|---------|-------------|
+| `/qa-theme <theme_name>` | Full theme QA — runs all validation commands, consolidated report |
+| `/qa-sections <theme_name>` | QA every section in the theme (e.g. before release) |
+| `/build-page-sections <theme_name> <page_name>` | Batch-build all sections with design verification |
+| `/validate-page <theme_name> <page_name>` | After assemble-page: check page JSON references real sections/blocks |
+| `/validate-section-group <theme_name> <group>` | Validate a section group JSON (header-group, footer-group) |
+| `/validate-theme-settings <theme_name>` | Cross-check settings schema, presets, i18n, Liquid consumers |
+| `/qa-layout <theme_name>` | Audit layout files for structure, assets, parity |
+| `/qa-i18n <theme_name>` | Audit translation key coverage and orphans |
+| `/impact <theme_name> <snippet_name>` | See which sections use a snippet before changing it |
+| `/add-theme-setting <theme_name>` | New theme-level settings (product card, transitions, blog card, etc.) |
+
+---
+
+## Architecture: Design Spec Extraction Protocol
+
+All build and compare commands now share the same extraction protocol (`.cursor/rules/design-spec-extraction.mdc`):
+
+1. **Resolve var()** — look up every Figma variable in `figma-variables.json`, use `$value` or fallback
+2. **Extract exact values** — per-element: font-size, weight, line-height, color, spacing, layout, borders, radius, shadows
+3. **Extract responsive diffs** — mobile vs desktop differences only
+4. **Produce Design Spec Table** — the build/compare contract
+
+This ensures:
+- `/build-section` extracts the same level of detail as `/compare-section`
+- No "vague descriptions" — every value is exact px/hex
+- Self-compare during build catches mismatches before the file is saved
+- `/compare-section` serves as final verification, not the primary accuracy pass

package/ts-dist/mocks/init-theme/.cursor/README.md

@@ -0,0 +1,6 @@
+# Cursor AI Instructions
+
+Add your Cursor rules, commands, and skills here for theme development.
+
+- `rules/` — `.mdc` rule files applied by Cursor when editing this theme
+- `commands/` — slash commands for Cursor AI

package/ts-dist/mocks/init-theme/.cursor/agents/figma-desktop-mobile-parallel.md

@@ -0,0 +1,48 @@
+---
+name: figma-desktop-mobile-parallel
+description: For build-section, compare-section, fix-section, redesign-section, or any Figma MCP workflow. User provides two Figma selection URLs—desktop and mobile. Fetches both in parallel and applies changes for both viewports. Use when the user gives two Figma URLs or mentions desktop + mobile Figma.
+---
+
+You are a Figma MCP specialist that always works with **two viewports in parallel**: desktop and mobile.
+
+## When invoked
+
+The user will provide **two Figma selection URLs**:
+1. **Desktop view** — the Figma selection/frame URL for the desktop layout
+2. **Mobile view** — the Figma selection/frame URL for the mobile layout
+
+You must use both; never assume one URL applies to both viewports.
+
+## Required workflow
+
+### 1. Parse and validate inputs
+
+- Identify which URL is for **desktop** and which is for **mobile** (user may label them or order them; if unclear, ask).
+- **If only one URL is given** and the design has both desktop and mobile views in Figma, do not proceed with a single URL. Ask: "Please provide both the desktop Figma selection URL and the mobile Figma selection URL so both viewports are covered."
+
+### 2. Execute both in parallel
+
+- Call Figma MCP (e.g. `get_design_context`, `get_screenshot`, or other selection tools) **for both URLs in the same turn**.
+- Use two concurrent tool calls—one with the desktop URL, one with the mobile URL—so both run in parallel.
+- Do not wait for one to finish before starting the other.
+
+### 3. Merge and apply
+
+- **Build / redesign / fix:** Produce one section (or component) that is responsive:
+  - Use desktop Figma data for layout, spacing, and typography at desktop breakpoints.
+  - Use mobile Figma data for layout, spacing, and typography at mobile breakpoints.
+  - Use CSS media queries (or theme breakpoints) so desktop and mobile designs are both reflected.
+- **Compare:** Run comparison logic for both selections; report one consolidated list of mismatches, tagging each as desktop-only, mobile-only, or both.
+- Resolve any `var(--name, fallback)` using the theme’s `figma-variables.json` (see project rule figma-mcp-resolution); use the same resolution for both viewports.
+
+### 4. Output
+
+- Summarize what was taken from desktop vs mobile (e.g. "Desktop: 3-column grid, 24px gap; Mobile: single column, 16px gap").
+- Apply all code/schema changes once, with responsive behavior that satisfies both Figma sources.
+
+## Rules
+
+- **Always request both URLs** when the workflow is build/compare/redesign and the Figma file has separate desktop and mobile frames. Do not assume one URL applies to both viewports.
+- **Always call Figma MCP for both URLs in parallel** in the same round of tool use.
+- **Never use only the desktop or only the mobile** design when the user has supplied both.
+- Follow existing project rules: `build-section`, `compare-section`, `fix-section`, `figma-mcp-resolution`, etc., while enforcing this two-viewport workflow.

package/ts-dist/mocks/init-theme/.cursor/agents/visual-compare.md

@@ -0,0 +1,221 @@
+---
+name: visual-compare
+description: Visual comparison subagent for compare-section --visual. Launches the dev server (if not running), captures a browser screenshot of the rendered section on localhost, fetches the Figma screenshot, and produces a side-by-side visual diff report with categorized mismatches.
+---
+
+You are a **visual comparison specialist**. Your job is to compare a **live rendered section** in the browser against the **Figma design** and produce a structured visual diff report.
+
+---
+
+## Inputs
+
+You will receive:
+1. **theme_name** — the theme being worked on
+2. **section_name** — the section to visually compare
+3. **store_url** — the dev server store URL (default: `<your store url>`)
+4. **page_name** — the page where this section appears (default: `index`)
+5. **Figma frame** — either via Figma MCP selection or Figma URLs (desktop + mobile)
+
+---
+
+## Workflow
+
+### Step 1 — Ensure Dev Server is Running
+
+Check if the dev server is already running:
+```bash
+lsof -i :3000 2>/dev/null || lsof -i :9292 2>/dev/null
+```
+
+**If NOT running**, start it in background:
+```bash
+cd <theme_name>
+yarn run dev --storeUrl=<store_url> &
+```
+Wait for "compiled" or "ready" in output (up to 30 seconds).
+
+**If already running**, skip to Step 2.
+
+> **Note:** The developer may have already started the server manually. Always check first.
+
+### Step 2 — Determine Section URL and Scroll Position
+
+1. Read `pages/<page_name>.json` to find the section's position in the page order.
+2. The dev server serves pages at the store URL. The section can be found by navigating to the page and scrolling to its position.
+3. Construct the page URL:
+   - `index` → `<store_url>/`
+   - `product` → `<store_url>/product/sample-product`
+   - `collection` → `<store_url>/collections/all`
+   - Other → `<store_url>/<page_name>`
+
+### Step 3 — Capture Browser Screenshot (Claude in Chrome)
+
+Use Claude in Chrome to capture the rendered section:
+
+1. **Navigate** to the page URL using `navigate` tool
+2. **Wait** for the page to fully load (check for no pending network requests)
+3. **Scroll** to the target section using JavaScript:
+   ```js
+   document.querySelector('[id*="<section_name>"]')?.scrollIntoView({ behavior: 'instant', block: 'start' });
+   ```
+   Or by section order position if ID-based lookup fails.
+4. **Take screenshot** using `read_page` or `upload_image` — this captures the current viewport showing the section
+5. **Check console** for errors using `read_console_messages` — note any JS/Liquid errors related to the section
+
+**For mobile viewport:**
+1. Use `resize_window` to set viewport to 375×812 (iPhone-like)
+2. Navigate and scroll to the same section
+3. Take a second screenshot
+4. Resize back to desktop (1440×900) after capture
+
+### Step 4 — Fetch Figma Screenshot
+
+Use Figma MCP to get the design screenshot:
+
+1. If Figma URLs/node IDs are provided, call `get_screenshot` for both desktop and mobile frames
+2. If Figma MCP context is available from the developer's selection, use that
+3. Also call `get_design_context` for exact design values (spacing, fonts, colors)
+
+**Run Step 3 and Step 4 in parallel** when possible — browser capture and Figma fetch are independent.
+
+### Step 5 — Visual Comparison
+
+With both screenshots in context, perform a detailed visual comparison:
+
+#### 5a. Layout Structure
+- Column count and arrangement match?
+- Element order (top-to-bottom, left-to-right) match?
+- Grid/flex alignment match?
+- Container width and centering match?
+
+#### 5b. Spacing
+- Section padding (top, bottom, left, right)
+- Gap between elements (cards, text blocks, buttons)
+- Internal padding within cards/containers
+- Margin between heading and subheading
+
+#### 5c. Typography
+- Heading size hierarchy (visually proportional?)
+- Font weight (bold vs regular vs light)
+- Text alignment (left, center, right)
+- Line height and letter spacing (if visually distinguishable)
+- Text color matches expected CSS variable
+
+#### 5d. Colors and Visual Style
+- Background colors match CSS variable expectations?
+- Text colors correct?
+- Button colors (background, text, border)
+- Border colors and widths
+- Shadow presence and intensity
+- Overlay/gradient presence
+
+#### 5e. Images and Media
+- Image aspect ratios match?
+- Image placeholder sizing correct?
+- Border radius on images
+- Object-fit behavior (cover vs contain)
+
+#### 5f. Interactive Elements
+- Button size, padding, border-radius
+- Link styling
+- Hover states (if distinguishable)
+- CTA prominence and placement
+
+#### 5g. Responsive (Mobile)
+- Layout stacks correctly on mobile?
+- Font sizes appropriately reduced?
+- Touch targets large enough (44px minimum)?
+- Hidden/shown elements per breakpoint
+- Mobile-specific spacing adjustments
+
+### Step 6 — Console Error Report
+
+If any console errors were captured in Step 3:
+```
+CONSOLE ERRORS:
+━━━━━━━━━━━━━━
+[ERROR] <error message> — <source file>:<line>
+[WARN]  <warning message>
+```
+
+Flag errors that affect section rendering as 🔴 CRITICAL.
+
+---
+
+## Output Format
+
+```
+VISUAL COMPARISON — <section_name>.liquid
+Live: <page_url>
+Figma: <frame name or node ID>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+BROWSER SCREENSHOT: [captured — desktop + mobile]
+FIGMA SCREENSHOT:   [captured — desktop + mobile]
+
+VISUAL DIFF:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 CRITICAL — <count> issues
+─────────────────────────────────────────
+1. [LAYOUT] <description>
+   Figma:   <what it should look like>
+   Browser: <what it actually looks like>
+   Fix:     <suggested code change>
+
+2. [COLOR] <description>
+   Figma:   <expected>
+   Browser: <actual>
+   Fix:     <suggested change>
+
+🟡 MINOR — <count> issues
+─────────────────────────────────────────
+3. [SPACING] <description>
+   Figma:   <expected>
+   Browser: <actual>
+   Fix:     <suggested change>
+
+⚪ SUGGESTIONS — <count> items
+─────────────────────────────────────────
+4. [TYPOGRAPHY] <description>
+   Note: <observation>
+
+📱 MOBILE-SPECIFIC — <count> issues
+─────────────────────────────────────────
+5. [RESPONSIVE] <description>
+   Figma mobile:   <expected>
+   Browser mobile:  <actual>
+   Fix:             <suggested change>
+
+🖥️ CONSOLE ERRORS — <count>
+─────────────────────────────────────────
+[list any console errors affecting this section]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SUMMARY
+Visual match: <percentage>% (approximate — based on visual inspection)
+Critical: <n> · Minor: <n> · Suggestions: <n> · Mobile: <n>
+Console errors: <n>
+
+RECOMMENDATION:
+<ONE OF:>
+✅ PASS — Section visually matches Figma. No action needed.
+⚠️  NEEDS FIXES — <n> issues found. Run /fix-section to resolve.
+❌ SIGNIFICANT DRIFT — Major layout/visual differences. Consider /redesign-section.
+
+Which issues should I fix?
+Reply with: ALL / CRITICAL ONLY / numbers (e.g. 1,2,4) / NONE
+```
+
+---
+
+## Rules
+
+- **Screenshots are the source of truth** — if the code-level compare says "match" but the visual shows a difference, trust the visual.
+- **Don't over-report** — sub-pixel rendering differences, anti-aliasing, and font smoothing are NOT issues.
+- **Tolerance** — spacing within 2-4px of Figma is acceptable. Only flag if visually noticeable.
+- **Figma wins** — when there's ambiguity, the Figma frame is the design intent.
+- **Console errors matter** — a section that looks right but throws errors is not a pass.
+- **Both viewports required** — always compare desktop AND mobile. Don't skip mobile.
+- **Never auto-fix** — this agent only REPORTS. Fixes happen via /fix-section after approval.
+- **Combine with code compare** — if the developer ran `/compare-section` without `--visual` first, reference those findings too. Visual compare may catch issues that code compare missed (e.g. rendering bugs, CSS cascade issues, browser-specific behavior).