@zohofinance/commerce 1.0.0 → 1.1.0

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

@@ -0,0 +1,307 @@
+---
+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 using **Level 0 → A → B** agent hierarchy (`agent-hierarchy.md`). Level 0 discovers pages; Level A identifies sections and spawns Level B per section; Level B builds from **section Figma node only** with lint + visual verify; Level A assembles page JSON and runs whole-page visual compare.
+
+## Usage
+```
+/build-theme <theme_name> <figma_file_key> [<root_node_id>]
+```
+
+Provide the Figma file URL or key. The root node is optional — if omitted, the whole canvas is scanned.
+
+---
+
+## Phase 0 — Discover Figma Structure
+
+### 0a. Fetch the root canvas
+Call `get_design_context` on the root node (or canvas) with `clientLanguages: "html,css,liquid"` and `clientFrameworks: "tailwind"`.
+
+The response will be a sparse metadata tree. Extract the **top-level sections** — these follow a standard naming convention:
+
+| Expected section   | Contains                                                        |
+|--------------------|-----------------------------------------------------------------|
+| **Guidelines**     | Typography (fonts, headings H1–H6, body), Colours, Components  |
+| **Website View**   | One child frame per page — desktop (≈ 1496px wide)             |
+| **Mobile View**    | One child frame per page — mobile (≈ 390px wide)               |
+| **Theme Settings** | Customizer UI mockups (informational only)                      |
+
+If any of these are missing, log a warning but continue with whatever is available.
+
+### 0b. Build the page map
+From **Website View**, list every direct child frame. Each is a page. Match by name to their **Mobile View** counterpart.
+
+Produce a page map:
+
+```
+PAGE MAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Page Name             | Desktop Node | Mobile Node  | Page JSON
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Home Page             | 2613:146     | 2375:4029    | index.json
+Product Detail Page   | 2321:4829    | 2560:1012    | product.json
+Blog Page             | 2344:5667    | 2568:1434    | blog.json
+Collection Page       | 2375:2752    | 2568:2220    | collection.json
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Map page names to standard page JSON filenames (`index.json`, `product.json`, `blog.json`, `collection.json`, etc.).
+
+---
+
+## Phase 1 — Scaffold Theme
+
+Run the `/create-theme` logic:
+
+1. Validate the target theme folder does not already exist (or confirm overwrite).
+2. Use this theme's current files as the template — do not look outside this directory for other themes.
+3. Create the full folder structure (assets, i18n, layouts, sections, snippets, pages, settings, etc.).
+4. Copy snippets, layouts, settings, and config files from this theme's existing files.
+5. Update `package.json` and `project.json` name fields.
+
+If the theme folder already exists, ask the user whether to continue with the existing folder or abort.
+
+---
+
+## Phase 2 — Extract Global Styles from Guidelines
+
+### 2a. Fetch the Guidelines section
+Call `get_design_context` on the **Guidelines** section node. This frame contains:
+
+- **Typography** — Heading font family, Body font family, H1–H6 sizes/line-heights, Body text specs.
+- **Colour** — Primary, Secondary, Neutral, Error, Success, Warning, Link, Background 1, Background 2, Border.
+- **Component specs** — Tooltip, Breadcrumb, Badge, Buttons (padding, font, border-radius).
+
+### 2b. Extract tokens — EXACT VALUES ONLY
+From the Guidelines frame, extract all design token values as exact px/hex numbers.
+Cross-reference with `figma-variables.json` if it exists.
+Follow the Design Spec Extraction Protocol in `.cursor/rules/design-spec-extraction.mdc`.
+
+Build a **token summary** with exact values:
+
+```
+GLOBAL TOKENS EXTRACTED
+━━━━━━━━━━━━━━━━━━━━━━━
+TYPOGRAPHY
+  Heading font: [font name] [weight]
+  Body font:    [font name] [weight]
+  H1: [size]px / [line-height]px → text-[size] / leading-[lh]
+  H2: [size]px / [line-height]px → text-[size] / leading-[lh]
+  H3: [size]px / [line-height]px → text-[size] / leading-[lh]
+  H4: [size]px / [line-height]px → text-[size] / leading-[lh]
+  H5: [size]px / [line-height]px → text-[size] / leading-[lh]
+  H6: [size]px / [line-height]px → text-[size] / leading-[lh]
+  Body: [size]px / [line-height]px → text-[size] / leading-[lh]
+  Small: [size]px / [line-height]px → text-[size] / leading-[lh]
+
+COLOURS
+  Primary:      [hex] → var(--color-primary)
+  On-Primary:   [hex] → var(--color-on-primary)
+  Secondary:    [hex]
+  Neutral:      [hex]
+  Error:        [hex]
+  Success:      [hex]
+  Warning:      [hex]
+  Link:         [hex]
+  Heading:      [hex] → var(--color-heading)
+  Body text:    [hex]
+  Background 1: [hex] → var(--color-background)
+  Background 2: [hex]
+  Border:       [hex] → var(--color-border)
+
+COMPONENTS
+  Button padding:  [top]px [right]px [bottom]px [left]px → py-[n] px-[n]
+  Button radius:   [value]px → rounded-[class]
+  Button font:     [size]px [weight] → text-[class] font-[class]
+  Badge padding:   [value]px → p-[n]
+  Badge radius:    [value]px → rounded-[class]
+```
+
+### 2c. Populate theme settings
+Using the extracted tokens, update:
+
+- `settings/schema.json` — ensure all colour, typography, and component settings have correct defaults matching the Figma guidelines.
+- `settings/theme.json` — fill the Default preset with the extracted token values.
+- `i18n/en.schema.json` — ensure all translation keys for settings exist.
+
+Verify by running `/validate-theme-settings` logic internally (do not output a separate report — just fix any mismatches).
+
+### 2d. Save Global Token Reference
+Save the token summary to `.design-tokens-summary.md` for reference during section builds. This file ensures every section build has access to the global typography and colour decisions.
+
+---
+
+## Phase 3 — Developer approval (Level 0)
+
+Present the page map from Phase 0. Ask:
+
+```
+Does this page map look correct?
+- Reply YES to start Stage 1 (Level A agents)
+- Reply EDIT to adjust page names or node IDs
+```
+
+**Wait for approval.** Level 0 does not build sections.
+
+---
+
+## Phase 4 — Stage 1: Level A → Level B (see `parallel-fanout.md`)
+
+**Architecture:** `.claude/skills/theme-from-figma/agent-hierarchy.md`
+
+### 4a. Index Level A (serial)
+Spawn one **Level A** for `index`. It:
+1. Calls `get_design_context` on the **page frame** (desktop + mobile)
+2. Writes `sections.plan.md` with Figma node ID per section
+3. Spawns **Level B** per section in parallel (header, footer, hero, …)
+4. Waits for all Level B PASS
+5. Assembles `pages/index.json`
+6. Whole-page visual verify vs Figma home frame
+7. Writes `header-footer-ready` marker
+
+### 4b. Four parallel Level A agents
+After marker, spawn Level A for `listing`, `product`, `blog_list`, `blog_detail`.
+
+Each Level A follows `page-orchestrator.md`. Each Level B follows `section-builder.md`.
+
+### Level B per-section gates (mandatory)
+1. `get_design_context` on **section node ID only** — NOT parent page (`figma-extraction.md`)
+2. `figma-spec.json` with every visual value (`transcription-rules.md`)
+3. `lint-section.mjs` PASS
+4. Chrome DevTools visual vs Figma **section crop** — `visual-diff.md` 0 CRITICAL
+
+### Anti-hallucination (fixes border-radius, colors, card heights)
+- No `rounded-*` unless spec `border_radius > 0`
+- Colors from spec → token map only
+- Product grids: fixed media box `w`×`h` + `object-fit`
+- Heading blocks / title fields → `text` only; body/description → `richtext`
+
+### Progress tracking
+Each Level B writes to scratchpad:
+
+```
+pages/<page>/sections/<section>/
+  figma-spec.json
+  visual-diff.md
+  report.md
+```
+
+Each Level A writes:
+
+```
+pages/<page>/
+  sections.plan.md
+  report.md
+```
+
+---
+
+## Phase 5 — Stage 2: Consolidation
+
+1. Run `verify-theme.mjs <theme_name>`
+2. Run `record-build-metrics.mjs`
+3. Cross-page token consistency check
+4. Collect all Level A/B `report.md` + `visual-diff.md` files
+
+Page JSON assembly happens inside each Level A — not in a separate phase.
+
+---
+
+## Phase 6 — QA summary
+
+Aggregate from Level B reports:
+- Sections with 0 CRITICAL visual diff
+- Sections NEEDS_REVIEW
+- Lint failures
+- Unmapped colors (`unmapped-colors.md`)
+
+Auto-fix only cross-cutting i18n gaps. Section visual issues → re-spawn Level B for that section.
+
+---
+
+## Phase 7 — Design accuracy summary
+
+```
+DESIGN ACCURACY SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Sections built: <n>
+Level B PASS (0 CRITICAL): <n>
+Level B NEEDS_REVIEW: <n>
+Whole-page Level A PASS: <n>/<total pages>
+
+COMMON FAILURE PATTERNS (should be 0 with transcription-rules.md):
+  rounded-* without Figma radius: <n>
+  unmapped colors: <n>
+  product grids without fixed media box: <n>
+```
+
+---
+
+## Output — Final Report
+
+```
+BUILD THEME — <theme_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SOURCE: Figma file <figma_file_key>
+
+GLOBAL TOKENS
+  Heading font: [name]  |  Body font: [name]
+  Primary: [hex]  |  Secondary: [hex]  |  Neutral: [hex]
+  ...
+
+PAGES BUILT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Page                | Sections | Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Home (index.json)   | 8        | ✅ complete
+Product (product)   | 5        | ✅ complete
+Blog (blog)         | 4        | ✅ complete
+Collection          | 3        | ✅ complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SECTIONS BUILT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  | Section               | Status  | Spec Match | Reference
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1  | header                | SKIPPED | —          | shared snippet
+2  | hero-banner           | BUILT   | 100%       | sections/hero-banner.liquid
+3  | product-carousel      | BUILT   | 97%        | sections/product-carousel.liquid
+4  | ...                   | ...     | ...        | ...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Built: <n>  |  Skipped: <n>  |  Failed: <n>
+
+DESIGN ACCURACY: <overall_percentage>% spec match
+
+QA SUMMARY
+  Sections:   <n> clean  |  <n> with warnings
+  Settings:   ✅ / ⚠️
+  Layouts:    ✅ / ⚠️
+  Pages:      ✅ / ⚠️
+  i18n:       ✅ / ⚠️
+
+⚠️ ITEMS REQUIRING DEVELOPER ATTENTION:
+  1. [severity] [file]: [description]
+  2. ...
+
+NEXT STEPS:
+  1. Review unresolved items above
+  2. /compare-section <theme_name> <section>  — only if unresolved items exist
+  3. /qa-theme <theme_name>                   — full QA after any manual fixes
+  4. npx @zohofinance/commerce theme dev --storeUrl=<your store url>  — preview in browser (live store data; omit `--storeUrl` for mock only)
+```
+
+---
+
+## Notes
+
+- This command now includes integrated design verification. The self-compare step in each section build eliminates most issues that previously required separate compare→fix iterations.
+- Figma MCP has context limits per frame. If a page frame is too large, this command automatically splits it into individual section frames and fetches them separately.
+- The only required pause point is Phase 3 (audit plan approval). All other phases run continuously.
+- If `figma-variables.json` is missing, the command still runs but logs warnings for every unresolved token. Add the file later and re-run `/sync-theme-settings`.
+- Section groups, page JSON, and i18n are all generated — the developer does not need to create any JSON files manually.
+- The `.design-tokens-summary.md` file is an internal reference — it can be deleted after the theme is complete.

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

@@ -0,0 +1,358 @@
+---
+
+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.
+
+This command uses the same Design Spec Extraction Protocol as /build-section,
+ensuring consistency between what was built and what is verified.
+
+## Usage
+```
+/compare-section <theme_name> <section_name> [figma_node_id]
+/compare-section <theme_name> <section_name> --visual [--page <page_name>] [--store-url <url>]
+```
+
+`figma_node_id` is optional. If not provided, Claude will look it up automatically.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--visual` | Enables visual browser comparison mode. Launches/connects to the dev server, captures browser screenshots of the rendered section, fetches Figma screenshots, and produces a side-by-side visual diff report. |
+| `--page <name>` | Page where the section appears (default: `index`). Used with `--visual` to navigate to the correct page. |
+| `--store-url <url>` | Dev server store URL (default: `<your store url>`). |
+
+### Modes
+
+**Default mode (code compare):** Extracts values from code and Figma MCP data, compares numerically. Fast and precise for CSS/Tailwind property matching.
+
+**Visual mode (`--visual`):** Launches the `visual-compare` subagent (see `.cursor/agents/visual-compare.md`). This mode:
+1. Ensures the dev server is running (`npx @zohofinance/commerce theme dev --storeUrl=<your store url>` — from `--store-url` / `dev-config.json`; without `--storeUrl`, preview uses mock data only)
+2. Uses Claude in Chrome to navigate to the page and screenshot the rendered section (desktop + mobile)
+3. Fetches the Figma screenshot via Figma MCP (`get_screenshot`)
+4. Visually compares both screenshots and reports differences
+5. Also checks the browser console for JS/Liquid errors
+
+**Combined mode (recommended for final QA):** Run both:
+```
+/compare-section <theme_name> <section_name>           → code-level compare
+/compare-section <theme_name> <section_name> --visual  → visual compare
+```
+Code compare catches precise CSS mismatches; visual compare catches rendering bugs, cascade issues, and browser-specific behavior that code compare cannot detect.
+
+---
+
+## 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` — token values for this theme
+4. `.cursor/rules/css.mdc` — Figma → Tailwind conversion table
+5. `.cursor/rules/design-spec-extraction.mdc` — extraction protocol
+
+Never ask the developer to paste file contents — read them directly.
+
+---
+
+## 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 frame in Figma first,
+then runs this command in Cursor.
+
+**Do NOT say "no Figma data available" without first checking MCP context.**
+
+The MCP frame data is already in your context if the developer had a frame selected.
+Look for it — it will contain layout, typography, color, and spacing values for the frame.
+
+If no Figma MCP context is present in the conversation:
+```
+⚠️ 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
+```
+
+Never silently skip the comparison and say "no issues found".
+
+---
+
+
+## Stage 1 — Extract Code Values
+
+From the section file and its snippets, extract current values for EVERY element:
+
+**Typography** (per text element)
+- Tailwind text class (font-size)
+- Font weight class
+- Line height classes if present
+- Letter spacing classes if present
+- Text colour (CSS variable used)
+- Text alignment
+
+**Spacing** (per container)
+- Section padding top/bottom (from {% style %} block or range default)
+- Padding inside containers (all four sides)
+- Gap between elements (flex/grid gap classes)
+- Margin between text blocks
+
+**Layout** (per container)
+- Grid column count at each breakpoint
+- Flex direction and alignment
+- Element order
+- Max-width container class
+
+**Visual** (per element)
+- Border radius classes on each element
+- Border classes (width, colour)
+- Shadow classes
+- Background colour (CSS variable or Tailwind bg class)
+
+**Images** (per image)
+- Aspect ratio classes
+- Object-fit classes
+- Width/height constraints
+- Border radius
+
+**Buttons / CTAs** (per button)
+- Padding classes (vertical and horizontal)
+- Border radius
+- Font size and weight
+- Background and text colour
+- Border if any
+
+**Produce a structured list** matching the Design Spec Table format (element → property → value).
+
+---
+
+
+## Stage 2 — Extract Figma Values Using Design Spec Extraction Protocol
+
+Follow `.cursor/rules/design-spec-extraction.mdc` EXACTLY:
+
+### 2a. Resolve ALL var() values first
+For every `var(--name, fallback)` in the MCP data:
+- Look up in `figma-variables.json` by path
+- Use `$value` if present, fallback otherwise
+- Never use variable names for comparison
+
+### 2b. Extract per-element design spec
+Extract EXACT resolved values for every visible element — same format as Stage 1.
+Produce the Design Spec Table with columns: Element | Property | Figma Value | Tailwind/CSS.
+
+### 2c. Extract responsive differences
+If mobile frame available, note what differs from desktop.
+
+Do NOT compare a variable name like `--font-size-9xl` against a Tailwind class —
+that comparison is meaningless. Only compare resolved px/hex values against code values.
+
+---
+
+
+## Stage 3 — Compare and Classify
+
+For EVERY property in the Design Spec Table, compare Figma value vs code value.
+
+Classify each mismatch:
+
+**🔴 CRITICAL**
+Clearly visible to any user. Blocks sign-off.
+- Wrong font size (more than one Tailwind step off)
+- Wrong font weight (bold vs regular)
+- Wrong colour (wrong CSS variable or hardcoded value)
+- Wrong column count
+- Wrong element missing entirely
+- Wrong element order
+- Missing responsive override (desktop layout on mobile)
+
+**🟡 MINOR**
+Noticeable on close inspection. Should fix before launch.
+- Spacing off by one Tailwind step (e.g. gap-4 vs gap-6)
+- Border radius one step off (rounded-lg vs rounded-xl)
+- Line height mismatch
+- Letter spacing mismatch
+- Shadow missing or too strong
+- Image aspect ratio off
+- Padding defaults don't match Figma section padding
+
+**⚪ SUGGESTION**
+Subtle. Developer judgement call — may be intentional.
+- Spacing off by less than 4px
+- Font weight one step off (medium vs semibold)
+- Colour slightly different due to opacity
+- Responsive behaviour differs from Figma mobile frame
+- Hover state not implemented
+
+Do NOT report items that match correctly — only report mismatches.
+If a value was not specified in Figma, do not flag it.
+
+---
+
+
+## Stage 4 — Check Responsive
+
+If a Figma mobile frame is provided, compare:
+- Column count on mobile vs desktop
+- Font size changes at mobile breakpoint
+- Stacking order of elements
+- Hidden/shown elements per breakpoint
+- Touch target sizes on buttons (minimum 44px)
+- Gap/padding changes at mobile breakpoint
+
+---
+
+
+## Output Format
+
+```
+DESIGN COMPARISON — <section_name>.liquid
+vs Figma: <frame name if known>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DESIGN SPEC TABLE (what Figma specifies):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  | Element          | Property        | Figma Value        | Expected Tailwind/CSS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[full spec table here]
+
+MISMATCHES:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 CRITICAL — <count> issues
+─────────────────────────────────────────
+1. <Property>
+   Figma:  <expected value>
+   Code:   <actual value> — <file>:<line>
+   Fix:    <exact change to make>
+
+2. <Property>
+   Figma:  <expected value>
+   Code:   <actual value> — <file>:<line>
+   Fix:    <exact change to make>
+
+🟡 MINOR — <count> issues
+─────────────────────────────────────────
+3. <Property>
+   Figma:  <expected value>
+   Code:   <actual value> — <file>:<line>
+   Fix:    <exact change to make>
+
+⚪ SUGGESTIONS — <count> items
+─────────────────────────────────────────
+4. <Property>
+   Figma:  <expected value>
+   Code:   <actual value>
+   Note:   May be intentional — confirm with designer
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SUMMARY
+Files checked: <section_name>.liquid + <list of snippets>
+Critical: <n> · Minor: <n> · Suggestions: <n>
+Design accuracy: <percentage>% (matched / total spec rows)
+
+Which issues should I fix?
+Reply with: ALL / CRITICAL ONLY / numbers (e.g. 1,2,4) / NONE
+```
+
+- If the user said **"Implement this design from Figma"** or **"Apply all"**, treat as **ALL** and apply all reported fixes, then run `/qa-section <theme_name> <section_name>` to verify.
+- Wait for developer approval before making any changes unless the user explicitly asked to apply all.
+
+---
+
+
+## Stage 5 — Apply Approved Fixes
+
+Once developer specifies which issues to fix:
+
+- Apply ONLY the approved fixes
+- For each fix, reference the issue number in a comment:
+  `{{-- compare-fix #1: text-4xl → text-5xl to match Figma spec --}}`
+- Do not touch anything not in the approved list
+- Do not refactor, reorganise, or improve other areas
+
+After applying:
+
+```
+✅ FIXES APPLIED
+
+Fixed: #<n>, #<n>, #<n>
+Skipped: #<n>, #<n> (not approved)
+
+Files changed:
+- sections/<section_name>.liquid
+- snippets/<snippet>.liquid (if applicable)
+
+Design accuracy after fix: <percentage>%
+
+NEXT: Run /qa-section <theme_name> <section_name> to verify no regressions
+```
+
+---
+
+
+## Visual Mode (`--visual`)
+
+When the `--visual` flag is provided, delegate to the **visual-compare** subagent:
+
+1. **Read the agent spec:** `.cursor/agents/visual-compare.md`
+2. **Pass inputs:**
+   - `theme_name`, `section_name` from the command arguments
+   - `page_name` from `--page` flag (default: `index`)
+   - `store_url` from `--store-url` flag (default: `<your store url>`)
+   - Figma frame data (from MCP context or provided URLs)
+3. **The subagent will:**
+   - Check/start the dev server
+   - Navigate Claude in Chrome to the rendered page
+   - Screenshot the section at desktop (1440px) and mobile (375px) viewports
+   - Fetch Figma screenshots via `get_screenshot`
+   - Compare visually and produce a categorized diff report
+   - Check the browser console for errors
+4. **Output** follows the visual-compare agent's report format (visual diff with CRITICAL/MINOR/SUGGESTION/MOBILE-SPECIFIC categories)
+
+### Prerequisites for Visual Mode
+
+- **Claude in Chrome** must be available (for browser navigation and screenshots)
+- **Figma MCP** must be connected (for `get_screenshot` and `get_design_context`)
+- **Dev server** must be running OR the subagent will attempt to start it
+- The section must already be built and saved to the theme's `sections/` folder
+- The page JSON must reference this section (so it renders on the page)
+
+### When to use Visual Mode
+
+- After initial `/compare-section` (code compare) passes but you want visual confirmation
+- When debugging a section that "looks wrong" but code values seem correct
+- For final QA before shipping — visual compare catches CSS cascade issues, z-index problems, overflow clipping, and browser rendering quirks that code compare cannot detect
+- When the Figma design has subtle visual details (gradients, shadows, overlapping elements) that are hard to verify from code alone
+
+---
+
+
+## Figma MCP fallback
+
+If Figma MCP context is not available, ask: "Figma MCP data not found. You can paste a structured design spec (e.g. spacing, typography, colours, CTA dimensions) and I'll compare against the section code." Then run the same comparison logic using the pasted spec.
+
+---
+
+
+## Notes
+
+- If Figma input is a screenshot, flag all extracted values with ~ to indicate they are estimates
+- If a value cannot be determined from Figma input, skip that check — do not guess
+- If the same mismatch appears in a shared snippet used by multiple sections, note it once and flag that fixing it affects all sections that use that snippet
+- Never change schema fields or Liquid logic — this command is HTML/CSS only
+- If a mismatch looks intentional (e.g. a responsive adaptation), flag as suggestion with note rather than critical
+- The Design Spec Table in the output gives the developer a complete reference of what Figma specifies, making it easier to review and approve fixes