@zohofinance/commerce 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,61 @@
+# Zoho Commerce CLI
+
+A command-line tool for developing and building themes for Zoho Commerce stores.
+
+## Installation
+
+Global installs (`npm i -g`) are not recommended. Prefer `npx` so you always run the package version resolved for the current project:
+
+```bash
+# From a theme (or monorepo) that depends on the CLI:
+npx @zohofinance/commerce <command>
+
+# Or install as a local dependency, then use npx / yarn scripts:
+npm install @zohofinance/commerce
+npx @zohofinance/commerce <command>
+```
+
+## Commands
+
+### `theme init [theme-name]`
+
+Scaffolds a new theme project. If `theme-name` is omitted, you will be prompted to enter one.
+
+```bash
+npx @zohofinance/commerce theme init <theme-name>
+```
+
+Creates a new folder with the theme template and includes AI helper files (`.claude/` and `.cursor/`) for editor integrations.
+
+---
+
+### `theme dev`
+
+Starts a local development server with live reload.
+
+```bash
+npx @zohofinance/commerce theme dev
+```
+
+**Options**
+
+| Flag | Description |
+|------|-------------|
+| `--port <value>` | Port for the local preview server |
+| `--open` | Open the theme preview in your default browser |
+| `--livereload-off` | Disable live reload |
+| `--storeUrl <value>` | Preview the theme with live store data |
+
+---
+
+### `theme build`
+
+Builds the theme into a distributable package.
+
+```bash
+npx @zohofinance/commerce theme build
+```
+
+## Docs
+
+[Zoho Commerce Theme Development](https://www.zoho.com/commerce/developer/themes/introduction/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zohofinance/commerce",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "ts-dist/index.js",
   "bin": {
     "zcommerce": "ts-dist/index.js"
@@ -16,7 +16,7 @@
     "test": "node -e \"console.log('No tests configured')\""
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org"
+    "registry": "https://registry.npmjs.com"
   },
   "type": "module",
   "dependencies": {

package/ts-dist/mocks/init-theme/.claude/CLAUDE.md

@@ -0,0 +1,6 @@
+# Claude Code Instructions
+
+Add your Claude Code skills and settings here for theme development.
+
+- `skills/` — skill markdown files loaded by Claude Code
+- `settings.json` — Claude Code project settings

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: zcommerce-section-from-design
+description: Use when the user asks to build a NEW ZCommerce Liquid section that should match a provided Figma frame, screenshot, or live URL — and they want production-quality output (visual accuracy, accessibility, performance). Triggers on phrases like "build this section from Figma", "make a section like this screenshot", "clone this URL's hero", "section that matches the design". Do NOT use for bug fixes (use zcommerce-theme-builder's `fix-section`), redesigns of an existing section (`redesign-section`), theme-wide setting changes (`add-theme-setting`), or full multi-page theme generation (`build-theme`). This skill orchestrates intake + verification; section authoring itself is delegated to `zcommerce-theme-builder`.
+---
+
+## Preconditions (check before starting)
+
+- **CLI is installed.** `npx @zohofinance/commerce --version` must work from inside the theme folder. If not, run `npm install @zohofinance/commerce` inside the theme directory, then retry.
+- **Dev server can start.** Run `yarn run dev --storeUrl=<your store url>` once to confirm. If the project hasn't been bootstrapped, run `yarn install` first.
+- **Claude in Chrome is connected** for gate 1 and gate 3 (the section-scoped axe path). Check via `mcp__Claude_in_Chrome__list_connected_browsers` — if none, ask the user to connect one. Without it, fall back to CLI-driven verification (`npx @zohofinance/commerce theme build`) which is slower but works.
+- **Figma MCP is authenticated** if the input is Figma. Two servers exist (Dev-Mode and the plugin's OAuth path) — see `inputs/figma.md`.
+- **Scratchpad path.** All intake artefacts and reports go under `.claude/scratchpad/<section_name>/` inside the theme repo (gitignored). This is the canonical location — every reference to "`<scratchpad>`" in the docs resolves here. Create it on first use.
+
+
+
+# ZCommerce Section From Design
+
+**Read first:**
+1. `CLAUDE.md` at the repo root — global project rules.
+2. `.claude/skills/zcommerce-theme-builder/SKILL.md` — section authoring mechanics, schema syntax, file anatomy, all CLI commands. This skill **does not** re-derive those rules.
+3. This theme's `sections/` folder — pick an existing section with similar purpose to copy Liquid logic from.
+
+This skill is the orchestration layer. It takes a design input, normalizes it into a Design Spec Table, hands off to `zcommerce-theme-builder` to build, then runs a four-gate verification pipeline and iterates until all gates pass (or the user accepts a tolerated deviation).
+
+---
+
+## 1. When to use
+
+Trigger when the user provides **any** of these and asks for a section, page block, or component:
+- A **Figma** selection (via Figma MCP) or shared frame URL.
+- A **screenshot** image (uploaded file, paste, or path).
+- A **live website URL** ("build this like xyz.com's hero").
+- Any combination of the above (e.g. "screenshot + reference site").
+
+Do **not** trigger for: theme-wide settings changes (use `add-theme-setting`), bug fixes on existing sections (use `fix-section`), or full multi-page theme generation (this skill is section-scoped).
+
+---
+
+## 2. The pipeline (always five stages)
+
+```
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│ 1. Intake &  │ → │ 2. Normalize │ → │ 3. Reference │ → │ 4. Build     │ → │ 5. Verify    │
+│   Input Type │   │   Spec Table │   │   Selection  │   │ (delegated)  │   │   4 gates    │
+└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
+                                                                                   │
+                                                                          fail → 6. Iterate ↑
+                                                                          pass → done
+```
+
+Every stage has a dedicated reference file. Read the relevant one before executing the stage.
+
+| Stage | What it produces | Reference doc |
+|------|------------------|---------------|
+| 1. Intake | Raw input + recorded source type | `inputs/figma.md` · `inputs/screenshot.md` · `inputs/url.md` |
+| 2. Normalize | Unified **Design Spec Table** (the build contract) | `spec-table.md` |
+| 3. Reference | Pick a reference section in this theme; decide whether to reuse existing web components | this theme's `sections/` · existing snippets / web components |
+| 4. Build | A `.liquid` section file in `sections/` | (delegated) `zcommerce-theme-builder` → `build-section` |
+| 5. Verify | A Verification Report covering 4 gates | `verification/visual-diff.md` · `verification/tokens.md` · `verification/accessibility.md` · `verification/performance.md` |
+
+---
+
+## 3. Stage 1 — Intake
+
+### 3.1 Inputs the user may give
+
+| Source | How to access |
+|---|---|
+| Figma frame URL or selection | `mcp__plugin_product-management_figma__*` tools or the Dev-Mode `mcp__32a68a89-...` tools — `get_design_context`, `get_variable_defs`, `get_screenshot`, `get_metadata` |
+| Screenshot file | Read the uploaded image; if absent, ask the user to upload to a known path |
+| Website URL | Claude in Chrome — `navigate`, `get_page_text`, `javascript_tool` for computed styles, `read_page` for DOM. If Claude in Chrome is unavailable, fall back to `mcp__workspace__web_fetch` for HTML only (no JS execution) |
+
+### 3.2 Required questions before proceeding
+
+Use `AskUserQuestion` once at the start to collect:
+1. **Target theme** — this theme directory (confirm the folder name).
+2. **Section name** (snake-case, used as filename).
+3. **Page where it will live** (so the page JSON can be updated in stage 4).
+4. **Both desktop AND mobile inputs?** — if input is Figma, request both frames. If screenshot, ask for both. If URL, the agent will resize the browser to 1440 and 375 itself.
+
+### 3.3 Source-specific intake — see the dedicated docs
+
+- Figma → `inputs/figma.md`
+- Screenshot → `inputs/screenshot.md`
+- URL → `inputs/url.md`
+
+Stage 1 output goes to `.claude/scratchpad/<section_name>/` (the canonical scratchpad path defined in Preconditions). Add this directory to `.gitignore` if not already. Raw artefacts: `{desktop.png, mobile.png, figma-context.json, computed-styles.json, spec-table.md, ...}`. Verification reuses these.
+
+---
+
+## 4. Stage 2 — Normalize to a Design Spec Table
+
+The **Design Spec Table** is the build contract. Every value the implementation must produce is enumerated here in pixels/hex/font-weight terms before any code is written. This is what makes the build a one-pass match instead of a guess-and-compare loop.
+
+See `spec-table.md` for the exact column schema and worked examples for all three input types. Hard rule: the table must be filled in before stage 4. If a row cannot be filled (e.g. screenshot is ambiguous about spacing), mark it `?` and ask the user — do not guess.
+
+---
+
+## 5. Stage 3 — Reference selection
+
+Two decisions:
+
+### 5.1 Which existing section to copy Liquid logic from
+
+Scan this theme's `sections/` for the closest match by purpose (hero, banner, product grid, footer, etc.). If nothing similar exists, use the closest partial match or build schema from the docs — do not look outside this theme for other themes.
+
+The rule from `zcommerce-theme-builder`: **logic and schema patterns come from the reference; HTML structure and visual values come from the input.** Never discard working Liquid logic to match a simpler-looking design.
+
+### 5.2 Whether to reuse an existing web component
+
+This theme may already ship accessible web components (for example add-to-cart, authentication, cookie bar, custom fields, accordion, input, message bar, quantity counter, search). Prefer those over hand-rolled JS when a matching component already exists. Wire them in via `{% render %}` the same way existing sections do.
+
+---
+
+## 6. Stage 4 — Build (delegated)
+
+Hand off to `zcommerce-theme-builder` → `build-section <theme_name> <section_name>`. Pass it:
+- The completed Design Spec Table from stage 2 (file at `.claude/scratchpad/<section_name>/spec-table.md`).
+- The reference section identified in stage 3.
+- Any existing web components to be wired in.
+
+**Spec-table handoff is explicit.** `zcommerce-theme-builder`'s `build-section` workflow has its own stage-2 "Extract Detailed Design Spec" step. When called from this skill, that step is **skipped** — the spec table this skill produced is the authoritative one. Tell the delegated workflow: "spec-table.md is pre-populated at `.claude/scratchpad/<section>/spec-table.md`; use it directly, do not re-extract."
+
+`zcommerce-theme-builder`'s `build-section` then handles: file anatomy (script/style/liquid/conditional/wrapper/schema order), custom schema syntax, Tailwind/CSS-variable mapping (the `*-theme-*` utility classes from each theme's `tailwind.config.js`), mobile-first responsive layout, self-compare against the spec table. Do not re-derive those rules here.
+
+**Note on Tailwind classes.** The spec-table examples use classes like `py-theme-16`, `gap-theme-8`, `rounded-theme-button`. These are defined in each theme's own `tailwind.config.js`. Before passing the spec to the build, **open `tailwind.config.js`** and confirm the classes referenced exist. If a class is missing, either add it to the config (if the underlying CSS variable exists in `theme.json`) or use arbitrary-value Tailwind (`py-[64px]`) as a fallback.
+
+After build, also update:
+- `pages/<page_name>.json` — add the new section to the page (use `assemble-page` if the page doesn't exist yet, otherwise edit in place).
+- `i18n/en.json` and `en.schema.json` — add all translation keys referenced in the schema.
+
+---
+
+## 7. Stage 5 — Verify (four gates)
+
+A section passes only when all four gates pass within tolerance. Run them **after** the build is in place and the dev server is up.
+
+### Start the dev server (once, kept alive for the whole verification)
+
+```bash
+cd <theme_name>
+yarn run dev --storeUrl=<your store url>
+```
+
+Wait for "compiled" / "ready". The dev server stays running across all four gates and any iteration loops. If the user wrote `--storefronturl` they mean `--storeUrl`. Add `--useMock` only if they explicitly asked for mock data.
+
+### Gate 1 — Visual diff
+
+See `verification/visual-diff.md`. Reuses `zcommerce-theme-builder`'s `compare-section --visual` workflow under the hood — that command already orchestrates Claude in Chrome navigation + screenshot + Figma comparison. This skill's gate 1 adds screenshot/URL input handling (compare-section is Figma-only) and ensures the resulting mismatch report categorizes by CRITICAL / MINOR / SUGGESTION using this skill's tolerance defaults (§10).
+
+### Gate 2 — Design-token exact match (Figma only)
+
+See `verification/tokens.md`. For every row of the Design Spec Table, assert the generated code uses the right CSS variable / Tailwind class / px value. This catches numeric drift that visual diff misses (e.g. 16px vs 17px). Skipped when input was screenshot or URL — those have no token source of truth.
+
+### Gate 3 — Accessibility (WCAG 2.1 AA via axe-core)
+
+See `verification/accessibility.md`. Run axe-core against the section URL — the CLI already integrates axe-core via puppeteer, so the simplest path is to call `npx @zohofinance/commerce theme build` and read the audit output. For section-only checks during iteration, run axe directly in Claude in Chrome via `javascript_tool` injecting axe-core. **Fail the gate on any critical or serious violation.**
+
+### Gate 4 — Performance (Lighthouse)
+
+See `verification/performance.md`. Same path — the CLI ships Lighthouse and runs it during `theme build`. For per-section iteration, run Lighthouse directly via puppeteer or just inspect Chrome DevTools metrics. Targets: LCP < 2.5s, CLS < 0.1, TBT < 200ms, performance score ≥ 90 on the section's host page.
+
+### The Verification Report
+
+After all four gates run, produce a single report:
+
+```
+SECTION: <theme>/<section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+INPUT TYPE: figma | screenshot | url
+SOURCE: <link or filename>
+DEVICE: desktop 1440 + mobile 375
+
+GATE 1 — VISUAL DIFF
+  desktop: 0 critical, 2 minor (gap 16→14px, radius 8→6px)
+  mobile:  0 critical, 0 minor
+
+GATE 2 — TOKEN MATCH (figma only)
+  17/17 spec rows verified
+  FAIL font-size on .hero-h1 expected 48px → found 44px
+
+GATE 3 — A11Y (axe-core, WCAG 2.1 AA)
+  0 critical, 0 serious
+  1 moderate: color-contrast 4.3:1 on .badge (target 4.5)
+
+GATE 4 — PERFORMANCE (Lighthouse, page = /home)
+  Performance 94 · LCP 1.9s · CLS 0.02 · TBT 110ms
+
+VERDICT: needs iteration (1 token mismatch, 1 a11y moderate)
+NEXT: fix .hero-h1 font-size, tweak .badge contrast → re-run gates 1-3
+```
+
+---
+
+## 8. Stage 6 — Iterate
+
+Loop on whichever gates failed. Two patterns:
+
+- **Token / visual mismatch** → edit the section file; re-run gates 1 and 2 only.
+- **A11y / perf failure** → diagnose in `verification/accessibility.md` / `verification/performance.md`; usually a fix in the `.liquid` or asset JS. Re-run the failing gate plus any visually affected gates.
+
+**Iteration counter.** One "iteration" = one full pass through whichever gates failed (not per-gate). Hard stop after **3 iterations** — if still failing, surface the report to the user with the remaining deltas and ask whether to ship as-is, change the spec, or escalate.
+
+**Gate-2 precedence.** Gate 2 (token match) is stricter than the tolerance defaults in §10 — it requires *exact* matches per the spec table. When gate 1's tolerance says "within 2px is fine" but gate 2 says "spec says 64px, code has 62px → FAIL", gate 2 wins. Tolerance defaults apply only to visual diff and to user-facing accept/reject decisions, not to token verification.
+
+---
+
+## 9. Parallelism
+
+Within a single section build, parallelize where safe:
+- Stage 1 — fetch desktop + mobile inputs concurrently.
+- Stage 5 — gates 1 (visual diff) and 2 (token check) can run in parallel; gates 3 (a11y) and 4 (perf) share a puppeteer browser so run them serially or use the CLI's `theme build` which already sequences them.
+
+For multi-section batches, spawn one subagent per section using the `general-purpose` agent type, each running this skill end-to-end. See `zcommerce-theme-builder` § 5 for the parallel agent strategy.
+
+---
+
+## 10. Tolerance defaults
+
+| Metric | Auto-pass | Flag minor | Flag critical |
+|---|---|---|---|
+| Spacing / padding | within 2px | 3–8px diff | > 8px diff |
+| Font size | exact | within 2px | > 2px diff |
+| Color | hex equal OR ΔE < 1 | ΔE 1–3 | ΔE > 3 |
+| Border radius | within 2px | 3–6px diff | > 6px diff |
+| LCP | < 2.5s | 2.5–4s | > 4s |
+| CLS | < 0.1 | 0.1–0.25 | > 0.25 |
+| Axe violations | none | moderate / minor | critical / serious |
+
+Override these per-section only if the user explicitly says "loose match" or "pixel-perfect required."
+
+---
+
+## 11. Quick-start command
+
+```
+section-from-design <theme_name> <section_name> --input figma:<your figma url> [--page <page_name>]
+section-from-design <theme_name> <section_name> --input screenshot:<path>[,<mobile_path>]
+section-from-design <theme_name> <section_name> --input url:<your website url>
+```
+
+If invoked without flags, the skill asks via `AskUserQuestion` for the missing pieces and proceeds.

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/inputs/figma.md

@@ -0,0 +1,81 @@
+# Input handler — Figma
+
+Triggered when the user provides a Figma frame URL, Figma file key, or has a selection active in the Figma desktop app (Dev-Mode MCP).
+
+## 1. Available Figma tools
+
+Two MCP servers may be connected:
+
+| Server | Tools | When to use |
+|---|---|---|
+| Dev-Mode MCP (`mcp__32a68a89-...`) | `get_design_context`, `get_screenshot`, `get_variable_defs`, `get_metadata`, `get_code_connect_suggestions`, `search_design_system` | **Preferred** when the user has the Figma desktop app open with a frame selected. Pulls live values from the canvas. |
+| Figma plugin MCP (`mcp__plugin_product-management_figma__*`) | OAuth-based REST API access | Use when only a URL/file-key is available and no selection is active. Requires `authenticate` first. |
+
+If neither is connected, ask the user to either open Figma with a selection (for Dev-Mode) or paste a screenshot as a fallback.
+
+## 2. Intake steps
+
+Run all of these. The first two can be parallelized.
+
+1. **`get_metadata`** — confirms the frame name, dimensions, and whether you're looking at a single frame vs a page. Reject if the selection is a page-level group (too broad); ask user to drill in.
+2. **`get_screenshot`** — fetch desktop screenshot at 1× and 2×. Save under `<scratchpad>/intake/<section_name>/figma-desktop.png` and `...-2x.png`.
+3. **`get_screenshot`** for the mobile variant frame — Figma files conventionally have a separate mobile frame. If the user only shared one frame, ask for the mobile counterpart before continuing.
+4. **`get_design_context`** — returns the full structured node tree with computed styles per element. Save raw to `<scratchpad>/intake/<section_name>/figma-context.json`. This is the source of truth for the spec table.
+5. **`get_variable_defs`** — pulls all variable references used in the selection (colors, spacing, radius, type). Save to `<scratchpad>/intake/<section_name>/figma-variables-used.json`.
+
+## 3. Resolve variables against `figma-variables.json`
+
+The theme repo has a `figma-variables.json` (W3C-design-tokens format with `$type` / `$value`). After step 4 above, for every variable reference in the design context:
+
+1. Strip the `--` prefix, split on `/`, traverse the JSON.
+2. If the resolved node has `$value`, use it.
+3. If not found, log it under "unmapped tokens" — the user may need to add it to `figma-variables.json` before the build can complete.
+
+Example: `var(--spacing/4-multiples/4, 16px)` → traverse `spacing > "4 Multiples" > "4"` → `$value: 16`.
+
+## 4. Extract per-element values
+
+For every visible element in the frame (containers, text nodes, images, buttons, dividers), record:
+
+- `width`, `height` (or `auto` / `fill`)
+- `padding-{top,right,bottom,left}`
+- `margin-*` (only if non-zero; rely on auto-layout gap otherwise)
+- `gap` (for flex/grid containers)
+- `background` — resolved hex or CSS variable name
+- `border` — width, color, style
+- `border-radius` — per-corner if asymmetric
+- `font-family`, `font-size`, `font-weight`, `line-height`, `letter-spacing`, `color`
+- `box-shadow` — full spec
+- `opacity`, `mix-blend-mode` if non-default
+- `display` / `flex-direction` / `justify-content` / `align-items` for containers
+
+Feed all of this into the spec table (`../spec-table.md`).
+
+## 5. Handle responsive
+
+Always compare desktop and mobile side-by-side. The spec table has a desktop column and a mobile column; if a value is the same, write it in one and leave the other blank.
+
+If the Figma file has only desktop and no mobile frame, **stop and ask** — building responsive from desktop alone leads to bad mobile output. Acceptable fallback only with user approval: derive mobile defaults using Tailwind breakpoints (`base` = mobile starting at 375, `md:` = 768+, `lg:` = 1024+).
+
+## 6. Gotchas
+
+- Figma "Auto Layout" → CSS flexbox. `gap` is real CSS gap, **not** margin between children.
+- Figma "fill container" → `flex-1` or `w-full`.
+- Figma color tokens that don't appear in `figma-variables.json` are likely from an unimported library — ask the user to either import or hardcode (with their explicit approval).
+- `get_screenshot` may downscale aggressively — for pixel-perfect typography checks, also fetch the 2× version.
+- The Dev-Mode MCP can return *generated code suggestions* via `get_code_connect_suggestions`. Treat those as hints only; never paste them directly — they don't follow ZCommerce's custom schema conventions.
+
+## 7. Output artefacts
+
+```
+<scratchpad>/intake/<section_name>/
+  figma-desktop.png
+  figma-desktop-2x.png
+  figma-mobile.png
+  figma-mobile-2x.png
+  figma-context.json        (raw get_design_context output)
+  figma-variables-used.json (raw get_variable_defs output)
+  unmapped-tokens.txt       (variables referenced but not in figma-variables.json)
+```
+
+Feed all of these into stage 2 (spec table).

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/inputs/screenshot.md

@@ -0,0 +1,54 @@
+# Input handler — Screenshot
+
+Triggered when the user uploads an image (PNG / JPG / WebP) or pastes a screenshot, with no Figma or URL source.
+
+## 1. Required inputs
+
+Use `AskUserQuestion` to collect (only fields not already provided):
+
+1. **Desktop screenshot** — required.
+2. **Mobile screenshot** — strongly recommended. If absent, ask once whether the user wants to:
+   - (a) provide a mobile screenshot, or
+   - (b) let the agent derive a sensible mobile layout from defaults (clearly note this in the report — the section's mobile match cannot be verified against an input).
+3. **Brand colors / typography** — if the screenshot is from an unrelated brand, the user must tell us what colors and fonts to map to. Otherwise we'll extract from the image and may get them wrong.
+4. **Theme settings to source colors from** — the section should still use `var(--color-*)` variables from `settings/theme.json`. Ask which theme settings the screenshot's brand colors should map to (e.g. "the orange button → `--color-primary`").
+
+## 2. Vision extraction protocol
+
+Read the screenshot directly (the Read tool sees PNG/JPG natively). For each visible element, extract approximate values:
+
+| Property | Method |
+|---|---|
+| Colors | Eyedropper-style — sample dominant colors. Match to nearest token in `figma-variables.json`. If no match within ΔE 3, propose adding a new variable. |
+| Spacing | Estimate in 4px steps (the project's spacing scale is `Spacing/4 Multiples`). Pad/gap values almost always land on multiples of 4. |
+| Typography | Identify font weight (thin / regular / medium / semibold / bold) and approximate size in 2px steps. Verify the font-family against `assets/` and `theme.json`. |
+| Border radius | Round to nearest of 4, 8, 12, 16, 24, full. |
+| Image aspect ratio | Eyeball + verify against common ratios (1:1, 4:3, 16:9, 3:2). |
+| Shadows | Note presence and rough strength (sm / md / lg). Tailwind shadow utilities are usually close enough. |
+
+For everything ambiguous, **mark it `?` in the spec table** — do not guess past the user's tolerance.
+
+## 3. Cross-reference theme tokens
+
+Before finalizing the spec, open `figma-variables.json` and `settings/theme.json`. Map every extracted value to an existing variable where possible. This is critical — hardcoded hex values from a screenshot will break the theme's customizer.
+
+## 4. Confirm before building
+
+Produce the draft spec table and **ask the user to approve** before stage 4 begins. Screenshot input has more ambiguity than Figma; user review at this point saves an iteration cycle.
+
+## 5. Output artefacts
+
+```
+<scratchpad>/intake/<section_name>/
+  screenshot-desktop.png       (copied from upload)
+  screenshot-mobile.png        (copied from upload, if provided)
+  vision-notes.md              (per-element extraction notes, what was guessed)
+  ambiguity-questions.md       (questions the user must answer before build)
+```
+
+## 6. Gotchas
+
+- Screenshot DPI matters — a 2× macOS screenshot is twice the pixel dimensions. Ask the user for the source viewport width if dimensions look off.
+- JPEG compression artefacts can shift perceived colors by a few units. Lean on the theme token list when possible rather than extracted hex.
+- If the screenshot was taken at a non-standard browser zoom (e.g. 110%), spacing measurements will be off. Cross-check with any reference URL the user can share.
+- Don't try to extract text content from the screenshot for the schema defaults — ask the user for the copy. OCR'd headlines are almost always slightly wrong.

package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/inputs/url.md

@@ -0,0 +1,88 @@
+# Input handler — Live website URL
+
+Triggered when the user says "build this like xyz.com" or pastes a URL.
+
+## 1. Tooling check
+
+This handler needs **Claude in Chrome** (`mcp__Claude_in_Chrome__*`) for computed-style extraction. If only `mcp__workspace__web_fetch` is available, you can only read raw HTML — degrade gracefully and tell the user the fidelity will be lower than Figma or screenshot inputs.
+
+If Claude in Chrome is connected but the user hasn't selected a browser, call `list_connected_browsers` then `select_browser`.
+
+## 2. Intake steps
+
+1. **`navigate`** to the URL.
+2. **`resize_window` 1440 × 900** — desktop viewport.
+3. **`get_page_text`** — DOM with text content. Save raw.
+4. **`javascript_tool`** — run a small script to dump computed styles of every visible element in the target section. Example:
+
+   ```js
+   const target = document.querySelector('SELECTOR_FROM_USER');
+   const out = [];
+   function walk(node, depth = 0) {
+     if (node.nodeType !== 1) return;
+     const cs = getComputedStyle(node);
+     out.push({
+       depth,
+       tag: node.tagName,
+       cls: node.className,
+       rect: node.getBoundingClientRect(),
+       styles: {
+         display: cs.display,
+         padding: cs.padding,
+         margin: cs.margin,
+         gap: cs.gap,
+         background: cs.backgroundColor,
+         color: cs.color,
+         font: cs.font,
+         lineHeight: cs.lineHeight,
+         borderRadius: cs.borderRadius,
+         boxShadow: cs.boxShadow,
+       },
+     });
+     node.childNodes.forEach((c) => walk(c, depth + 1));
+   }
+   walk(target);
+   JSON.stringify(out);
+   ```
+
+   Ask the user for the CSS selector that bounds the target section (e.g. `header.site-header`, `.hero`, `section#products`). If they don't know, navigate them through it: take a screenshot, ask them to point at the bounding element.
+5. **Screenshot** the section with Claude in Chrome's screenshot capability. Crop to just the target section using the bounding rect from step 4.
+6. **`resize_window` 375 × 812** — mobile viewport. Repeat steps 4–5 for mobile.
+7. **`read_console_messages`** + **`read_network_requests`** — capture font loads and any errors. Helps identify the actual font stack vs what's in `font-family`.
+
+## 3. Map computed styles to theme tokens
+
+Live sites use raw hex / px values. The output section must use the **target theme's** tokens, not the source site's. For each computed value:
+
+1. Find the nearest token in `figma-variables.json` (ΔE < 3 for colors, exact match for spacing/radius).
+2. If no nearby token exists, ask the user:
+   - "The source uses #FF6B35 — should the target theme adopt this as `--color-primary`, or map it to your existing `--color-primary` (#XYZ)?"
+
+Never silently hardcode a value from the source site. The whole point of the theme system is that every color/spacing/font is a customizable token.
+
+## 4. Section selection — be precise
+
+Live sites usually have **everything**: nav, hero, footer, modals, popups. Insist the user identifies the **exact** section to clone. Pull the bounding selector and crop to it. Don't try to reconstruct an entire homepage from a URL — that's out of scope (use full-theme builds for that).
+
+## 5. Output artefacts
+
+```
+<scratchpad>/intake/<section_name>/
+  url.txt                       (the source URL)
+  selector.txt                  (the CSS selector used as the bound)
+  desktop.png                   (cropped section, 1440 viewport)
+  mobile.png                    (cropped section, 375 viewport)
+  computed-styles-desktop.json
+  computed-styles-mobile.json
+  dom.html                      (saved HTML of the section)
+  console-errors.txt
+  font-requests.txt             (from network log — what fonts actually loaded)
+```
+
+## 6. Gotchas
+
+- Computed styles include browser defaults — filter out values that look like UA defaults (e.g. `margin: 0px` everywhere).
+- Some sites use CSS-in-JS / utility frameworks (Tailwind, Bootstrap) — the class names are noise, not signal. Always trust computed styles, never the class strings.
+- Behind-Cloudflare / paywalled sites may not be fetchable. Fall back to asking the user for a screenshot.
+- Dynamic content (lazy-loaded images, animation states) — wait for `networkidle` before snapshotting. If the section has an animation, screenshot at the end-state.
+- Anti-bot challenges may block Chrome — if so, surface the issue and fall back to screenshot input.