@zohofinance/commerce 1.0.0 → 1.1.0

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

@@ -0,0 +1,102 @@
+# The Design Spec Table
+
+The spec table is the build contract between intake and code. **Every value the section must produce is enumerated here in pixels / hex / numeric units before any Liquid is written.** Self-compare against this table is what makes the build pass on the first try.
+
+## Columns
+
+| # | Element | Property | Desktop | Mobile | Token / Tailwind | Source | Notes |
+|---|---------|----------|--------:|-------:|------------------|--------|-------|
+| 1 | section wrapper | padding-y | 64 | 40 | `py-theme-16 md:py-theme-16` + style | figma-context.json#node-12:3 | uses section padding var |
+
+- `#` — row number, used in self-compare reports.
+- `Element` — selector-style identifier. Use descriptive names — `hero h1`, `cta button`, `card image`. Be consistent so verification can match by name.
+- `Property` — one CSS property per row. **Never** combine (no "padding: 64 40 32 40"). One row per value.
+- `Desktop` / `Mobile` — numeric value. Use units `px`, `%`, `rem` consistently; default to `px`. Leave blank if same as desktop and the next-up breakpoint covers it.
+- `Token / Tailwind` — the Tailwind class or CSS variable that produces this value. Mandatory before stage 4 begins (this is what gets typed into the `.liquid` file).
+- `Source` — pointer back to the intake artefact. For Figma: `figma-context.json#<node-id>`. For screenshot: `screenshot-desktop.png#estimated`. For URL: `computed-styles-desktop.json#<index>`.
+- `Notes` — anything the build needs to know (e.g. "uses dynamic value from section.settings.padding_top — schema default = 64").
+
+## Required row coverage
+
+For every visible element in the section, the table **must** have rows for:
+
+| Element type | Required rows |
+|---|---|
+| **Section wrapper** | tag, padding-top, padding-bottom, padding-x, background, max-width |
+| **Any container** | display, flex-direction OR grid-template-*, gap, justify-content, align-items, padding |
+| **Text** | font-family, font-size, font-weight, line-height, letter-spacing, color, text-align |
+| **Image** | width, height OR aspect-ratio, object-fit, border-radius |
+| **Button / link** | padding-x, padding-y, font-size, font-weight, color, background, border, border-radius, hover-state |
+| **Icon** | size (w/h), color, stroke-width if SVG |
+| **Card / surface** | background, border, border-radius, box-shadow, padding |
+| **Divider** | thickness, color, margin |
+
+If a property is omitted because it's the browser default, that's fine — but mark it explicitly in a "defaults" row at the top so future readers know it was intentional.
+
+## Worked example — Hero banner section (Figma input)
+
+```
+#  Element              Property            Desktop  Mobile  Token / Tailwind                Source                       Notes
+1  section wrapper      padding-y           96       64      py-theme-24 md:py-theme-32      figma-context.json#node-12:3 dynamic via schema
+2  section wrapper      padding-x           80       16      px-theme-20 md:px-theme-4       figma-context.json#node-12:3 also --section-padding-x
+3  section wrapper      background          —        —       bg-primary                      figma-vars#color/primary     #1F2937
+4  section wrapper      min-height          640      auto    min-h-[640px] md:min-h-0        figma-context.json#node-12:3
+5  content grid         display             grid     flex    grid md:grid-cols-2 gap-theme-8 figma-context.json#node-12:5 mobile = column
+6  content grid         gap                 32       24      gap-theme-8 md:gap-theme-6      figma-context.json#node-12:5
+7  hero h1              font-family         —        —       font-display                    figma-vars#font/display       Inter
+8  hero h1              font-size           60       40      text-[60px] md:text-[40px]      figma-context.json#node-12:8 also fluid clamp option
+9  hero h1              font-weight         700      700     font-bold                       figma-context.json#node-12:8
+10 hero h1              line-height         1.05     1.1     leading-[1.05] md:leading-[1.1] figma-context.json#node-12:8
+11 hero h1              color               —        —       text-on-primary                 figma-vars#color/on-primary  #FFFFFF
+12 cta button           padding             16x32    14x28   px-theme-8 py-theme-4           figma-context.json#node-12:14
+13 cta button           background          —        —       bg-accent                       figma-vars#color/accent       #FB923C
+14 cta button           color               —        —       text-on-accent                  figma-vars#color/on-accent
+15 cta button           border-radius       8        8       rounded-theme-button            figma-vars#radius/sm
+16 cta button           font-size           18       16      text-lg md:text-base            figma-context.json#node-12:14
+17 hero image           aspect-ratio        4/3      4/5     aspect-[4/3] md:aspect-[4/5]    figma-context.json#node-12:20
+18 hero image           object-fit          —        —       object-cover                    figma-context.json#node-12:20
+```
+
+This is the contract the section file is built against. After build, the verification pipeline scans the generated `.liquid` and asserts every row.
+
+## Worked example — Screenshot input (less precise)
+
+Same columns, but values are best-estimate and many rows will carry `?`:
+
+```
+#  Element        Property      Desktop  Mobile  Token / Tailwind                  Source                      Notes
+1  section        padding-y     ~64      ~40     py-theme-16 md:py-theme-10        screenshot-desktop.png      ESTIMATED — confirm
+2  section        background    #FAFAFA  —       bg-neutral-50                     screenshot-desktop.png      sampled, ΔE 1.2 from token
+3  card           border-radius 12       12      rounded-xl                        screenshot-desktop.png      
+4  card           gap           ?        ?       gap-theme-?                       screenshot-desktop.png      ASK USER — could be 16 or 24
+```
+
+The `ASK USER` rows must be resolved before stage 4 begins. Build is blocked otherwise.
+
+## Worked example — URL input
+
+```
+#  Element        Property      Desktop  Mobile  Token / Tailwind          Source                                  Notes
+1  section        padding       80x120   32x16   py-theme-20 px-theme-30   computed-styles-desktop.json#3          source uses raw px
+2  section        background    #FFFFFF  —       bg-background             mapped: #FFFFFF → --color-background    exact match
+3  h1             font-size     48       32      text-5xl md:text-3xl      computed-styles-desktop.json#7
+4  h1             font-family   Inter    Inter   font-sans                 font-requests.txt: Inter-Bold.woff2     source loads Inter
+```
+
+URL inputs are mid-fidelity: spacing and sizes are exact (computed styles don't lie), but you still need to map raw colors to the target theme's variables.
+
+## Hard rules
+
+1. **One property per row.** Compound CSS (padding shorthand, font shorthand) is forbidden in the table.
+2. **No empty Token column** when entering stage 4. If a row's Tailwind/CSS variable is unknown, resolve it first.
+3. **No build before approval** for screenshot/URL inputs — the user reviews the spec to catch misreads.
+4. **Persist the table** to `.claude/scratchpad/<section_name>/spec-table.md` (markdown) and reload it for stage 5 verification.
+
+## Verifying Tailwind class names per target theme
+
+The example tables above use classes like `py-theme-16`, `gap-theme-8`, `rounded-theme-button`, `max-w-container-theme`. These are defined in **each theme's own** `tailwind.config.js` under `theme.extend.spacing` / `borderRadius` / `maxWidth`.
+
+Before finalizing the spec, **`cat tailwind.config.js`** and confirm every Tailwind theme-* class the spec references has a matching extend entry. If a class is missing:
+
+- The class is likely missing because the underlying CSS variable hasn't been added to `settings/theme.json` either. Add both, with user approval.
+- Or, fall back to **arbitrary-value Tailwind** (`py-[64px]`, `gap-[24px]`, `rounded-[8px]`) — these always work but bypass the theme's design token system. Use sparingly and only for one-off values that don't recur elsewhere in the theme.

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

@@ -0,0 +1,110 @@
+# Gate 3 — Accessibility (WCAG 2.1 AA)
+
+Run axe-core against the rendered section and assert zero critical/serious violations.
+
+## Two ways to run
+
+### Option A — CLI build path (most accurate, slowest)
+
+`npx @zohofinance/commerce theme build` already runs axe-core through puppeteer against the dev server. Run it and parse the output:
+
+```bash
+cd <theme_name>
+npx @zohofinance/commerce theme build
+```
+
+This spins up puppeteer, runs axe with tags `wcag2a, wcag2aa, wcag21a, wcag21aa`, and prints critical/serious violations. Failing causes the build to halt. Read the console output and surface the relevant violations.
+
+**Use this for the final gate check before declaring done.** Don't use it in tight iteration loops — it's slow.
+
+### Option B — Per-section axe injection (fast, for iteration)
+
+Faster for the inner loop. With Claude in Chrome:
+
+1. `navigate` to the section's host page on the dev server.
+2. `javascript_tool` — inject axe-core from CDN and run scoped to the section:
+
+   ```js
+   const s = document.createElement('script');
+   s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js';
+   s.onload = async () => {
+     const results = await axe.run(
+       document.querySelector('#section-<section_id>'),  // scope to just this section
+       {
+         runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] },
+         resultTypes: ['violations'],
+       },
+     );
+     window.__axeResult = JSON.stringify(results, null, 2);
+   };
+   document.head.appendChild(s);
+   ```
+
+3. Wait ~1s, then read back: `JSON.parse(window.__axeResult)`.
+4. Filter to `impact: critical` and `impact: serious`. These fail the gate.
+
+## Output format
+
+```
+GATE 3 — A11Y (axe-core, WCAG 2.1 AA)
+SCOPED TO: #section-<id>
+
+  PASS  no critical violations
+  PASS  no serious violations
+
+  MODERATE (1) — flagged, does not fail gate
+    [1] color-contrast — 1 node
+        target: .badge.bg-primary text-on-primary
+        contrast: 4.3:1 (needs 4.5:1 for AA)
+        Fix: darken --color-primary or use a different text token on the badge.
+
+  MINOR (0)
+```
+
+## What blocks the gate
+
+Critical or serious violations from any of these rules **must** be fixed:
+
+| axe rule | Why it matters |
+|---|---|
+| `image-alt`, `image-redundant-alt` | Screen readers need alt text |
+| `color-contrast` (4.5:1 normal, 3:1 large) | Low-vision readability |
+| `label`, `form-field-multiple-labels` | Form input labelling |
+| `link-name`, `button-name` | Interactive elements need accessible names |
+| `heading-order` | Heading hierarchy must be logical (`h1` → `h2` → `h3`) |
+| `aria-valid-attr`, `aria-allowed-attr` | ARIA attribute correctness |
+| `landmark-one-main`, `landmark-unique` | Page landmark structure |
+| `frame-title` | iframes need titles |
+| `html-has-lang` | (layout-level — not section's concern) |
+| `bypass` | Skip navigation (header section's concern) |
+
+## Section-author quick checks (catch before running axe)
+
+Most section a11y issues are predictable. Before running axe, eyeball the section file for:
+
+- **All `<img>` tags** — does each have `alt="{{ ... }}"` or `alt=""` (decorative)? Reject `alt="image"` placeholder strings.
+- **All `<a>` and `<button>`** — does each have meaningful text content, or `aria-label` if icon-only? Reject `<a><i class="icon"></i></a>` with no label.
+- **All `<input>` and `<select>`** — paired with a `<label for="...">` or wrapped in one?
+- **Heading hierarchy** — does the section start with `<h2>` (most sections shouldn't have `<h1>` — that's the page title in the layout)?
+- **Color contrast** — for any text-on-color combination, verify the theme tokens used pass 4.5:1. The most common failure is light text on a non-primary brand color.
+- **Focus states** — all interactive elements need visible `:focus-visible` styles. Tailwind's `focus:ring-2 focus:ring-offset-2` is a safe default.
+- **Decorative images** — when an image is decorative (next to text that already describes it), use `aria-hidden="true"` AND `alt=""`. Look at existing hero-banner sections across themes for good examples.
+
+## Color-contrast specifics
+
+The most-failed rule. Procedure to verify:
+
+1. For each text-on-background pair in the section, resolve both to actual hex (consult `figma-variables.json` and `theme.json`).
+2. Compute contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` where `L1` is the lighter luminance.
+3. Targets: ≥ 4.5:1 normal text, ≥ 3:1 for 18pt+ or 14pt+ bold (large text).
+
+If a contrast pair fails, the fix is usually one of:
+- Use a darker variant of the background (`--color-primary` → `--color-primary-dark`).
+- Use a different text token (`--color-on-primary` instead of `--color-heading`).
+- Add a semi-transparent overlay between background image and text (common for hero sections).
+
+Don't fix by hardcoding hex values — that breaks customization.
+
+## Iteration
+
+If the gate fails, fix in the section file (not in `theme.json` unless the fix is theme-wide), and re-run option B. Run option A once at the end for final sign-off.

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

@@ -0,0 +1,127 @@
+# Gate 4 — Performance (Lighthouse)
+
+Run Lighthouse against the section's host page, assert performance score and Core Web Vitals targets.
+
+## Two ways to run
+
+### Option A — CLI build path
+
+Same `npx @zohofinance/commerce theme build` runs Lighthouse via puppeteer. Failing scores halt the build.
+
+```bash
+cd <theme_name>
+npx @zohofinance/commerce theme build
+```
+
+Reads from the dev server URL (or its own ephemeral server) and prints the score per category. Use this once at the end of iteration.
+
+### Option B — Standalone Lighthouse via Node
+
+For per-section iteration, run Lighthouse from this theme's `node_modules` rather than relying on a global install:
+
+```bash
+# from the theme directory, with dev server running on port 3000:
+node ./node_modules/lighthouse/cli.js \
+  http://localhost:3000/<page_route> \
+  --output=json \
+  --output-path=./.claude/scratchpad/<section>/lighthouse.json \
+  --chrome-flags="--headless --no-sandbox" \
+  --only-categories=performance \
+  --form-factor=mobile \
+  --quiet
+```
+
+If lighthouse is not installed, add it as a one-shot:
+```bash
+npm install --no-save lighthouse
+node ./node_modules/lighthouse/cli.js http://localhost:3000/<page_route> --quiet
+```
+
+**Quick check via Claude in Chrome.** For LCP and CLS only (skipping the full Lighthouse run), inject this with `javascript_tool`:
+
+```js
+(async () => {
+  const lcp = await new Promise(r => {
+    new PerformanceObserver(list => {
+      const entries = list.getEntries();
+      r(entries[entries.length - 1].renderTime || entries[entries.length - 1].loadTime);
+    }).observe({ type: 'largest-contentful-paint', buffered: true });
+    setTimeout(() => r(null), 3000);
+  });
+  let cls = 0;
+  new PerformanceObserver(list => list.getEntries().forEach(e => { if (!e.hadRecentInput) cls += e.value; }))
+    .observe({ type: 'layout-shift', buffered: true });
+  await new Promise(r => setTimeout(r, 1000));
+  return { lcp, cls };
+})();
+```
+
+This is good enough for inner-loop iteration. Run real Lighthouse once at the end for the official gate.
+
+## Targets
+
+Default targets per the project's expectations. Adjust only if the user asks.
+
+| Metric | Target | Failure |
+|---|---|---|
+| Performance score | ≥ 90 | < 90 |
+| Largest Contentful Paint (LCP) | < 2.5s | ≥ 2.5s |
+| Cumulative Layout Shift (CLS) | < 0.1 | ≥ 0.1 |
+| Total Blocking Time (TBT) | < 200ms | ≥ 200ms |
+| First Contentful Paint (FCP) | < 1.8s | ≥ 1.8s |
+| Speed Index | < 3.4s | ≥ 3.4s |
+
+Mobile and desktop are both measured. Mobile is the harder bar — desktop usually passes if mobile does.
+
+## Output format
+
+```
+GATE 4 — PERFORMANCE (Lighthouse)
+PAGE: /home
+
+  desktop
+    Performance 96 · LCP 1.4s · CLS 0.01 · TBT 80ms · FCP 0.9s
+    PASS
+
+  mobile (simulated Slow 4G / 4x CPU)
+    Performance 88 · LCP 2.8s · CLS 0.04 · TBT 240ms · FCP 1.6s
+    FAIL — LCP 2.8s (> 2.5s), TBT 240ms (> 200ms)
+
+  Suspects (section-attributable):
+    [1] hero image — 480KB JPEG, no width/height → contributes to LCP delay AND CLS shift.
+        Fix: serve WebP, add explicit width/height attrs, mark loading="eager" on above-fold image.
+    [2] product-collection-carousel.js — 38KB, blocking on parse.
+        Fix: confirm `defer` attribute is set; consider lazy-loading the script if section is below fold.
+```
+
+## Section-author quick checks (catch before running Lighthouse)
+
+Most perf issues are predictable. Before running Lighthouse, audit the section file for:
+
+- **Above-fold images** — explicit `width` and `height` attributes (prevents CLS). `loading="eager"` and `fetchpriority="high"` on the LCP image. Use `image_url` filter so the platform serves optimized variants.
+- **Below-fold images** — `loading="lazy"`. Still need width/height.
+- **Background images** — use CSS `background-image` with `image-set()` and explicit `aspect-ratio` on the container.
+- **Fonts** — preload only the actually-used weights. `<link rel="preload" as="font" type="font/woff2" crossorigin>` for above-fold typography. Prefer `.woff2`.
+- **JS** — all `<script>` tags have `defer` (per `CLAUDE.md`). Confirm no inline `<script>` blocks doing render-blocking work.
+- **CSS** — section-specific styles inside `{% style %}` and scoped to `#section-{{ section.id }}` (already in the file anatomy). Avoid `@import` inside section CSS.
+- **Animations** — use `transform` and `opacity` (compositor-only). Avoid animating `width`, `height`, `top`, `left`, `margin` — they cause layout thrash.
+- **Web components** — load only the components this section uses. Don't pull in unused storefront JS.
+
+## When a section fails perf
+
+Diagnosis steps:
+
+1. Open Chrome DevTools Performance panel via `javascript_tool` (or rely on Lighthouse's "Opportunities" output).
+2. Identify which network requests or JS executions are attributable to this section. Sometimes the slow path is in a different section sharing a snippet.
+3. Fix in the section file first. If the fix needs to live in a shared snippet, **flag it** — changing a snippet affects every section using it. Run `impact <theme> <snippet>` (from `zcommerce-theme-builder`) to see the blast radius before editing.
+
+## Don't optimize blindly
+
+If a section passes perf but fails token-match or visual-diff, fix those first. Perf regressions during iteration almost always come from added content or animation — not from the original build.
+
+## Mobile-specific gotchas
+
+- Lighthouse simulates Slow 4G + 4× CPU throttling. Real devices may be faster, but the simulation is the gate.
+- A large hero image is the #1 LCP killer. Set `fetchpriority="high"` on the LCP image, preload it in the layout if it's predictable.
+- Web font flashes — use `font-display: swap` in `@font-face` declarations.
+- Layout shifts from late-loading content — reserve space with `min-height` or `aspect-ratio` on containers.

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

@@ -0,0 +1,87 @@
+# Gate 2 — Design-token exact match
+
+Strictly Figma-only. Skipped for screenshot and URL inputs because they have no normative token source.
+
+## Why this gate exists
+
+Visual diff catches "looks wrong" but misses numeric drift inside its tolerance band — 16px vs 17px both look fine but accumulate over a page. This gate asserts the **exact** Tailwind class / CSS variable / numeric value listed in each Design Spec Table row is present in the generated section file.
+
+## Procedure
+
+For each row in the spec table:
+
+1. Read `sections/<section_name>.liquid`.
+2. Extract the relevant value:
+   - For a Tailwind class row (`py-theme-16`) — search for that class on the matching element.
+   - For a CSS variable row (`var(--color-primary)`) — search inside the `{% style %}` block or inline `style="..."`.
+   - For a numeric default in the schema (padding_top default = 64) — locate it in the `{% schema %}` block.
+3. Assert match.
+
+The match scope is the element identified in the table's `Element` column. Map element names to selectors:
+
+| Spec row Element | Selector in generated code |
+|---|---|
+| `section wrapper` | the top-level `<section id="section-{{ section.id }}">` |
+| `content grid` / `content container` | the first child `<div>` inside the wrapper |
+| `hero h1` | `<h1>` inside the section |
+| `cta button` | `<a class="...btn...">` or `<button>` |
+| `card` | `<article>` or `<div class="...card...">` |
+| `hero image` | the largest `<img>` |
+
+If the table uses a non-obvious element name, the build phase must include a code comment marker (`{{-- spec:hero-h1 --}}`) so verification can grep for it.
+
+## Output format
+
+```
+GATE 2 — TOKEN MATCH (figma)
+SPEC ROWS: 18
+
+PASS  rows 1, 2, 4, 5, 6, 9, 10, 11, 13, 14, 15, 16, 17, 18 (14)
+FAIL  row 3  — section wrapper background
+        spec: bg-primary
+        found: bg-indigo-600 (raw Tailwind, not theme variable)
+FAIL  row 7  — hero h1 font-family
+        spec: font-display
+        found: font-sans
+FAIL  row 8  — hero h1 font-size desktop
+        spec: text-[60px]
+        found: text-5xl   (48px, off by 12)
+MISS  row 12 — cta button padding-y mobile
+        spec: py-theme-3.5
+        found: no responsive override → uses desktop value
+```
+
+- **PASS** — exact match.
+- **FAIL** — value present but wrong.
+- **MISS** — value absent (no class found on the element).
+- **TOLERATED** — value differs but inside tolerance and acceptable (use sparingly; record the reason).
+
+## Tolerance
+
+Hard rule: this gate uses **zero numeric tolerance**. The whole point is to catch what visual diff lets through. If a value is intentionally different from the spec, the spec is wrong — update it after user approval.
+
+The one exception is unit conversion that produces equivalent values:
+- `text-base` ≡ `text-[16px]` ≡ `text-[1rem]` (assuming 16px root) — pass.
+- `gap-4` ≡ `gap-[16px]` — pass.
+
+## Fix strategy
+
+When this gate fails:
+
+1. Group failures by element. A "wrong color on hero" usually has 3–4 cascading effects in adjacent rows.
+2. Open the section file and fix all related rows in one edit.
+3. Re-run the gate.
+
+Do not silently update the spec to match the code — that defeats the whole purpose. Spec changes require user approval.
+
+## Unmapped tokens
+
+If the spec table references a variable not yet defined in `figma-variables.json` or `theme.json`, the gate fails with `UNMAPPED`:
+
+```
+UNMAPPED row 4 — section wrapper min-height
+  spec: var(--hero-min-height) — token does not exist in theme.json
+  ACTION: add token or hardcode value with user approval
+```
+
+These must be resolved in stage 4 (build), not by suppressing the gate.

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

@@ -0,0 +1,123 @@
+# Gate 1 — Visual diff
+
+Render the built section in a real browser, screenshot it, compare to the input artefacts from stage 1.
+
+## Prerequisite
+
+Dev server running:
+```bash
+cd <theme_name>
+yarn run dev --storeUrl=<your store url>
+```
+Default port is 3000 unless `--port` was passed. If port 3000 is in use, the CLI auto-picks the next available port — check the CLI output.
+
+## Tools (concrete capture path)
+
+**Preferred:** Claude in Chrome.
+- `mcp__Claude_in_Chrome__navigate` — open the dev server URL.
+- `mcp__Claude_in_Chrome__resize_window` — set viewport.
+- `mcp__Claude_in_Chrome__read_page` — returns the rendered page including a visual snapshot the agent can inspect. **This is the screenshot mechanism for gate 1** — `read_page` is the tool that gives the agent the visual content, not a separate `take_screenshot` call.
+- `mcp__Claude_in_Chrome__find` — locate the section element by selector or text.
+- `mcp__Claude_in_Chrome__javascript_tool` — run JS for `scrollIntoView`, `getBoundingClientRect`, applying `:hover` states.
+- `mcp__Claude_in_Chrome__gif_creator` — captures a GIF for animated sections; use sparingly.
+
+**Sharing screenshots back to the user** (so they can see the comparison): save the input-side images already exist in `.claude/scratchpad/<section>/`; for the rendered side, use `read_page` to view, then if you want to surface to chat, `mcp__cowork__present_files` on the scratchpad inputs alongside an `mcp__cowork__create_artifact` HTML page showing both side-by-side.
+
+**Fallback (no Claude in Chrome):** `mcp__workspace__web_fetch` for HTML only — confirms the section renders without Liquid errors but cannot do visual comparison. Surface this to the user and ask whether to ship without gate 1.
+
+## Procedure
+
+For **each** viewport (desktop 1440, mobile 375):
+
+1. **`resize_window`** to the target dimensions.
+2. **`navigate`** to the correct URL — see "Resolving the section URL" below.
+3. Wait for network idle. Use `read_console_messages` to confirm no JS errors blocking render.
+4. Scroll to the section. Use `javascript_tool`:
+   ```js
+   document.querySelector('#section-<section_id>').scrollIntoView({block:'start'});
+   document.querySelector('#section-<section_id>').getBoundingClientRect();
+   ```
+   The section's wrapper has `id="section-{{ section.id }}"` — find it in the page DOM. If the section's wrapper has a recognizable class instead, use that.
+5. **`read_page`** to get the rendered visual — this is the "screenshot" for comparison. The bounding rect from step 4 tells you which portion of the page corresponds to the section.
+6. **Side-by-side compare** with the input artefact:
+
+### Resolving the section URL
+
+The dev server routes by page slug. Find the page that hosts the section:
+
+| Section family | Page route |
+|---|---|
+| Header / footer / global | any page — `/home` is fine |
+| Hero / banner / homepage CTA cards | `/home` |
+| Product collection grid | `/collections/<handle>` (use a known collection from mock data, or `/collections/all`) |
+| Product detail | `/products/<product_id>` (use any product slug from `?format=json` on the storefront) |
+| Cart | `/cart` |
+| Checkout | `/checkout` |
+| Search | `/search?q=<term>` |
+| Blog | `/blog` or `/blog/<post-slug>` |
+| Account | `/account/profile`, `/account/orders`, etc. |
+| 404 | `/this-route-does-not-exist` |
+
+If unsure, ask the user. If the section is in `pages/<page>.json`, that JSON file's name is the route (e.g. `pages/index.json` → `/home`, `pages/cart.json` → `/cart`).
+   - Figma input → `<scratchpad>/intake/<section>/figma-desktop.png` (or mobile)
+   - Screenshot input → `<scratchpad>/intake/<section>/screenshot-desktop.png`
+   - URL input → `<scratchpad>/intake/<section>/desktop.png`
+
+## What to compare
+
+Walk the Design Spec Table top-to-bottom. For each row, eyeball-verify the rendered section matches. Focus areas:
+
+- **Structural** — same number of elements? Same hierarchy? (Quick reject on missing elements.)
+- **Alignment** — text aligned same way, columns same width, elements vertically centered correctly.
+- **Spacing** — gaps between elements look the same. Counter-intuitive padding/margin mistakes are the most common visual bug.
+- **Typography** — heading vs body size ratio, font weight, line height.
+- **Colors** — primary/secondary/accent applied correctly. Watch for inverted color states (light text on light bg).
+- **Imagery** — aspect ratio, object-fit (cover vs contain), placement.
+- **States** — hover/focus states on interactive elements (use `javascript_tool` to apply `:hover` programmatically if needed).
+
+## Output format
+
+```
+GATE 1 — VISUAL DIFF
+DEVICE: desktop 1440
+SOURCE: figma-desktop.png
+RENDERED: localhost:3000/home → #section-12345
+
+  CRITICAL
+    [1] Hero h1 missing — Figma has two-line headline, rendered shows only one. Cause: schema field `heading_line_2` not added.
+  MINOR
+    [2] CTA button gap from heading: Figma=32, Rendered=24. Spec row 16.
+    [3] Hero image aspect ratio: Figma=4:3, Rendered=16:9. Spec row 17.
+  SUGGESTION
+    [4] Drop shadow on card is softer in Figma — try `shadow-md` instead of `shadow-lg`.
+
+DEVICE: mobile 375
+  PASS — no critical or minor mismatches.
+```
+
+## Categorization rules
+
+| Severity | Trigger |
+|---|---|
+| CRITICAL | Missing/extra element, wrong content, broken layout (overflow/clip), wrong major color (primary/background) |
+| MINOR | Numeric drift within tolerance band 1 (spacing 3–8px, font ±2px, color ΔE 1–3, radius 3–6px) |
+| SUGGESTION | Subjective polish — different shadow, slightly different easing, "could look nicer" |
+
+CRITICAL items must be fixed before passing the gate. MINOR items can pass if the user explicitly accepts the deviation. SUGGESTION items never block the gate.
+
+## Common false positives
+
+- **Font rendering differences** — Chrome/Safari/Firefox render type slightly differently. Don't flag 1px line-height drift.
+- **Antialiasing** — diagonal lines and small text look slightly different in rasterized output. Trust computed styles over screenshots when in doubt.
+- **Image placeholders** — the dev server may serve a placeholder image while real product data loads. Re-screenshot after refresh.
+- **Animations** — if the section animates in, screenshot the end state.
+
+## When the dev server can't render the section
+
+If the section file has Liquid errors, the rendered page won't include the section at all. Check:
+
+- Terminal output from `yarn run dev` — surface any Liquid stack traces.
+- Browser console — `read_console_messages`.
+- The page JSON — does it actually reference the new section type?
+
+Fix the rendering bug first, then re-run the gate.