@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-vibe-headless/references/portfolio/INSTRUCTIONS.md

@@ -33,11 +33,11 @@ so you don't need to open them:**
 | `components/CollectionCard.jsx`, `CollectionGrid.jsx` | collections listing UI (grid + card, with empty state) |
 | `components/ProjectCard.jsx`, `ProjectGrid.jsx` | projects listing UI (grid + card, with empty state) |
 | `components/ProjectMedia.jsx` | one gallery item — branches on `item.type` (IMAGE / VIDEO) |
-| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
 | `pages/Portfolio.jsx` | collections gallery route (`/portfolio`) |
 | `pages/CollectionPage.jsx` | collection page route (`/collection/:slug`) |
 | `pages/ProjectDetail.jsx` | project detail route (`/project/:slug`) |
-| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-config.js` | the two ids, written by the install step |
 | `rest/wix-client.js` + `rest/wix-portfolio.js` | REST transport + portfolio read helpers |
 
 They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
@@ -47,11 +47,8 @@ a real fallback — a runtime error, or a field the snippets don't cover (see "F
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/portfolio/app/` → `src/`.)
 
-## STEP 2 — Credentials
-Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
-one place both ids live.
 
-## STEP 3 — Theme (nothing to style on the shipped components)
+## STEP 2 — Theme (nothing to style on the shipped components)
 The shipped components carry **no palette of their own** — they render from base44's design tokens in
 `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`, `--muted`,
 `--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`, `text-foreground`,
@@ -59,10 +56,10 @@ The shipped components carry **no palette of their own** — they render from ba
 are **already set to the brand by the design phase**, so the shipped pages are themed with zero work
 here. To adjust the palette, edit `index.css` (`:root` **and** `.dark`) — the base44 way; **never add
 a parallel theme file (e.g. a `theme.css`) or restyle the shipped JSX.** Build the Home/Header you add
-(STEP 4) from the **same** base44 tokens/classes so it matches automatically. A dark brand is just
+(STEP 3) from the **same** base44 tokens/classes so it matches automatically. A dark brand is just
 base44's dark palette in `index.css` — no per-component work.
 
-## STEP 4 — Wire routes (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+## STEP 3 — Wire routes (surgical `find_replace` on `src/App.jsx`, never a rewrite)
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it. Portfolio is read-only with no cross-page state, so there's **no provider to wrap** (no
@@ -122,7 +119,7 @@ function Layout() {
 
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the `Layout`
-(STEP 4) so they wrap every route — plus the overall brand story, styled with the same base44
+(STEP 3) so they wrap every route — plus the overall brand story, styled with the same base44
 tokens/classes. **Compose the shipped pieces** — a featured strip is just `queryCollections` (or
 `queryProjects`) + the shipped `CollectionGrid` / `ProjectGrid`; the nav is a link to `/portfolio`:
 
@@ -204,9 +201,8 @@ links its own reference page inline; the whole area is here:
 - Portfolio (collections, projects, project items): https://dev.wix.com/docs/api-reference/business-solutions/portfolio.md
 
 ## Hard rules
-- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
 - Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
-- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped
   `Portfolio`/`CollectionPage`/`ProjectDetail` to add chrome.
 - The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your
   `Header` is plain in-flow markup (not `position:fixed`).

package/skills/wix-vibe-headless/references/portfolio/seed/SEED.md

@@ -16,7 +16,7 @@ first, then thread their real ids into each project.
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/pricing-plans/INSTRUCTIONS.md

@@ -36,11 +36,11 @@ map, so you don't need to open them:**
 | `components/PlanCard.jsx` | plan card — name, description, price, perks, Subscribe (when `buyable`) |
 | `components/PlanGrid.jsx` | responsive plans grid + empty state |
 | `components/OrderCard.jsx` | one member order row for the "my plans" list |
-| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
 | `pages/Plans.jsx` | the plans-table route (`/plans`) — grid + paging + checkout |
 | `pages/PlanDetail.jsx` | the plan-detail route (`/plans/:slug`) — perks, terms, checkout |
 | `pages/MyPlans.jsx` | the member's memberships + post-checkout confirmation (`/my-plans`) |
-| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-config.js` | the two ids, written by the install step |
 | `rest/wix-client.js` + `rest/wix-pricing-plans.js` | REST transport + plans/orders/checkout helpers |
 
 They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
@@ -50,11 +50,8 @@ a real fallback — a runtime error, or a field the snippets don't cover (see "F
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/pricing-plans/app/` → `src/`.)
 
-## STEP 2 — Credentials
-Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
-one place both ids live.
 
-## STEP 3 — Theme (nothing to style on the shipped components)
+## STEP 2 — Theme (nothing to style on the shipped components)
 The shipped components carry **no palette of their own** — they render from base44's design tokens
 in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`,
 `--muted`, `--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`,
@@ -62,10 +59,10 @@ in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `
 `font-display`). Those tokens are **already set to the brand by the design phase**, so the shipped
 pages are themed with zero work here. To adjust the palette, edit `index.css` (`:root` **and**
 `.dark`) — the base44 way; **never add a parallel theme file (e.g. a `theme.css`) or restyle the
-shipped JSX.** Build the Home/Header you add (STEP 4) from the **same** base44 tokens/classes so it
+shipped JSX.** Build the Home/Header you add (STEP 3) from the **same** base44 tokens/classes so it
 matches automatically. A dark brand is just base44's dark palette in `index.css` — no per-component work.
 
-## STEP 4 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it. Pricing Plans needs **no** cross-page provider (checkout is a redirect, not client
@@ -125,7 +122,7 @@ function Layout() {
 
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the
-`Layout` (STEP 4) so they wrap every route — plus the overall brand story, styled with the same
+`Layout` (STEP 3) so they wrap every route — plus the overall brand story, styled with the same
 base44 tokens/classes. **Compose the shipped pieces** — a "featured plans" strip is just `queryPlans` +
 the shipped `PlanGrid`; the nav is links to `/plans` and `/my-plans`:
 
@@ -214,9 +211,8 @@ Fallback only — when you hit an error or need something not shown here: read t
 file under `src/`, or look it up via the **`wix-docs`** skill.
 
 ## Hard rules
-- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
 - Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
-- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped
   `Plans`/`PlanDetail`/`MyPlans` to add chrome.
 - The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your
   `Header` is plain in-flow markup (not `position:fixed`).

package/skills/wix-vibe-headless/references/pricing-plans/seed/SEED.md

@@ -9,7 +9,7 @@ plain data.
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md

@@ -35,9 +35,9 @@ so you don't need to open them:**
 | `components/ItemDialog.jsx` | dish detail modal — description, price/variants, modifier groups (display), quantity, add-to-order |
 | `components/OrderCartButton.jsx` | header order **icon** button with a live-count badge |
 | `components/OrderCartDrawer.jsx` | slide-over order cart (mount once; opens from `useOrderCart`) |
-| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
 | `pages/Menu.jsx`, `pages/Reservations.jsx` | the two shipped routes (`/menu`, `/reservations`) |
-| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-config.js` | the two ids, written by the install step |
 | `rest/wix-client.js` | REST transport + visitor-token mint/refresh (the refresh token IS the cart identity) |
 | `rest/wix-restaurants-menu.js` | menu read helpers — `getFullMenu` (the assembled tree; start here) + raw `list*` |
 | `rest/wix-restaurants-ordering.js` | ordering — operations, add/update/remove, `checkout` |
@@ -50,11 +50,8 @@ real fallback — a runtime error, or a field the snippets don't cover (see "Fal
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/restaurants/app/` → `src/`.)
 
-## STEP 2 — Credentials
-Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
-one place both ids live.
 
-## STEP 3 — Theme (nothing to style on the shipped components)
+## STEP 2 — Theme (nothing to style on the shipped components)
 The shipped components (menu, item dialog, order cart, reservations) carry **no palette of their
 own** — they render from base44's design tokens in `src/index.css` (`:root`/`.dark`: `--background`,
 `--foreground`, `--card`, `--primary`, `--muted`, `--border`, `--radius`, `--font-*`) via shadcn
@@ -62,11 +59,11 @@ Tailwind classes (`bg-card`, `text-foreground`, `bg-primary`, `text-muted-foregr
 `border-border`, `rounded-lg`, `font-display`). Those tokens are **already set to the brand by the
 design phase**, so the shipped pages are themed with zero work here. To adjust the palette, edit
 `index.css` (`:root` **and** `.dark`) — the base44 way; **never add a parallel theme file (e.g. a
-`theme.css`) or restyle the shipped JSX.** Build the Home/Header you add (STEP 4) from the **same**
+`theme.css`) or restyle the shipped JSX.** Build the Home/Header you add (STEP 3) from the **same**
 base44 tokens/classes so it matches automatically. A dark brand is just base44's dark palette in
 `index.css` — no per-component work.
 
-## STEP 4 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it.
@@ -129,7 +126,7 @@ function Layout() {
 
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** (mount `<OrderCartButton/>` in it) and a **`Footer`** —
-the two you drop into the `Layout` (STEP 4) so they wrap every route — plus the overall brand story,
+the two you drop into the `Layout` (STEP 3) so they wrap every route — plus the overall brand story,
 styled with the same base44 tokens/classes. The nav is an `<OrderCartButton/>` (a clean order-**icon**
 button with a live-count badge — render it as-is, don't wrap it in your own text button) + links to
 `/menu` and `/reservations`:
@@ -229,9 +226,8 @@ Fallback only — when you hit an error or need something not shown here: read t
 file under `src/`, or look it up via the **`wix-docs`** skill.
 
 ## Hard rules
-- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
 - Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
-- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped `Menu`/`Reservations` to add chrome.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped `Menu`/`Reservations` to add chrome.
 - The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your `Header` is plain in-flow markup (not `position:fixed`).
 - Order through the shipped cart: `addItem()` → `checkout()` (redirect-session) — never a hand-built `/checkout`, ordering, or reservation URL.
 - Reservations: offer only `AVAILABLE` slots; pass the hold's `revision` into reserve; `firstName` + `phone` (E.164) are mandatory.

package/skills/wix-vibe-headless/references/restaurants/seed/SEED.md

@@ -17,7 +17,7 @@ across exec calls. Online ordering and table reservations run only when the plan
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/shared/app/components/WixManageBanner.jsx

@@ -1,7 +1,7 @@
 // Preview-only banner linking the running app to its Wix Business Manager (the back office).
 // Renders while the app is previewed or run locally, never on the published site, and is
 // dismissible (persisted per site).
-// Mount it at the top of your Layout's fixed region, ABOVE <Header/> (see INSTRUCTIONS STEP 4) —
+// Mount it at the top of your Layout's fixed region, ABOVE <Header/> (see INSTRUCTIONS STEP 3) —
 // banner + header ride together as one fixed block, so nothing drifts or gaps on scroll.
 import { useState } from "react";
 import { WIX_METASITE_ID } from "@/rest/wix-config";

package/skills/wix-vibe-headless/references/shared/app/rest/wix-config.js

@@ -1,6 +1,8 @@
-// Wix credentials — the ONLY file you set these in. Paste both values from your prompt,
-// replacing the placeholders. Safe to commit: WIX_CLIENT_ID is a public, buyer-facing id
-// (it only mints anonymous visitor tokens); WIX_METASITE_ID just identifies the site.
+// Wix credentials. The install step writes this file: deploy.cjs --client-id … --metasite-id …
+// If you're seeing the placeholders below, re-run that command with the ids from the prompt rather
+// than typing them in here.
+// Safe to commit: WIX_CLIENT_ID is a public, buyer-facing id (it only mints anonymous visitor
+// tokens); WIX_METASITE_ID just identifies the site.
 // wix-client.js and wix-manage-banner.js read their ids from here.
 export const WIX_CLIENT_ID = "<YOUR-CLIENT-ID>";
 export const WIX_METASITE_ID = "<YOUR-METASITE-ID>";

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -24,15 +24,18 @@ so you don't need to open them:**
 | `context/CartContext.jsx` | `useCart()` provider: server cart, add/update/remove, checkout |
 | `hooks/useProductDetail.js` | PDP data — product + variant resolution for a slug, plus load/add state |
 | `hooks/useShop.js` | catalog listing — category menu, cursor paging, sort, failure state |
-| `components/ProductCard.jsx`, `ProductGrid.jsx` | product listing UI (grid + card, skeletons, empty state). The tile carries quick add for single-variant products, colour dots + an option summary, and pre-order / sold-out / limited-stock / percent-off / merchant-ribbon badges — all from the list query, no extra request |
+| `hooks/useProductCard.js` | headless data layer for a grid tile — returns `leftBadges`, `promoBadge`, `priceDisplay`, `compareAtDisplay`, `colors`, `optionLabel`, `isQuickAddable`, `image`, `hoverImage`; **always use this to build your own product card UI on the grid** |
+| `components/ProductCard.jsx` | reference implementation of a grid tile built on `useProductCard` — read it for inspiration, build your own component rather than using it directly |
+| `components/ProductGrid.jsx` | reference grid layout (2-col mobile → auto-fill desktop) with skeleton + empty state — read it for the skeleton/empty-state patterns, build your own layout rather than using it directly |
 | `components/ProductGallery.jsx` | PDP main image + thumbnails |
 | `lib/storeImage.js` | `productImage()` / `productGallery()` / `storeImage()` — normalise Wix image urls |
 | `components/CartButton.jsx` | header cart **icon** button with a live-count badge |
 | `components/CartDrawer.jsx` | slide-over cart (mount once; opens from `useCart`) |
-| `components/VariantPicker.jsx` | option/variant selector used on the PDP — colour options render as real swatches, and picking one moves the gallery to that colour's photo |
-| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `hooks/useVariantOptions.js` | headless data layer for options/modifiers — returns `optionGroups` + `modifierGroups` (normalised, render-agnostic); **always use this to build your own variant UI on the PDP** |
+| `components/VariantPicker.jsx` | reference implementation of a variant selector built on `useVariantOptions` (pills + colour swatches) — read it for inspiration, but build your own component rather than using it directly |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
 | `pages/Shop.jsx`, `pages/ProductDetail.jsx` | the two shipped routes (`/shop`, `/product/:slug`) |
-| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-config.js` | the two ids, written by the install step |
 | `rest/wix-client.js` + `rest/wix-store-*.js` | REST transport + catalog/cart helpers |
 
 They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
@@ -42,11 +45,8 @@ real fallback — a runtime error, or a field the snippets don't cover (see "Fal
 end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
 `references/storefront/app/` → `src/`.)
 
-## STEP 2 — Credentials
-Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
-one place both ids live.
 
-## STEP 3 — Theme (nothing to style on the shipped components)
+## STEP 2 — Theme (nothing to style on the shipped components)
 The shipped components carry **no palette of their own** — they render from base44's design tokens
 in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`,
 `--muted`, `--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`,
@@ -54,10 +54,10 @@ in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `
 `font-display`). Those tokens are **already set to the brand by the design phase**, so the shipped
 pages are themed with zero work here. To adjust the palette, edit `index.css` (`:root` **and**
 `.dark`) — the base44 way; **never add a parallel theme file (e.g. a `theme.css`) or restyle the
-shipped JSX.** Build the Home/Header you add (STEP 4) from the **same** base44 tokens/classes so it
+shipped JSX.** Build the Home/Header you add (STEP 3) from the **same** base44 tokens/classes so it
 matches automatically. A dark brand is just base44's dark palette in `index.css` — no per-component work.
 
-## STEP 4 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+## STEP 3 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
 **No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
 `App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
 replace it.
@@ -73,6 +73,69 @@ replace it.
   banner is dismissed.
 - Routes under the Layout: `/shop` → `Shop`, `/product/:slug` → `ProductDetail` (both shipped, as-is).
   **You add `/` → your own Home** page.
+- **Build your own variant selector on the PDP — this is required, not optional, and it's your chance to be creative.** `ProductDetail.jsx` ships with a `VariantPicker` import — remove it and replace with your own component built on `useVariantOptions`. Design the controls to fit the brief: the business type, the tone, the audience. A fashion brand might want large colour swatches and a size chart link; a tech store might want a compact dropdown. `VariantPicker.jsx` is in `src/` for reference — read it, don't use it:
+- **Build your own product card for the grid — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships with a `ProductCard` import — replace it with your own component built on `useProductCard`. The hook hands you everything the tile needs (badges, price display, colour dots, quick-add flag, images) — you decide the layout, shape, hover behaviour, and CTA style. A lifestyle brand might want full-bleed images with an overlay gradient; a tech store might want a compact horizontal list item. `ProductCard.jsx` is in `src/` for reference — read it, don't use it:
+- **Build your own grid layout — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships as a reference (2-col mobile → auto-fill desktop, 220px min) — replace it with an arrangement that fits the brief. A curated boutique might want a 3-col asymmetric editorial layout; a high-volume store might want a dense 4-col grid; a featured strip on the home page might want horizontal scroll. Keep the skeleton and empty-state patterns from `ProductGrid.jsx` (copy them into your own component) — the states themselves are correct, just the layout is yours to choose.
+
+```jsx
+import { Link } from "react-router-dom";
+import { useCart } from "@/context/CartContext";
+import { useProductCard } from "@/hooks/useProductCard";
+
+export default function MyProductCard({ product }) {
+  const { addToCart } = useCart();
+  const {
+    isSoldOut, isPreorder,
+    leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }] — render left side of image
+    promoBadge,       // { type: 'discount'|'ribbon', label } | null — render right side
+    priceDisplay,     // "€10" or "€10 – €20" (range when variants differ)
+    compareAtDisplay, // original price string | null
+    colors,           // hex strings → render as dots (slice to how many you want)
+    optionLabel,      // "3 sizes · 2 materials" or empty string
+    isQuickAddable,   // true for single-variant, in-stock products
+    image,            // primary image URL | null
+    hoverImage,       // second image URL | null
+  } = useProductCard(product);
+
+  // Then render however you want:
+  return (
+    <div>
+      {/* image, badges, price, colour dots, quick-add or "Choose options" CTA */}
+      {isQuickAddable && <button onClick={() => addToCart(product.id)}>Quick add</button>}
+      {!isQuickAddable && !isSoldOut && <Link to={`/product/${product.slug}`}>Choose options</Link>}
+      {isSoldOut && isPreorder && <Link to={`/product/${product.slug}`}>Pre-order</Link>}
+    </div>
+  );
+}
+```
+
+```jsx
+import { useVariantOptions } from "@/hooks/useVariantOptions";
+
+// options/modifiers/selectedOptions/modifierValues come from useProductDetail:
+const { optionGroups, modifierGroups } = useVariantOptions(options, modifiers, selectedOptions, modifierValues);
+
+// optionGroups: [{ id, name, isColor, choices: [{ choiceId, name, colorCode, isColorSwatch, inStock, selected }] }]
+// modifierGroups: [{ key, name, mandatory, type: 'choices'|'text', choices?: [{ key, name, selected }], value?: string }]
+
+// Then render however you want:
+optionGroups.map((group) =>
+  group.choices.map((c) =>
+    c.isColorSwatch
+      ? <MySwatch key={c.choiceId} color={c.colorCode} active={c.selected} disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)} />
+      : <MyPill  key={c.choiceId} active={c.selected} disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)}>{c.name}</MyPill>
+  )
+);
+modifierGroups.map((m) =>
+  m.type === "text"
+    ? <MyInput key={m.key} label={m.name} value={m.value} onChange={(v) => setModifier(m.key, v)} />
+    : m.choices.map((c) =>
+        <MyPill key={c.key} active={c.selected} onClick={() => setModifier(m.key, c.key)}>{c.name}</MyPill>
+      )
+);
+```
 
 ```jsx
 import { useRef, useState, useEffect } from "react";
@@ -120,7 +183,7 @@ function Layout() {
 
 ## What you build (not shipped)
 The **home / landing page**, the **`Header`** (mount `<CartButton/>` in it) and a **`Footer`** — the
-two you drop into the `Layout` (STEP 4) so they wrap every route — plus the overall brand story,
+two you drop into the `Layout` (STEP 3) so they wrap every route — plus the overall brand story,
 styled from the same base44 tokens/classes. **Compose the shipped pieces** — a
 featured strip is just `queryProducts` + the shipped `ProductGrid`; the nav is a `<CartButton/>`
 (a clean cart-**icon** button with a live-count badge — render it as-is, don't wrap it in your own
@@ -243,9 +306,8 @@ reference page inline; these are the areas they sit in:
 - Headless redirect session (hosted checkout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md
 
 ## Hard rules
-- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
 - Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
-- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped `Shop`/`ProductDetail` to add chrome.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped `Shop`/`ProductDetail` to add chrome.
 - The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your `Header` is plain in-flow markup (not `position:fixed`).
 - Checkout goes through the shipped cart (redirect-session) — never a hand-built `/checkout` URL.
 - Render live Wix data or the shipped empty state — never mock products.

package/skills/wix-vibe-headless/references/storefront/app/components/ProductCard.jsx

@@ -1,72 +1,29 @@
-// Grid tile. Styled with base44 design tokens (shadcn Tailwind classes: bg-card / text-foreground /
-// border-border) — re-skin via the app's design tokens (src/index.css :root/.dark), not this JSX.
-// The price / stock / ribbon field paths are load-bearing; image URLs go through lib/storeImage so the
-// grid, the PDP gallery and the cart all normalise them the same way.
-//
-// Everything here comes from the list query — the tile costs no extra request. What the list query
-// does NOT carry is a stock COUNT (inventory has availabilityStatus only), so "Limited stock" is as
-// precise as a tile can honestly get; "Only 2 left" would need per-variant inventory per product.
+// Reference implementation of a product grid tile built on useProductCard.
+// Styled with base44 design tokens (shadcn Tailwind classes: bg-card / text-foreground / border-border).
+// Build your own card on useProductCard instead — read this for inspiration, don't use it directly.
 import { useState } from "react";
 import { Link } from "react-router-dom";
-import { productGallery, productImage } from "@/lib/storeImage";
 import { useCart } from "@/context/CartContext";
+import { useProductCard } from "@/hooks/useProductCard";
 
-// Percent off, from the raw amounts — the formatted strings ("€129.00") can't be subtracted.
-function discountPercent(product) {
-  const now = Number(product?.actualPriceRange?.minValue?.amount);
-  const was = Number(product?.compareAtPriceRange?.minValue?.amount);
-  if (!now || !was || was <= now) return null;
-  return Math.round(((was - now) / was) * 100);
-}
-
-// What the buyer gets to choose, previewed on the tile: colour options become real dots (the colours
-// say more than "3 colors" could), everything else becomes "4 sizes". Pluralised from the option's own
-// name, so the wording follows the merchant's catalogue rather than a hardcoded English word.
-function optionsPreview(product) {
-  const labels = [], colors = [];
-  for (const o of product?.options || []) {
-    const choices = (o.choicesSettings?.choices || []).filter((c) => c.visible !== false);
-    if (!choices.length) continue;
-    const swatches = choices.map((c) => c.colorCode).filter(Boolean);
-    if (swatches.length) { colors.push(...swatches); continue; }
-    const n = o.name.toLowerCase();
-    labels.push(`${choices.length} ${choices.length === 1 || n.endsWith("s") ? n : `${n}s`}`);
-  }
-  return { label: labels.join(" · "), colors };
-}
-
-// One rule for every chip on the tile, so a new badge has an obvious home instead of a fresh colour:
-// promotional shouts in the brand colour, informational sits quietly on a card surface, and only a
-// blocking state is destructive. Each background travels with its own foreground token.
 const badge = "px-2 py-0.5 text-[11px] font-semibold uppercase tracking-wide rounded-full";
-const badgePromo = `${badge} bg-primary text-primary-foreground`;
-const badgeInfo = `${badge} bg-card text-foreground border border-border`;
-const badgeBlocked = `${badge} bg-destructive text-destructive-foreground`;
+const badgePromo    = `${badge} bg-primary text-primary-foreground`;
+const badgeInfo     = `${badge} bg-card text-foreground border border-border`;
+const badgeBlocked  = `${badge} bg-destructive text-destructive-foreground`;
+
+const badgeClass = { "pre-order": badgeInfo, "sold-out": badgeBlocked, "limited-stock": badgeInfo };
 
 export default function ProductCard({ product }) {
   const { addToCart } = useCart();
   const [adding, setAdding] = useState(false);
 
-  const image = productImage(product);
-  const hoverImage = productGallery(product)[1]?.url;
-  const price = product?.actualPriceRange?.minValue?.formattedAmount;
-  const priceMax = product?.actualPriceRange?.maxValue?.formattedAmount;
-  const compareAt = product?.compareAtPriceRange?.minValue?.formattedAmount;
-
-  const status = product?.inventory?.availabilityStatus;
-  const soldOut = status === "OUT_OF_STOCK";
-  const preorder = product?.inventory?.preorderStatus === "ENABLED";
-  const discount = discountPercent(product);
-  // A merchant-set ribbon ("New", "Best Seller") is the catalogue's own badge, so it beats anything
-  // derived here — a "new" label computed from createdDate would flag the whole catalogue at once
-  // right after seeding. Suppressed when a discount badge is showing, since that ribbon is "Sale".
-  const ribbon = product?.ribbon?.name;
-  const { label: optionLabel, colors } = optionsPreview(product);
-  const hasOptions = (product?.options?.length || 0) > 0;
+  const {
+    isSoldOut, isPreorder, leftBadges, promoBadge,
+    priceDisplay, compareAtDisplay,
+    colors, optionLabel,
+    isQuickAddable, image, hoverImage,
+  } = useProductCard(product);
 
-  // No options means a single variant, which the cart resolves from the product id alone — so the
-  // tile can add straight to the cart with no extra request. The drawer opening is the confirmation
-  // (and carries the reason when it fails), which is why there's no "Added ✓" state to fake here.
   const quickAdd = async () => {
     setAdding(true);
     await addToCart(product.id);
@@ -79,11 +36,8 @@ export default function ProductCard({ product }) {
         <Link to={`/product/${product.slug}`} aria-label={product.name} className="block w-full h-full">
           {image ? (
             <>
-              {/* Fade out only when there IS a second shot behind it — a one-photo product would
-                  otherwise hover to an empty frame. */}
               <img src={image} alt={product.name} loading="lazy"
                 className={`w-full h-full object-cover ${hoverImage ? "transition-opacity duration-300 md:group-hover:opacity-0" : ""}`} />
-              {/* Second catalogue shot on hover. `hidden` below md so phones never fetch it. */}
               {hoverImage && (
                 <img src={hoverImage} alt="" aria-hidden="true" loading="lazy"
                   className="hidden md:block absolute inset-0 w-full h-full object-cover opacity-0 transition-opacity duration-300 group-hover:opacity-100" />
@@ -99,51 +53,40 @@ export default function ProductCard({ product }) {
         </Link>
 
         <div className="absolute top-2 left-2 flex flex-col items-start gap-1 pointer-events-none">
-          {soldOut && preorder && <span className={badgeInfo}>Pre-order</span>}
-          {soldOut && !preorder && <span className={badgeBlocked}>Sold out</span>}
-          {status === "PARTIALLY_OUT_OF_STOCK" && <span className={badgeInfo}>Limited stock</span>}
+          {leftBadges.map((b) => (
+            <span key={b.type} className={badgeClass[b.type]}>{b.label}</span>
+          ))}
         </div>
-        {/* Discount and ribbon are mutually exclusive, so both can claim the promotional slot. */}
         <div className="absolute top-2 right-2 pointer-events-none">
-          {discount ? <span className={badgePromo}>−{discount}%</span>
-            : ribbon ? <span className={badgePromo}>{ribbon}</span> : null}
+          {promoBadge && <span className={badgePromo}>{promoBadge.label}</span>}
         </div>
 
-        {/* Sold out with no pre-order has nothing to offer, so no control appears at all. */}
-        {(!soldOut || preorder) && (
+        {(!isSoldOut || isPreorder) && (
           <div className="absolute inset-x-2 bottom-2 opacity-100 transition-opacity md:opacity-0 md:group-hover:opacity-100 md:group-focus-within:opacity-100">
-            {/* Same tokens as the PDP's Add-to-cart button: one action, one treatment, so the tile's
-                CTA is the brand colour rather than "whatever the text colour is". */}
-            {hasOptions || soldOut ? (
-              <Link to={`/product/${product.slug}`}
-                className="block w-full text-center py-2.5 px-4 rounded-full bg-primary text-primary-foreground no-underline text-sm font-semibold">
-                {soldOut ? "Pre-order" : "Choose options"}
-              </Link>
-            ) : (
+            {isQuickAddable ? (
               <button onClick={quickAdd} disabled={adding}
                 className="w-full py-2.5 px-4 rounded-full bg-primary text-primary-foreground border-none text-sm font-semibold cursor-pointer transition-opacity hover:opacity-90 disabled:opacity-60 disabled:cursor-wait">
                 {adding ? "Adding…" : "Quick add"}
               </button>
+            ) : (
+              <Link to={`/product/${product.slug}`}
+                className="block w-full text-center py-2.5 px-4 rounded-full bg-primary text-primary-foreground no-underline text-sm font-semibold">
+                {isSoldOut ? "Pre-order" : "Choose options"}
+              </Link>
             )}
           </div>
         )}
       </div>
 
       <div className="p-3 flex flex-col gap-1">
-        {/* Side by side once the tile is wide enough; stacked on a phone's two-up grid, where a long
-            name wrapping to three lines against a top-right price reads as broken. */}
         <div className="flex flex-col gap-1 md:flex-row md:items-baseline md:justify-between md:gap-3">
-          {/* Clamped to two lines: a 220px tile turns a long product name into three or four ragged
-              lines beside a top-right price. The full name is on the tile's link and the PDP. */}
           <h3 className="m-0 font-display text-[15px] font-semibold line-clamp-2">
             <Link to={`/product/${product.slug}`} className="no-underline text-foreground">{product.name}</Link>
           </h3>
           <div className="flex gap-2 items-baseline flex-wrap md:justify-end">
-            {/* A product whose variants differ in price spans a range — showing only minValue reads as
-                the price of everything, then the PDP appears to raise it once a variant is picked. */}
-            <span className="font-semibold whitespace-nowrap">{priceMax && priceMax !== price ? `${price} – ${priceMax}` : price}</span>
-            {compareAt && compareAt !== price && (
-              <span className="text-muted-foreground line-through text-[13px] whitespace-nowrap">{compareAt}</span>
+            <span className="font-semibold whitespace-nowrap">{priceDisplay}</span>
+            {compareAtDisplay && (
+              <span className="text-muted-foreground line-through text-[13px] whitespace-nowrap">{compareAtDisplay}</span>
             )}
           </div>
         </div>

package/skills/wix-vibe-headless/references/storefront/app/components/ProductGrid.jsx

@@ -1,11 +1,6 @@
-// Responsive product grid, with the two states a fresh store spends most of its life in: loading and
-// empty. Styled with base44 design tokens (shadcn Tailwind classes).
-//
-// Two columns on phones — a 220px minmax leaves room for only one, and a one-up catalog scrolls
-// forever — then auto-fill from md up.
-//
-// The empty state carries weight here — a catalog is seeded separately from the build, so it is
-// routinely empty when the merchant first opens the page. Say why, rather than showing a bare line.
+// Reference implementation of a product grid — 2-col mobile, auto-fill desktop, with a skeleton
+// loading state and a descriptive empty state. Build your own layout instead (see INSTRUCTIONS.md
+// STEP 3) — read this for the skeleton/empty-state patterns, don't use it directly.
 import ProductCard from "./ProductCard";
 
 // Skeleton tiles match ProductCard's aspect-square + two text lines, so nothing shifts when the real