@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/pixel-diff.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * pixel-diff.mjs — render a URL in headless Chrome, compare against a Figma reference image.
+ *
+ * Usage:
+ *   node pixel-diff.mjs \
+ *     --rendered-url http://localhost:3000/home \
+ *     --figma-image  /path/to/figma-desktop.png \
+ *     --viewport     1440x900 \
+ *     --selector     "#section-hero"          (optional — crop to this element)
+ *     --threshold    0.1                       (pixelmatch threshold, default 0.1)
+ *     --out          /path/to/pixel-diff.json
+ *
+ * Output JSON shape:
+ *   {
+ *     "rendered_url": "...",
+ *     "viewport": { "width": 1440, "height": 900 },
+ *     "selector": "#section-hero",
+ *     "metrics": {
+ *       "mismatched_pixels": 12345,
+ *       "total_pixels": 1296000,
+ *       "mismatch_ratio": 0.0095,
+ *       "mean_delta_e": 1.4,
+ *       "max_delta_e": 4.2
+ *     },
+ *     "regions": [ { "x":..., "y":..., "w":..., "h":..., "delta_e":... }, ... ],
+ *     "verdict": "PASS" | "FAIL",
+ *     "rendered_screenshot": "/path/written.png",
+ *     "diff_image": "/path/diff.png"
+ *   }
+ *
+ * Pass thresholds (default):
+ *   mean_delta_e   < 2.0
+ *   max_delta_e    < 5.0
+ *   mismatch_ratio < 0.03
+ *
+ * Dependencies (install in this theme if missing):
+ *   puppeteer
+ *   pixelmatch
+ *   pngjs
+ *
+ * If they are missing, run:
+ *   npm install --no-save puppeteer pixelmatch pngjs
+ */
+
+import puppeteer from 'puppeteer';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = parseArgs(process.argv.slice(2));
+const renderedUrl = required(args, 'rendered-url');
+const figmaImagePath = required(args, 'figma-image');
+const viewport = parseViewport(required(args, 'viewport'));
+const selector = args.selector || null;
+const threshold = parseFloat(args.threshold ?? '0.1');
+const outPath = required(args, 'out');
+
+const PASS = { meanDeltaE: 2.0, maxDeltaE: 5.0, mismatchRatio: 0.03 };
+
+(async () => {
+  if (!fs.existsSync(figmaImagePath)) {
+    fail(`Figma reference image not found: ${figmaImagePath}`);
+  }
+
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  });
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: viewport.width, height: viewport.height, deviceScaleFactor: 1 });
+    await page.goto(renderedUrl, { waitUntil: 'networkidle2', timeout: 60_000 });
+
+    // Optional small extra wait for late-loading images / fonts
+    await page.evaluate(() => document.fonts && document.fonts.ready);
+    await new Promise((r) => setTimeout(r, 500));
+
+    const renderedPath = outPath.replace(/\.json$/, '-rendered.png');
+    if (selector) {
+      const el = await page.$(selector);
+      if (!el) fail(`Selector not found in DOM: ${selector}`);
+      await el.screenshot({ path: renderedPath });
+    } else {
+      await page.screenshot({ path: renderedPath, fullPage: false });
+    }
+
+    const rendered = readPng(renderedPath);
+    const figma = readPng(figmaImagePath);
+
+    // Resize figma to match rendered if dimensions differ. pixelmatch needs identical sizes.
+    // Simple approach: write canvas with sharp-like manual scaling? We avoid extra deps —
+    // require the caller to provide a Figma image at the right dimensions. If they don't match,
+    // we crop or pad and warn.
+    let figmaForCompare = figma;
+    if (figma.width !== rendered.width || figma.height !== rendered.height) {
+      figmaForCompare = resizeOrPad(figma, rendered.width, rendered.height);
+    }
+
+    const diff = new PNG({ width: rendered.width, height: rendered.height });
+    const mismatchedPixels = pixelmatch(
+      rendered.data, figmaForCompare.data, diff.data,
+      rendered.width, rendered.height,
+      { threshold, diffColor: [255, 0, 0], includeAA: false }
+    );
+
+    const diffPath = outPath.replace(/\.json$/, '-diff.png');
+    fs.writeFileSync(diffPath, PNG.sync.write(diff));
+
+    const totalPixels = rendered.width * rendered.height;
+    const mismatchRatio = mismatchedPixels / totalPixels;
+
+    // Approximate ΔE: pixelmatch doesn't compute it directly. We sample the diff regions
+    // and compute mean / max ΔE between corresponding pixels using a basic Lab approximation.
+    const { meanDeltaE, maxDeltaE } = computeDeltaE(rendered, figmaForCompare);
+
+    const verdict = (
+      meanDeltaE < PASS.meanDeltaE &&
+      maxDeltaE  < PASS.maxDeltaE &&
+      mismatchRatio < PASS.mismatchRatio
+    ) ? 'PASS' : 'FAIL';
+
+    const report = {
+      rendered_url: renderedUrl,
+      viewport: { width: viewport.width, height: viewport.height },
+      selector,
+      metrics: {
+        mismatched_pixels: mismatchedPixels,
+        total_pixels: totalPixels,
+        mismatch_ratio: round(mismatchRatio, 4),
+        mean_delta_e: round(meanDeltaE, 2),
+        max_delta_e: round(maxDeltaE, 2),
+      },
+      verdict,
+      rendered_screenshot: renderedPath,
+      diff_image: diffPath,
+    };
+
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, JSON.stringify(report, null, 2));
+    console.log(JSON.stringify(report, null, 2));
+  } finally {
+    await browser.close();
+  }
+})().catch((e) => fail(e.message ?? String(e)));
+
+// ─── helpers ───────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+      out[key] = val;
+    }
+  }
+  return out;
+}
+function required(args, k) { if (!args[k]) fail(`Missing --${k}`); return args[k]; }
+function parseViewport(s) {
+  const m = String(s).match(/^(\d+)x(\d+)$/);
+  if (!m) fail(`Invalid --viewport "${s}", expected WxH e.g. 1440x900`);
+  return { width: +m[1], height: +m[2] };
+}
+function readPng(p) { return PNG.sync.read(fs.readFileSync(p)); }
+function round(n, d) { return Math.round(n * 10 ** d) / 10 ** d; }
+function fail(msg) { console.error('pixel-diff error:', msg); process.exit(2); }
+
+function resizeOrPad(src, w, h) {
+  // Minimal no-deps resize: nearest-neighbor. For high-fidelity comparison this is OK because
+  // we're looking at large regions, not single pixels. For better results, install `sharp`
+  // and replace this function.
+  const dst = new PNG({ width: w, height: h });
+  const sx = src.width / w, sy = src.height / h;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const ix = Math.min(src.width - 1, Math.floor(x * sx));
+      const iy = Math.min(src.height - 1, Math.floor(y * sy));
+      const di = (y * w + x) * 4;
+      const si = (iy * src.width + ix) * 4;
+      dst.data[di]     = src.data[si];
+      dst.data[di + 1] = src.data[si + 1];
+      dst.data[di + 2] = src.data[si + 2];
+      dst.data[di + 3] = src.data[si + 3];
+    }
+  }
+  return dst;
+}
+
+function computeDeltaE(a, b) {
+  // Approximate ΔE via RGB Euclidean (faster, no Lab conversion). Calibrated empirically.
+  let sum = 0, max = 0, count = 0;
+  for (let i = 0; i < a.data.length; i += 4) {
+    // Skip transparent pixels in figma reference
+    if (a.data[i + 3] < 10 || b.data[i + 3] < 10) continue;
+    const dr = a.data[i] - b.data[i];
+    const dg = a.data[i + 1] - b.data[i + 1];
+    const db = a.data[i + 2] - b.data[i + 2];
+    const d = Math.sqrt(dr * dr + dg * dg + db * db) / 4.42; // crude scale to ~ΔE units
+    sum += d; count++;
+    if (d > max) max = d;
+  }
+  return { meanDeltaE: count ? sum / count : 0, maxDeltaE: max };
+}

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/record-build-metrics.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * record-build-metrics.mjs — aggregate build stats for end-of-run report.
+ *
+ * Usage:
+ *   node record-build-metrics.mjs templates/<theme_name>
+ *
+ * Reads scratchpad artefacts and theme folder. Outputs JSON summary.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const themePath = process.argv[2];
+if (!themePath) {
+  console.error('Usage: node record-build-metrics.mjs templates/<theme_name>');
+  process.exit(2);
+}
+
+const themeName = path.basename(themePath);
+const repoRoot = path.resolve(themePath, '../..');
+const scratchpad = path.join(repoRoot, '.claude', 'scratchpad', themeName);
+
+function countFiles(dir, ext) {
+  if (!fs.existsSync(dir)) return 0;
+  return fs.readdirSync(dir).filter(f => f.endsWith(ext)).length;
+}
+
+function walkVisualDiffs(root) {
+  const results = [];
+  if (!fs.existsSync(root)) return results;
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name === 'visual-diff.md') {
+        const content = fs.readFileSync(full, 'utf-8');
+        const critical = (content.match(/CRITICAL/gi) || []).length;
+        const hasZeroCritical = /0 CRITICAL|CRITICAL.*0 issues|no CRITICAL/i.test(content);
+        results.push({
+          path: path.relative(scratchpad, full),
+          critical_mentions: critical,
+          pass: hasZeroCritical || !/CRITICAL — [1-9]/i.test(content),
+        });
+      }
+    }
+  }
+  walk(root);
+  return results;
+}
+
+function parsePageReports(root) {
+  const pages = [];
+  const pagesDir = path.join(root, 'pages');
+  if (!fs.existsSync(pagesDir)) return pages;
+  for (const page of fs.readdirSync(pagesDir)) {
+    const reportPath = path.join(pagesDir, page, 'report.md');
+    if (!fs.existsSync(reportPath)) continue;
+    const content = fs.readFileSync(reportPath, 'utf-8');
+    const sectionsMatch = content.match(/SECTIONS BUILT:\s*(\d+)/i);
+    pages.push({
+      page,
+      sections_built: sectionsMatch ? Number(sectionsMatch[1]) : null,
+      has_report: true,
+    });
+  }
+  return pages;
+}
+
+const startedPath = path.join(scratchpad, 'build-started.json');
+let startedAt = null;
+let durationMs = null;
+if (fs.existsSync(startedPath)) {
+  try {
+    const s = JSON.parse(fs.readFileSync(startedPath, 'utf-8'));
+    startedAt = s.started_at;
+    if (startedAt) durationMs = Date.now() - new Date(startedAt).getTime();
+  } catch { /* ignore */ }
+}
+
+const sections = countFiles(path.join(themePath, 'sections'), '.liquid');
+const snippets = countFiles(path.join(themePath, 'snippets'), '.liquid');
+const pages = countFiles(path.join(themePath, 'pages'), '.json');
+const visualDiffs = walkVisualDiffs(scratchpad);
+const pageReports = parsePageReports(scratchpad);
+
+const summary = {
+  theme: themeName,
+  started_at: startedAt,
+  finished_at: new Date().toISOString(),
+  duration_ms: durationMs,
+  duration_human: durationMs
+    ? `${Math.floor(durationMs / 60000)}m ${Math.round((durationMs % 60000) / 1000)}s`
+    : null,
+  files: { sections, snippets, pages },
+  visual_verify: {
+    sections_with_diff: visualDiffs.length,
+    sections_passing: visualDiffs.filter(d => d.pass).length,
+    sections_failing: visualDiffs.filter(d => !d.pass).length,
+  },
+  page_reports: pageReports,
+  token_estimate: {
+    note: 'Approximate — Cursor does not expose per-run token counts to agents.',
+    profiles: {
+      small: '800K–1.5M tokens (≤15 sections, ~1 verify iteration each)',
+      medium: '1.5M–3M tokens (20–30 sections, 1–2 iterations)',
+      large: '3M–6M+ tokens (30+ sections, multiple visual re-loops)',
+    },
+    suggested_profile: sections <= 15 ? 'small' : sections <= 30 ? 'medium' : 'large',
+  },
+  time_estimate: {
+    note: 'Wall-clock varies with parallel agents and visual re-loop count.',
+    typical_first_build: '35–60 min for a 5-page theme',
+    typical_single_page_rerun: '5–15 min',
+  },
+};
+
+console.log(JSON.stringify(summary, null, 2));

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

@@ -0,0 +1,131 @@
+# Level B — Section builder (one section only)
+
+Spawned by **Level A (page orchestrator)**. Builds **one section**. Does not see other sections or the full page Figma tree for coding purposes.
+
+**Scope rule:** `get_design_context` is called on the **section's node ID only**. Never on the parent page frame. See `agent-hierarchy.md`.
+
+**The single most important rule, replacing everything from earlier versions:** the agent does NOT look at a section screenshot and improvise. It extracts a **Figma Spec** (per-element measurements, colors, fonts, positions, assets) from `get_design_context` and **transcribes** that into the section file. After building, it runs the visual verify loop until the rendered output matches the Figma in the agent's vision.
+
+## Read first (in this order)
+
+1. `agent-hierarchy.md` — Level B scope (section node only).
+2. `figma-extraction.md` — Figma Spec from section node only.
+3. `transcription-rules.md` — border-radius, colors, product card heights.
+4. `visual-verify-loop.md` — Chrome DevTools verify vs **section crop**.
+5. `image-sources.md` — `asset_url` for theme assets.
+6. `ask-developer.md` — when to ask instead of guessing.
+7. `zcommerce-docs/sections.md` — section structure rules.
+8. `zcommerce-docs/reference/schema-types.md` — schema field types (READ every time, don't guess).
+9. `zcommerce-docs/reference/filters.md` — valid Liquid filters.
+10. `zcommerce-docs/reference/tags.md` — valid Liquid tags (only 13 — no Shopify-only tags).
+11. `code-quality.md` — code budgets.
+
+Reading just the screenshot was what produced 5% accuracy themes. The Figma Spec is the contract.
+
+## Inputs you receive
+
+From the page orchestrator:
+- **`section_name`** — snake-case filename.
+- **`archetype`** — hero, product-grid, PDP, etc. (used only for sibling-theme logic reference — never for design/asset reference).
+- **`figma_node_id`** — the section's specific Figma node. If missing, ASK the developer (see `ask-developer.md`).
+- **`theme_folder`** — `<theme>/` (the theme root folder).
+- **`scratchpad`** — `.claude/scratchpad/<theme>/pages/<page>/sections/<section_name>/`.
+- **`snippet_registry`** — path to pre-built snippets you can render via `{% render %}`.
+- **`page_url`** — full URL from `dev-config.json` (e.g. `http://localhost:3000/home`). If missing or unconfirmed, write `needs-developer.md` and escalate — do not guess.
+
+## Workflow (8 phases — every phase is mandatory)
+
+### Phase 1 — Confirm the Figma node (~10s)
+
+If `figma_node_id` is missing or marked uncertain, ASK the developer immediately. Don't try to infer from the parent page screenshot — that's how earlier versions hallucinated the wrong section boundaries.
+
+### Phase 2 — Extract the Figma Spec (~2-3min)
+
+Follow `figma-extraction.md` + `transcription-rules.md`:
+- Call `get_design_context` on **`figma_node_id` (section frame only)** — NOT the parent page node.
+- Record `border_radius` per element — default 0 means no `rounded-*` in code.
+- Record exact colors → token map; no guessing from sibling themes.
+- For product grids: record fixed media box `w`×`h` and `object_fit` per card.
+- Walk the tree, extract every element's measurements/colors/fonts/positions.
+- Extract image assets via `get_screenshot` on image nodes, save base64 PNGs to `assets/<section>-<purpose>.png`.
+- Map colors → theme tokens. Log unmapped to `unmapped-colors.md`.
+- Save the spec to `<scratchpad>/figma-spec.json`.
+
+**Hard rule:** if Phase 2 produces nothing (Figma MCP unavailable, node not accessible), STOP and ask the developer. Do not proceed to Phase 3 without a spec — that's the no-imagination rule.
+
+### Phase 3 — Read 3+ sibling implementations for LOGIC only (~30s)
+
+Per `exemplars.md`, read siblings for **logic only** (loops, schema types, web components, i18n).
+
+**Forbidden from siblings:** colors, border-radius, spacing, typography, shadows, card dimensions. All visual values come from `figma-spec.json` only (`transcription-rules.md`).
+
+### Phase 4 — Plan the markup (~1min)
+
+For every element in the Figma Spec, map to a Liquid element:
+- Frame/Container → `<section>` / `<div>` with `{% style %}` block holding exact CSS values from the spec.
+- Text → `<h1>` / `<h2>` / `<p>` with content from spec.text.content AND a schema setting so the admin can override.
+- Image → theme asset: `{{ '<section>-<purpose>.png' | asset_url }}`; schema setting: `{{ section.settings.image.url | asset_url }}` (see `image-sources.md`).
+- Layout → CSS grid/flex with exact gap, padding, alignment from spec.layout.
+
+Plan the schema: every **heading/title/label** becomes a `text` setting; every **description/body** becomes a `richtext` setting; every image becomes an `image_picker` setting with the extracted asset as default, every URL becomes a `url` setting. **Never use `richtext` for heading blocks or fields rendered in `<h1>`–`<h6>`.** Schema field IDs follow the spec element IDs.
+
+Plan inter-section structure: respect the section anatomy (script tags → style block → liquid assigns → conditional → wrapper → schema).
+
+### Phase 5 — Write the section file (~1-2min)
+
+Write `sections/<section_name>.liquid` by transcription from the Figma Spec. No improvising. Every measurement is the value from the spec — either a theme token (preferred when mapped) or an exact px/hex (otherwise).
+
+After writing, also append to `i18n/en.json` (runtime keys for `| t` references) and `i18n/en.schema.json` (schema label keys). Re-read `zcommerce-docs/i18n.md` if unsure which file a key belongs in.
+
+### Phase 6 — Lint (mandatory, blocking)
+
+```bash
+node .claude/skills/theme-from-figma/scripts/lint-section.mjs \
+  sections/<section_name>.liquid
+```
+
+Must return PASS. If FAIL, fix and re-run before continuing.
+
+### Phase 7 — 3-gate verify via Chrome DevTools MCP (mandatory, blocking)
+
+Follow `visual-verify-loop.md`:
+
+1. **Visual** — desktop + mobile `take_screenshot` vs Figma `get_screenshot`; write `visual-diff.md` with CRITICAL/MINOR/SUGGESTION.
+2. **A11y** — `lighthouse_audit` mode `navigation` device `mobile` on the page route.
+3. **Perf** — `lighthouse_audit` mobile baseline (flag if score < 85 on heavy pages).
+4. **Network** — `list_network_requests` for image 404s; fix with `asset_url` per `image-sources.md`.
+5. Fix CRITICAL items only. Re-loop. **Max 3 iterations.**
+
+**If 3 iterations don't converge:** write `<scratchpad>/needs-developer.md` and exit. Page orchestrator surfaces in batch.
+
+**PASS = `visual-diff.md` with 0 CRITICAL + no section-related console errors.**
+
+### Phase 8 — Final report
+
+Write `<scratchpad>/report.md`:
+
+```
+SECTION: hero-banner
+NODE: 2613:147
+
+FIGMA SPEC: <scratchpad>/figma-spec.json   (47 elements, 4 image assets extracted)
+LINT: PASS
+VISUAL DIFF (final iteration): <scratchpad>/visual-diff.md
+  CRITICAL: 0
+  MINOR: 2 (View All chevron gap, panel border-radius 1px off)
+  SUGGESTION: 1
+ITERATIONS: 3
+ASSETS WRITTEN: 4 (hero-banner-panel-left-penguin.png, hero-banner-panel-middle-cars.png, hero-banner-panel-right-robot.png, hero-banner-decorative-stripe.png)
+SNIPPETS RENDERED: (none — section is self-contained)
+UNRESOLVED (for orchestrator to batch):
+  (none)
+```
+
+## Things to NOT do
+
+- Don't skip the Figma Spec. No spec = no build.
+- Don't write from a screenshot impression. Use the spec.
+- Don't loop on visual diff without writing the structured `visual-diff.md`. The diff is the contract; vague "still doesn't look right" loops produce nothing.
+- Don't substitute a sibling theme's asset. If extraction fails, ask the developer.
+- Don't claim "verified pass" without the visual-diff.md and Figma Spec in scratchpad. `verify-theme.mjs` checks for both.
+- Don't decide on hover/focus/animation states that aren't in Figma. Flag to the developer.

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

@@ -0,0 +1,75 @@
+# Subagent → main agent escalation
+
+Every question, blocker, or notification from a **page orchestrator** or **section subagent** MUST appear on the **main agent screen**. Subagents must not silently fail or defer.
+
+---
+
+## What must escalate to the main agent
+
+| Event | Main agent action |
+|---|---|
+| `needs-developer.md` written | Surface immediately in chat with section/page name |
+| `unresolved.md` with `blocking: true` | Batch into `AskUserQuestion` before continuing |
+| Dev server not running | Ask developer to start OR start with confirmed `storeUrl` |
+| Page URLs not confirmed | Pause build; run URL confirmation flow (`dev-server-and-urls.md`) |
+| Visual verify stuck after 3 iterations | Show CRITICAL items from `visual-diff.md` |
+| Subagent aborted / timed out | Report which page/section; parent takes over or re-spawns |
+| Figma MCP unavailable | Ask developer to select frame or provide URL |
+
+---
+
+## Subagent report format (required)
+
+Each subagent ends with a short **ESCALATION** block in its return message:
+
+```markdown
+## ESCALATION (for main agent)
+
+**Page/Section:** product / product-details
+**Verdict:** PASS | NEEDS_REVIEW | BLOCKED
+
+**Developer action needed:** yes | no
+
+**Questions (if any):**
+1. [blocking] Collection URL — used /collections/all, 404. Confirm correct handle?
+
+**Artifacts:**
+- scratchpad/.../visual-diff.md (2 CRITICAL remaining)
+- scratchpad/.../needs-developer.md
+
+**Notify main agent:** YES — do not proceed to Stage 2 until resolved.
+```
+
+---
+
+## Main orchestrator duties
+
+1. **At Stage 0** — collect `storeUrl` + confirm page URLs → write `dev-config.json`
+2. **After each page agent completes** — read its ESCALATION block; post summary to developer chat
+3. **Before Stage 2 consolidation** — aggregate all `needs-developer.md` files into one developer-facing list
+4. **Never hide subagent failures** — if collection agent aborted, say so explicitly
+
+---
+
+## Page orchestrator batching
+
+Page orchestrators collect section `unresolved.md` files and ask the developer **one batch per page** (max 4 questions via `AskUserQuestion`).
+
+But the **main orchestrator still gets a copy** of every batch in the consolidated report — even if the page agent already asked.
+
+---
+
+## Example main-agent message to developer
+
+```
+Subagent updates:
+
+✅ index — 8 sections built, visual verify PASS
+✅ product — 2 sections, 0 CRITICAL after 1 iteration
+⚠️ collection — BLOCKED: dev server returned 404 for /collections/all
+   → Please confirm collection URL (I guessed /collections/all-products)
+
+❌ blog_list subagent aborted — parent will retry
+
+Action needed: confirm collection + blog list URLs (see dev-server-and-urls.md)
+```

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

@@ -0,0 +1,98 @@
+# Transcription rules — Figma spec → code (Level B only)
+
+Level B agents transcribe `figma-spec.json` into Liquid/CSS. **Zero improvisation.**
+
+---
+
+## Border radius
+
+| Figma spec | Code |
+|---|---|
+| `border_radius` absent or all `0` | **No** `rounded-*`, **no** `border-radius` in CSS |
+| `border_radius: 20` (uniform) | `border-radius: 20px` in scoped `{% style %}` OR token if matches `--radius-card` |
+| `border_radius` per corner | Exact px per corner in `{% style %}` |
+
+**Never** apply `rounded-lg`, `rounded-card`, or theme `--radius-card` unless the Figma spec row explicitly has radius > 0 for that element.
+
+If Figma shows square buttons (`border_radius: 0`) — use `border-radius: 0`, not `rounded-full`.
+
+---
+
+## Colors
+
+1. Extract exact hex from Figma element fill/stroke.
+2. Map to theme token via `figma-variables.json` (ΔE < 1.5).
+3. Use `var(--color-*)` in code — never raw hex in markup.
+4. If unmapped → log in `unmapped-colors.md` and ask developer — **do not pick a "close" token silently**.
+
+| Wrong | Right |
+|---|---|
+| `var(--color-primary)` on body text because "primary is brand" | Use spec text color → `--color-heading` or `--color-body` |
+| Sibling theme's peach background | Spec background → `--section-bg-accent` or mapped token |
+
+Each element in `figma-spec.json` must have a `token_used` field after mapping.
+
+---
+
+## Product / image cards (equal heights)
+
+When Figma shows a **grid of product cards** with uniform card frames:
+
+```json
+{
+  "id": "product-card-media",
+  "position": { "w": 280, "h": 330 },
+  "image": { "object_fit": "contain" }
+}
+```
+
+Level B must enforce in CSS:
+
+```liquid
+{% style %}
+  #section-{{ section.id }} .product-card-media {
+    aspect-ratio: 280 / 330;   /* from spec w/h */
+    min-height: 330px;
+    overflow: hidden;
+  }
+  #section-{{ section.id }} .product-card-media img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;         /* from spec — usually contain for product shots */
+  }
+  #section-{{ section.id }} .product-card {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+  }
+{% endstyle %}
+```
+
+**Never** let `<img>` natural height drive card height in a grid — that causes the uneven heights you saw.
+
+For `object-fit`: use what Figma spec says (`cover` for hero banners, `contain` for product packshots on neutral bg).
+
+---
+
+## Typography
+
+Transcribe exact `font_size`, `font_weight`, `line_height` from spec into scoped CSS or Tailwind only when class matches **exact px** from `tailwind.config.js` theme extension.
+
+Do not round 44px → `text-4xl` if `text-4xl` resolves to 36px in this theme.
+
+---
+
+## Spacing
+
+`gap`, `padding`, `margin` — exact px from spec. One Tailwind step off = MINOR in visual diff; fix in re-loop.
+
+---
+
+## What Level B checks before claiming PASS
+
+- [ ] Every visible element in Figma has a row in `figma-spec.json`
+- [ ] No `rounded-*` on elements where spec `border_radius` is 0
+- [ ] All colors trace to spec → token map
+- [ ] Product grids have fixed media box dimensions from spec
+- [ ] `lint-section.mjs` PASS
+- [ ] `visual-diff.md` 0 CRITICAL (section crop only)