@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: theme-from-figma
+description: Build a complete ZCommerce Liquid theme from a Figma file in a single command. Provide theme name + figma file key; the agent auto-discovers pages via get_metadata (Website View / Mobile View). Fans out parallel page-agents with Chrome DevTools MCP visual verify. Use for "build a new theme", "create a theme from Figma", "/build-theme". Per-page URLs are fallback only when discovery fails. Single entry point — replaces archived zcommerce-theme-builder and zcommerce-section-from-design skills.
+---
+
+# theme-from-figma — one command, Level 0 → A → B hierarchy, verified output
+
+This is the only skill developers need for theme construction. It uses a **three-level agent hierarchy** (see `agent-hierarchy.md`): Level 0 discovers pages and bootstraps; Level A identifies sections per page and spawns Level B; Level B builds **one section from its Figma node only** and verifies lint + visual before Level A assembles the page.
+
+## How accuracy is achieved — four non-negotiables
+
+Earlier versions produced themes structurally similar to Figma but visually far off. Four rules fix that:
+
+1. **Per-element Figma extraction, not imagination.** Every section is built from `figma-spec.json` via `get_design_context` on the section's Figma node. See `figma-extraction.md`.
+
+2. **Chrome DevTools MCP visual verify on every section AND every page.** Mandatory 3-gate loop: visual screenshot diff + `lighthouse_audit` a11y + perf baseline. See `visual-verify-loop.md` and `.cursor/skills/browser-verify.md`. A section without `visual-diff.md` showing **0 CRITICAL** does not ship.
+
+3. **Correct image `src` in dev.** Schema JSON stores filenames — always pipe theme assets through `asset_url`. Product CDN URLs use `?organization_id=`. See `image-sources.md`. Check `list_network_requests` for 404s during visual verify.
+
+4. **Simple, reliable code.** Transcribe the Figma spec into straightforward Liquid + scoped `{% style %}`. No over-engineered conditionals. Lint at write time; fix CRITICAL visual items only in re-loops (max 3 per section).
+
+`verify-theme.mjs` + `record-build-metrics.mjs` run at Stage 2. Every build ends with time/token insights in `report.md`. See `build-metrics.md`.
+
+## Official ZCommerce docs — bundled at `zcommerce-docs/`
+
+This skill ships with the complete official ZCommerce theme documentation. **The docs are the source of truth for anything not explicitly handled by this skill** — Liquid filters, schema field types, global objects, layout primitives, asset filters, i18n filter semantics, best practices.
+
+| When you need to know… | Read |
+|---|---|
+| What Liquid filters exist and how to use them | `zcommerce-docs/reference/filters.md` |
+| What `{% schema %}` field types are valid and their default formats | `zcommerce-docs/reference/schema-types.md` |
+| What global Liquid objects are available (`organization`, `pageinfo`, `cart`, `product`, etc.) | `zcommerce-docs/reference/global-objects.md` |
+| What Liquid tags work (only 13 — no `paginate`, `form`, `javascript`, etc.) | `zcommerce-docs/reference/tags.md` |
+| Required folder layout and naming | `zcommerce-docs/theme-structure.md` |
+| Layout file conventions (`theme.liquid`, `content_for_*`) | `zcommerce-docs/layouts.md` |
+| Section + block anatomy | `zcommerce-docs/sections.md` |
+| Snippet rules + variable scoping | `zcommerce-docs/snippets.md` |
+| Page JSON contract | `zcommerce-docs/pages.md` |
+| Asset filter + fingerprint.json | `zcommerce-docs/assets.md` |
+| i18n key conventions | `zcommerce-docs/i18n.md` |
+| Performance / security / a11y / deploy checklist | `zcommerce-docs/best-practices.md` |
+| CLI commands + `?format=json` data inspection | `zcommerce-docs/setup-guide.md` |
+| Custom JS integration patterns | `zcommerce-docs/custom-scripts.md` |
+
+Agents should consult these docs **before inventing patterns**. The most common bug from the v5 build (`{% paginate %}` crashing) came from an agent extrapolating from Shopify knowledge instead of reading `reference/tags.md` which explicitly lists what's supported.
+
+## TL;DR — what the developer types
+
+**Preferred (auto-discovery):**
+```
+/build-theme <theme_name> <figma_file_key> [<root_node_id>]
+```
+
+Example: `/build-theme my_theme <figma_file_key>`
+
+The agent calls Figma MCP `get_metadata` on the theme canvas, finds **Website View** + **Mobile View** children, and builds the page map **without asking for per-page URLs**. See `figma-discovery.md`.
+
+**Optional** — paste per-page URLs only if discovery fails or the file is non-standard:
+```
+build theme {theme_name}
+  figma_file: {file_key_or_url}
+  pages:  (fallback only)
+    index: {figma_url}
+    ...
+```
+
+Selecting a frame in Figma before running the command is a **hint** for which page you're focused on — it does **not** replace canvas discovery. The agent still walks the full file.
+
+Optional override clause for brand changes that post-date the Figma file:
+```
+override:
+  primary  = #4A1525
+  body_font = "Inter"
+```
+
+**Never** ask for per-page Figma URLs when `figma_file_key` was provided and discovery succeeded. **Never** ask for token values — they live in the guidelines frame. **Never** ask which theme to use as a reference. See `figma-discovery.md`, `inputs/guidelines-frame.md`, `exemplars.md`.
+
+---
+
+## The pipeline — Level 0 → A → B
+
+See `agent-hierarchy.md` for the full spec. Summary:
+
+```
+LEVEL 0  Main orchestrator (serial)
+   ├─ figma-discovery.md → page map from file key
+   ├─ bootstrap.md → tokens + dev-config.json
+   └─ developer approves page map
+
+LEVEL A  Page orchestrator — one per page (index first, then parallel)
+   ├─ identify sections + Figma node ID each → sections.plan.md
+   ├─ does NOT write section Liquid
+   ├─ spawn LEVEL B in parallel (one per section)
+   ├─ assemble pages/<page>.json after all B pass
+   └─ whole-page visual verify vs Figma PAGE frame
+
+LEVEL B  Section builder — one per section
+   ├─ get_design_context on SECTION node only (not parent page)
+   ├─ figma-spec.json → transcribe → sections/<name>.liquid
+   ├─ transcription-rules.md (no radius/colors unless in spec)
+   ├─ lint-section.mjs (syntax)
+   └─ Chrome DevTools visual verify vs Figma SECTION crop
+
+Stage 2  Consolidation — verify-theme.mjs + build-metrics.md
+```
+
+**Why two levels:** Level B scope = one Figma section → less hallucination (wrong border-radius, wrong colors, uneven product card heights). Level A only assembles and checks inter-section layout.
+
+Read each `.md` file referenced above before executing that stage. The files are short — they exist precisely to keep this entry doc light.
+
+---
+
+## Preconditions (auto-checked at start)
+
+The skill runs these checks before Stage 0. If any fail, stop and surface to the user with a one-line fix.
+
+1. **Ask developer for `storeUrl`.** Do not hardcode a demo store. Record in `dev-config.json`. See `dev-server-and-urls.md`.
+2. **Confirm page URLs before any browser navigation.** Home is often `/home` not `/`. Product/collection handles vary by store. Ask once; write confirmed URLs to `dev-config.json`.
+3. **Dev server.** Ask developer to start it, or start it yourself: `yarn run dev --storeUrl=<confirmed>`. Notify developer either way.
+4. **`npx @zohofinance/commerce --version` works from inside the theme folder.** If not, run `npm install @zohofinance/commerce` in the theme directory.
+5. **Figma MCP authenticated.** Otherwise: ask user to open Figma desktop with the first frame selected.
+6. **Chrome DevTools MCP available** (`.cursor/mcp.json`). See `.cursor/skills/browser-verify.md`.
+7. **Theme name is valid.** Snake-case. If folder exists, ask whether to continue or pick a new name.
+8. **Subagent escalation.** All page/section agent questions and blockers surface on the main agent screen. See `subagent-escalation.md`.
+
+---
+
+## Core principle — never copy design from another theme
+
+There is no "base theme" in the design sense. Every theme is its own product with its own colors, fonts, spacing, radius, and visual flavour. Pulling design decisions from sibling themes — even subconsciously, even "for inspiration" — produces wrong output every time.
+
+What CAN be referenced from sibling themes:
+- **Liquid logic patterns** — how a `{% for %}` loop is structured, how a variant picker delegates to a snippet, how a `{% case %}` branches on block types.
+- **Schema patterns** — which `{% schema %}` field types are used, how defaults are formatted for url / image_picker / select, where blocks are introduced. **Heading/title fields → `text`; body/description → `richtext` (never `richtext` on heading blocks).**
+- **Snippet implementations** — how `add-to-cart.liquid` wires up `mcp__plugin_product-management_figma__*` (or `quantity-counter` web component), how `pagination.liquid` handles edge cases.
+- **JS / web-component usage patterns** — when a section uses `<dot-slider>`, `<expand-accordion>`, `<add-to-cart>`, etc.
+- **Accessibility patterns** — how a header implements skip-links, how a modal traps focus.
+- **i18n key patterns** — what kinds of keys live in en.json vs en.schema.json.
+- **File and folder conventions** — same across all themes.
+
+What CANNOT be referenced from sibling themes — must come from the developer's Figma + the theme's own tokens, never from another `.liquid` file, asset, or font:
+- **Assets** — images, logos, icons, hero/banner graphics, decorative SVGs. All must be extracted from the input Figma. Bootstrap leaves `assets/` empty (only `fingerprint.json`); page agents populate it. Hashing siblings' assets vs the new theme's catches violations (`verify-theme.mjs` → `assets_diverge`).
+- **Fonts** — font files. Reference Google Fonts via `<link>` for common faces, or download from the design system if proprietary. Never `.woff2` files copied from sibling themes.
+- Colors (anywhere, including hover/disabled states)
+- Typography (font family, weight, size, line-height)
+- Spacing (padding, margin, gap)
+- Border radius
+- Box shadows
+- Component visual style (button shape, card shadow, input border treatment)
+- Layout density / whitespace rhythm
+
+The lint script enforces this at the technical level — zero hardcoded hex, zero hardcoded inline px font-sizes, zero hardcoded inline px paddings. But the rule is also conceptual: when an agent reads a sibling theme's section file for reference, it reads for *how the logic flows*, not *what the design looks like*. Two themes can have the same Liquid skeleton and produce totally different visual outputs — that's the goal.
+
+## Failure modes this skill explicitly defends against
+
+Every safeguard below exists because the corresponding bug actually shipped in real-world builds. The defenses are mechanical (lint checks, verify-theme assertions) — not just docs.
+
+| Failure | Defense | Where enforced |
+|---|---|---|
+| **Header/footer copied or "retokenized" from a sibling theme** — index agent skipped Figma extraction. | Bootstrap does not create header.liquid/footer.liquid. Index agent must build them from the Figma. `verify-theme.mjs` `header_diverges` / `footer_diverges` checks fail the build if either file has > 70% normalized line similarity to ANY sibling theme's equivalent. | `bootstrap.md` §6 · `page-builder.md` "Special case" · `scripts/verify-theme.mjs` |
+| **Images/logos/icons reused from a sibling theme's `assets/`** — even with new .liquid, pages "looked like" the source theme because the visual assets were someone else's brand. | Bootstrap does NOT copy `assets/`. The folder starts empty (only `fingerprint.json`). Each page agent extracts assets from the Figma per `page-builder.md` "Asset extraction protocol". `verify-theme.mjs` `assets_diverge` check hashes every file in `assets/` and fails if any is byte-identical to a sibling. | `bootstrap.md` step 2 · `page-builder.md` "Asset extraction" · `scripts/verify-theme.mjs` |
+| **project.json / package.json `name` field unchanged** — every theme shipped with a default template name instead of the new theme's name. | Bootstrap sets `package.json` name to the **folder name** (snake_case) and `project.json` name to **kebab-case** (`my_theme` → `my-theme`). Both must include `prebuild`, `prebuild:dev`, and `dev` scripts matching the standard theme layout. | `bootstrap.md` step 6 · `scripts/verify-theme.mjs` |
+| **Invalid Liquid tag like `{% paginate %}`** — agent used Shopify-only tags the ZCommerce engine doesn't register; pages crashed at render time. | `lint-section.mjs` `liquid_tags_valid` check enforces an allow-list pulled from the bundled `zcommerce-docs/reference/tags.md` docs. Anything else fails the file. | `scripts/lint-section.mjs` |
+| **Runtime translation crash** — agent put schema-label keys in `en.schema.json` but used them at runtime via `\| t`, which only resolves against `en.json`. | `lint-section.mjs` `i18n_keys_resolve` check fails files where runtime `\| t` keys are missing from `en.json` or misplaced in `en.schema.json`, with a hint about which file the key should move to. | `scripts/lint-section.mjs` |
+| **Snippet variable scope bug** — snippet used bare `settings.X` (not `section.settings.X`), accessing a non-existent global. | `lint-section.mjs` `snippet_scope_sanity` check: failure when the file is a section, warning when it's a snippet (since snippets can legitimately receive `settings` as a render parameter). | `scripts/lint-section.mjs` |
+| **Verification skipped entirely** — agents reported "passed" without invoking the puppeteer scripts. | Page agent's output contract requires four JSON files in scratchpad. Stage-2 consolidator refuses to ship if any are missing. | `page-builder.md` Phase 5 · `verification.md` |
+| **Hardcoded hex / inline-px design values** snuck into copied common-page sections from a sibling theme. | `lint-section.mjs` `hardcoded_hex` and `hardcoded_inline_px` checks. `verify-theme.mjs` `no_hardcoded_design` aggregates across all .liquid files. | `scripts/lint-section.mjs` · `scripts/verify-theme.mjs` |
+| **Any `.liquid` file too similar to a sibling theme's** — agent copied or lightly-modified rather than exploring multiple themes and writing fresh. | `verify-theme.mjs` `all_sections_diverge` runs structural-similarity check on every section + snippet file. Fails if any has > 70% normalized line overlap with any sibling. | `scripts/verify-theme.mjs` |
+| **Extra section in `pages/<page>.json` that isn't in the Figma** (e.g., a "Why families pick us" / value-props block that the Figma doesn't show — agent added it from a sibling theme's template). | The page orchestrator's section-identification phase MUST produce a list that matches what's visually in the Figma frame and ONLY what's visually there. Any section in the Figma → add. Any section the agent "thinks would be useful" → reject. The `sections.plan.md` artefact in scratchpad lists each section's Figma node ID — if a planned section has no node ID, it shouldn't be in the page. | `page-orchestrator.md` §Phase 2 |
+| **Repeated placeholder content across multiple blocks** (e.g., three blog cards all titled "Where little hands find their bunny buddies"). | Block defaults in `pages/<page>.json` must be distinct per block instance. If the Figma shows three blog cards, the agent must transcribe each card's distinct title/excerpt/date into the corresponding block's settings — not leave `settings: {}` (which falls back to repeated schema defaults). | `page-orchestrator.md` §Phase 7 + new `verify-theme.mjs` check |
+| **Block settings left as `{}` in page JSON** — agent wrote schema with reasonable defaults but didn't transcribe Figma content into the page JSON, so every block falls back to the same schema default. | New `verify-theme.mjs` check `block_settings_populated`: scans every `pages/*.json`, fails if any block of a multi-block section has `"settings": {}` while sibling blocks of the same section have non-empty settings. Catches the "agent forgot to transcribe" pattern. | `scripts/verify-theme.mjs` |
+| **Repeating block defaults inside section schema** (e.g., all three "blog_post" block defaults set to the same title — so empty page JSON blocks all show the same content). | Schema defaults for repeating block types must either be (a) left blank/null so missing settings are visually obvious, or (b) authored as a progressive set (`post_1_default`, `post_2_default`, `post_3_default`). Lint check `schema_defaults_distinct`: when a block type appears multiple times in a page JSON's `block_order` with empty settings, the agent must populate distinct values OR the schema must use blank defaults. | `scripts/lint-section.mjs` |
+
+The skill SHIPS a theme only when `verify-theme.mjs` returns verdict PASS. Anything else is a bug to fix, not a tolerated deviation.
+
+## What this skill enforces that the old ones didn't
+
+1. **No `extract-tokens` command, no developer-supplied preset.** Token extraction is folded into Stage 0 — the agent reads the guidelines frame screenshot, extracts typography / colors / button states / component micro-specs via vision, and writes `theme.json` + `figma-variables.json` automatically. Falls back to `get_variable_defs` for files without a guidelines frame.
+2. **Write-time code lint.** Every section file is linted *before* being written. The lint enforces hard budgets (see `code-quality.md`). A file that would exceed budgets is rejected and the agent re-plans rather than emitting bloat.
+3. **Exemplar-anchored output.** New sections are compared structurally to the gold-standard exemplars in `exemplars.md`. If the planned section's DOM depth or class count exceeds the exemplar's by more than 20%, the build pauses and the agent justifies the deviation or simplifies.
+4. **Parallel page builds.** Five page-agents work concurrently. Each has its own scratchpad and never touches another page's files. The result: ~5× faster than the old serial flow.
+5. **Verification via Chrome DevTools MCP first.** `lighthouse_audit`, `take_screenshot`, `list_console_messages`, `list_network_requests`, and `performance_start_trace` are the primary gates during build. Puppeteer scripts are optional CI artefacts — not a substitute for MCP visual compare during the dev loop.
+6. **Single source of truth for tokens.** Header + footer + all "common" pages (cart, checkout, account, 404, signin/signup) inherit colors/fonts/radius/spacing from one place — Stage 0's `tailwind.config.js` + `theme.json`. Changing a token automatically updates everything.
+
+---
+
+## What the developer sees during a run
+
+```
+[stage 0]   bootstrap                                                 ✓ 32s
+            ├─ scaffolded lush_market/
+            ├─ guidelines frame parsed: Oswald + Lato, 10 color tokens
+            ├─    3 button variants with 4 states each, 6 component specs
+            ├─ tailwind.config.js + theme.json + figma-variables.json written
+            └─ header.liquid + footer.liquid locked
+
+[stage 1]   parallel page builds (5 agents)
+            ├─ index         building 5 sections   building 4/5   verify   ✓ 4m12s
+            ├─ listing       building 3 sections   verify                  ✓ 3m20s
+            ├─ product       building 6 sections   building 5/6   verify   ✓ 5m04s   (1 iteration: a11y contrast fix)
+            ├─ blog_list     building 2 sections   verify                  ✓ 2m48s
+            └─ blog_detail   building 2 sections   verify                  ✓ 3m15s
+                                                                      total ~5m04s (slowest agent)
+
+[stage 2]   consolidation
+            ├─ cross-page token consistency        ✓
+            ├─ navigation parity                   ✓
+            ├─ page JSONs + i18n keys              ✓
+            └─ build metrics + token estimate      ✓
+
+theme ready at lush_market/
+report at .claude/scratchpad/lush_market/report.md
+
+## Build metrics (example)
+  Wall-clock:     42m 18s
+  Sections:       23 built, 21/23 visual PASS (0 CRITICAL)
+  Token estimate: ~2.8M input / ~420K output (medium profile)
+  Slowest page:   product (8m 22s, 2 visual iterations)
+```
+
+The developer reviews the report — especially visual-diff CRITICAL counts and build metrics. **Figma fidelity is proven by screenshots, not by code inspection alone.**
+
+---
+
+## When to step out of the pipeline
+
+The pipeline is the right tool for: building a new theme from scratch with full Figma coverage.
+
+It is the **wrong** tool for, and should not be used for:
+- **Bug fix in an existing theme** → just open the file and fix it. No skill needed.
+- **One-off section change** → edit the section directly, then `cd <theme> && yarn run dev` to verify visually. No skill needed.
+- **Adding a theme setting** → edit `settings/schema.json` + `theme.json` directly.
+- **A new section that doesn't fit any of the 5 pages this skill handles** → also direct edit; the lint rules in `code-quality.md` still apply, but you don't need the orchestration.
+
+Keeping this skill scoped to its job is what makes it work without prompting overhead.
+
+---
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | This document — the entry point. |
+| `bootstrap.md` | Stage 0 — scaffold + token wiring. No file copies from any theme. |
+| `figma-extraction.md` | **NEW.** Per-element measurement extraction from Figma. The contract for what to build. |
+| `visual-verify-loop.md` | Mandatory 3-gate verify: visual + a11y + perf via Chrome DevTools MCP. |
+| `image-sources.md` | `asset_url` vs product CDN URLs — fixes the #1 dev-server image bug. |
+| `build-metrics.md` | End-of-run time + token estimate template. |
+| `agent-hierarchy.md` | Level 0 / A / B roles, scope boundaries, spawn rules. |
+| `transcription-rules.md` | Border-radius, colors, product card heights — spec → code. |
+| `figma-discovery.md` | Auto-discover pages from file key — do NOT ask for URLs first. |
+| `dev-server-and-urls.md` | Collect storeUrl, confirm page URLs, dev server workflow. |
+| `subagent-escalation.md` | Subagent questions/blockers must reach main agent + developer. |
+| `page-orchestrator.md` | Stage 1 page-level agent: identifies sections, plans snippets, spawns section subagents, batches developer questions, assembles page JSON, runs whole-page visual verify. |
+| `section-builder.md` | Section-level subagent: extracts Figma Spec, transcribes to Liquid, runs per-section visual verify loop. |
+| `ask-developer.md` | When to surface ambiguity vs decide. Format for `unresolved.md` entries. The batched-question protocol. |
+| `common-pages-agent.md` | Stage 1c — orchestrator for cart/checkout/account/auth/404/etc. Builds from logic patterns + tokens (no Figma per page). |
+| `inputs/guidelines-frame.md` | How to parse the guidelines frame: typography, colors, button states, component specs. |
+| `parallel-fanout.md` | Stage 1 — spawning the 5 page agents and managing their reports. |
+| `page-builder.md` | What runs inside each parallel page agent. |
+| `code-quality.md` | The strict budgets and the write-time lint procedure. |
+| `exemplars.md` | Logic patterns per archetype, built from the bundled docs (no other themes). |
+| `verification.md` | Four-gate verify + Stage 2 consolidation. |
+| `scripts/pixel-diff.mjs` | Puppeteer + pixelmatch — rendered vs. Figma. |
+| `scripts/a11y.mjs` | Puppeteer + axe-core — WCAG 2.1 AA scoped to a section. |
+| `scripts/perf.mjs` | Puppeteer + Lighthouse — CWV + perf score per page. |
+| `scripts/lint-section.mjs` | Write-time AST lint — DOM depth, class count, schema field wiring. |
+| `scripts/record-build-metrics.mjs` | Aggregates wall-clock, section counts, visual-verify pass rate. |
+
+---
+
+## Scratchpad layout
+
+Everything intermediate lives under `.claude/scratchpad/<theme_name>/` (gitignored).
+
+```
+.claude/scratchpad/<theme_name>/
+  bootstrap/
+    figma-variables.raw.json     (raw get_variable_defs output)
+    token-map.json               (resolved tokens applied to theme)
+  pages/
+    index/
+      figma-desktop.png
+      figma-mobile.png
+      figma-context.json
+      spec-table.md
+      sections.plan.md           (which sections to build, in order)
+      lint-reports/              (one per section)
+      verify/
+        pixel-diff.json
+        axe.json
+        lighthouse.json
+      iterations.log
+    listing/    (same shape)
+    product/    (same shape)
+    blog_list/  (same shape)
+    blog_detail/(same shape)
+  report.md                      (final consolidated report)
+```
+
+Each parallel page agent owns its subdirectory exclusively. No cross-writes.
+
+---
+
+## Quick start (the only command developers need to remember)
+
+```
+/build-theme {name} {figma_file_key} [{root_node_id}]
+```
+
+Discovery finds pages automatically. Optional: `override: primary=#hex` for brand updates.
+
+Ask developer only when: discovery fails, URLs unconfirmed for browser verify, or ambiguous design. Otherwise: run.

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/agent-hierarchy.md

@@ -0,0 +1,142 @@
+# Agent hierarchy — Level 0 → A → B
+
+This is the **only** build architecture for `/build-theme`. Each level has a narrow scope to prevent hallucination (wrong border-radius, wrong colors, uneven product cards).
+
+```
+LEVEL 0 — Main orchestrator (serial)
+  │
+  ├─ figma-discovery.md     → identify ALL pages from file key
+  ├─ bootstrap.md           → tokens, dev-config.json
+  ├─ developer approves page map
+  │
+  └─ spawns LEVEL A agents (one per page, parallel after index)
+
+LEVEL A — Page orchestrator (one page, does NOT write sections)
+  │
+  ├─ get_design_context on PAGE frame only (desktop + mobile)
+  ├─ identify SECTION list + Figma node ID per section
+  ├─ write sections.plan.md
+  ├─ spawn LEVEL B agents (one per section, PARALLEL)
+  ├─ wait for all Level B PASS
+  ├─ assemble pages/<page>.json
+  └─ whole-page visual verify vs Figma PAGE frame
+
+LEVEL B — Section builder (ONE section, does NOT see other sections)
+  │
+  ├─ get_design_context on SECTION node only (not parent page)
+  ├─ write figma-spec.json (every visual value transcribed)
+  ├─ transcribe → sections/<name>.liquid (no improvisation)
+  ├─ lint-section.mjs (syntax / docs compliance)
+  ├─ Chrome DevTools visual verify vs Figma SECTION crop
+  └─ report PASS only when visual-diff.md has 0 CRITICAL
+```
+
+---
+
+## Scope boundaries (prevents hallucination)
+
+| Level | May read | Must NOT read |
+|---|---|---|
+| **0** | Full file metadata, all pages | Section markup, sibling theme CSS |
+| **A** | Page frame tree, section boundaries | Build section Liquid; full-page design values for coding |
+| **B** | **One section node** + theme tokens + logic exemplars | Parent page frame; other sections; sibling theme colors/spacing |
+
+**Level B context window = one Figma section frame.** That is the fix for "agent guessed border-radius / colors from memory."
+
+---
+
+## Level 0 — Main orchestrator
+
+**File:** `SKILL.md`, `figma-discovery.md`, `parallel-fanout.md`
+
+1. Discover pages (`get_metadata` on theme canvas)
+2. Bootstrap theme + `dev-config.json`
+3. Show page map → developer **YES**
+4. Spawn Level A for index **first** (header/footer)
+5. After `header-footer-ready`, spawn Level A for product, collection, blog_list, blog_detail **in parallel**
+6. Stage 2 consolidation + `record-build-metrics.mjs`
+
+**Level 0 never writes `sections/*.liquid`.**
+
+---
+
+## Level A — Page orchestrator
+
+**File:** `page-orchestrator.md`
+
+### Responsibilities
+
+| Do | Don't |
+|---|---|
+| Identify sections from page Figma frame | Write section HTML/CSS |
+| Assign each section a **unique node ID** | Pass whole-page screenshot to Level B as build input |
+| Spawn Level B subagent per section | Copy design from sibling themes |
+| Assemble `pages/<page>.json` after all B pass | Skip whole-page visual verify |
+| Whole-page visual compare (inter-section spacing) | Fix section internals (delegate to B) |
+
+### Output before spawning Level B
+
+`sections.plan.md` — every row must have a Figma node ID:
+
+```
+| # | section_name       | desktop_node | mobile_node | archetype      |
+|---|--------------------|--------------|-------------|----------------|
+| 1 | header             | 2613:152     | 2375:4031   | header         |
+| 2 | featured-products  | 2613:400     | 2375:4100   | product-grid   |
+```
+
+### Level B spawn (parallel)
+
+One `Task` / `Agent` per section. Prompt must include:
+
+- `figma_node_id` (desktop; mobile as separate if differs)
+- `section_name`
+- `scratchpad` path
+- `page_url` from `dev-config.json`
+- **Explicit:** "You are Level B. Scope = this section node only. Do not read parent page Figma."
+
+---
+
+## Level B — Section builder
+
+**File:** `section-builder.md`, `figma-extraction.md`, `transcription-rules.md`
+
+### Responsibilities
+
+| Do | Don't |
+|---|---|
+| `get_design_context` on **section node ID only** | `get_design_context` on full page |
+| Transcribe `figma-spec.json` → Liquid | Add `rounded-*` unless spec has `border_radius > 0` |
+| Lint + visual verify **this section** | Assemble page JSON |
+| Use theme tokens mapped in spec | Hardcode hex or copy sibling theme styles |
+
+### Verify gates (Level B only)
+
+1. **Syntax** — `lint-section.mjs` PASS
+2. **Docs** — valid tags/filters per `zcommerce-docs/`
+3. **Visual** — Chrome DevTools screenshot of **this section** vs Figma **section crop**; `visual-diff.md` 0 CRITICAL
+
+Level B does **not** pass until all three pass.
+
+---
+
+## After Level B — Level A assembles + verifies page
+
+1. Wire sections in `pages/<page>.json` (order from `sections.plan.md`)
+2. Populate block settings from Figma (distinct per block)
+3. Navigate to `page_url` from `dev-config.json`
+4. Full-page screenshot vs Figma **page** frame
+5. Fix **only** inter-section issues (order, gap, missing section)
+6. If a section looks wrong internally → re-spawn Level B for that section only
+
+---
+
+## Common failures this hierarchy fixes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Border radius where Figma is square | Agent used theme default `rounded-card` | Level B: `border_radius: 0` in spec → no `rounded-*` |
+| Product cards different heights | Images without fixed media box | Level B: spec `position.h` on media + `object-fit` + `aspect-ratio` |
+| Wrong colors | Agent read sibling theme or guessed token | Level B: colors only from `figma-spec.json` token map |
+| Extra sections on page | Level A invented sections | Level A: section list = Figma children only |
+| Page looks wrong but sections "pass" | Level A skipped whole-page verify | Level A Phase 8 mandatory |

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/ask-developer.md

@@ -0,0 +1,113 @@
+# Ask the developer — checkpoints, format, what to ask, what NEVER to ask
+
+Every previous build failed in part because the agent guessed when it should have asked. This doc enumerates the exact checkpoints where asking is mandatory, with templates.
+
+## The principle
+
+A question to the developer costs ~10 seconds of their attention. A wrong guess costs a full iteration cycle plus their trust. **When the answer isn't in the bundled docs (`zcommerce-docs/`), the theme tokens (`theme.json` / `figma-variables.json`), or the Figma's structured `get_design_context` output — ASK. Always.**
+
+When the answer IS in any of those three sources — look it up. Don't ask.
+
+## Hard checkpoints (asking is mandatory if condition holds)
+
+### Bootstrap (Stage 0)
+
+- **No guidelines frame URL provided** → ask. Without it, no tokens.
+- **Two or more candidate guidelines frames found** → ask which one. Don't pick.
+- **A token in the guidelines frame is unreadable** (low resolution, OCR ambiguous) → ask the developer for the hex / size value directly. Don't guess.
+- **Figma auto-discovery failed** (`get_metadata` returned nothing usable, no Website View / Mobile View) → ask for missing page frame URLs. **Do NOT ask if discovery already produced a page map** — see `figma-discovery.md`.
+- **No `storeUrl` provided** → ask before starting dev server. See `dev-server-and-urls.md`.
+- **Page URLs not confirmed** → ask before any `navigate_page`. Defaults are guesses only:
+  - Home: `http://localhost:3000/home` (NOT `/`)
+  - Product: `http://localhost:3000/products/item-1`
+  - Collection: `http://localhost:3000/collections/all-products`
+  Write confirmed URLs to `dev-config.json`.
+- **Dev server not running** → ask developer to start it, or start it yourself with their `storeUrl` and notify them.
+
+### Section identification (page orchestrator Phase 2)
+
+- **A region in the page Figma doesn't correspond to any sibling theme's archetype** (e.g. a brand-new section type not in any theme) → ask whether to (a) build from scratch from docs, (b) skip with a placeholder, or (c) the developer will provide a reference.
+- **Two adjacent regions could be one section with 2 blocks OR 2 separate sections** → ask. Don't decide.
+- **A region is in the Figma but the developer said "ignore non-Figma sections"** → ask whether to include it (because it IS in the Figma) or skip per their note.
+
+### Figma extraction (section builder Phase 2)
+
+- **`get_design_context` fails on the section's node** ("nothing selected", network error, file access) → ask the developer to open Figma desktop and select the section, or to provide a fresh URL.
+- **An image node returns an empty / non-PNG `get_screenshot`** → ask the developer to export it manually and drop into assets/.
+- **A color in the Figma doesn't map to any theme token (ΔE > 1.5)** → ask whether to add a new theme token or use a one-off hex.
+- **A font weight in the Figma isn't available in the theme's font setup** (e.g. Figma uses Oswald 850, but only 400/500/600/700 are loaded) → ask whether to add the weight to webfont imports, or use closest available.
+- **A text element shows "Lorem ipsum" or other placeholder copy** → ask for the real copy. Never invent customer-facing copy.
+
+### Build (section builder Phase 4-5)
+
+- **Schema setting has no obvious default** (e.g. CTA URL — should it be `/all-products`, `/cart`, or developer's choice?) → ask.
+- **A section spans both desktop and mobile Figma frames that materially differ** (not just responsive resize — actually different layouts) → ask which is canonical and whether to implement both as separate variants.
+
+### Visual verify loop (Phase 7)
+
+- **After 5 iterations of the verify loop, CRITICAL mismatches remain** → ask the developer for a specific call (e.g. "this hero text is supposed to be at bottom-left but I can't anchor it without affecting the next section's top spacing — should I add an absolute-positioned container, or use min-height on the panel?").
+- **A visual element appears in the Figma but the agent can't reproduce it** (custom gradient, complex mask, blur, mix-blend mode) → ask how to handle.
+
+### State / interactivity
+
+- **Hover / focus / pressed / disabled / loading state not shown in static Figma** → ask. Static design doesn't show these by default.
+- **Animation or transition specs** (entrance animation, hover transition, scroll behavior) → ask.
+- **Mobile breakpoints between 375 and 1440** (tablet 768px, desktop md/lg) → ask.
+- **Conditional rendering rules** (show only if X, hide on Y page) → ask.
+
+## NEVER ask — look it up
+
+- **Token values.** `theme.json`, `figma-variables.json`. Read them.
+- **Tailwind class names.** Derived from `tailwind.config.js`. Read it.
+- **Schema field types.** `zcommerce-docs/reference/schema-types.md`. Read it.
+- **Liquid filter names.** `zcommerce-docs/reference/filters.md`. Read it.
+- **Liquid tag names.** `zcommerce-docs/reference/tags.md`. Read it.
+- **Global object properties.** `zcommerce-docs/reference/global-objects.md`. Read it.
+- **File / folder conventions.** `zcommerce-docs/theme-structure.md`. Read it.
+- **Performance / accessibility best practices.** `zcommerce-docs/best-practices.md`. Read it.
+- **Asset filter syntax.** `zcommerce-docs/assets.md`. Read it.
+- **i18n key conventions.** `zcommerce-docs/i18n.md`. Read it.
+- **Pixel coordinates of elements in the Figma.** `get_design_context` returns these. Use it.
+
+## Format
+
+Section subagents write to `<scratchpad>/sections/<section>/unresolved.md`. Page orchestrators collect them and ask the developer in ONE batch per page.
+
+Each entry has this shape:
+
+```
+### Q{N} — {one-line summary}
+**section:** hero-banner
+**phase:** figma-extraction | build | verify-loop | other
+**type:** missing-asset | unmapped-color | placeholder-copy | layout-stuck | state-undefined | other
+**context:** {one paragraph explaining what you tried and what's stuck}
+**options:**
+  a) {first concrete option}
+  b) {second concrete option}
+  c) {third concrete option}
+**recommended:** a — {one-line justification}
+**blocking:** true | false
+**deadline:** {how long the orchestrator will wait before defaulting to `recommended`}
+```
+
+The page orchestrator uses `AskUserQuestion` with up to 4 questions per page batch. If more than 4 unresolved, ask the 4 with `blocking: true` first; defer the rest with `recommended` answers and log to NEEDS_REVIEW.
+
+**All subagent questions must also surface on the main agent screen.** See `subagent-escalation.md` — the main orchestrator posts a summary after each page agent completes, even if the page agent already asked the developer.
+
+## What good vs bad questions look like
+
+**Bad (vague, unanswerable, indicates agent didn't try):**
+- "What should the hero look like?"
+- "How should I style the button?"
+- "Is this section important?"
+
+**Good (specific, with concrete options, ask only when the doc/spec lookup truly fails):**
+- "The hero's right-panel has a #FFAB4A background in the Figma but the closest theme token is `--color-accent` (#FF8F6B, ΔE 2.1). Should I (a) add a new `--color-accent-warm` token, (b) use the closest existing `--color-accent`, or (c) hardcode the hex for this one-off?"
+- "Figma node 2613:148 (the penguin plush image) returned an empty result from `get_screenshot`. Can you export this image manually from Figma and drop it into `assets/hero-banner-panel-left-penguin.png`?"
+- "Hero text needs to be at bottom-left of the panel per Figma, but my CSS keeps causing the next section to overflow. I tried `justify-content: flex-end` (broke responsive), `padding-top: 60%` (broke at narrow viewports). Should I (a) use absolute positioning, (b) add a min-height to the panel, or (c) accept text-in-middle as a deviation?"
+
+## When the developer can't be reached promptly
+
+For `blocking: false` questions, proceed with `recommended` after the deadline (default 2 minutes for a section subagent, 5 minutes for a page orchestrator batch). Log to NEEDS_REVIEW.
+
+For `blocking: true` questions, the page orchestrator does NOT ship the page. It writes a NEEDS_REVIEW report and the main orchestrator surfaces to the developer as a build halt.