INSTRUCTIONS

The file map (deployed into src/)

On Astro and React the shipped files are tested and work as they are — this table and the contracts below are everything you need to use them, so don’t spend the run reading their source; wire them and build your surfaces. Reading them is the right move when something is off (a runtime error, a field this playbook doesn’t cover) or when the brief wants a behaviour they don’t offer — then read the file that owns it and change or extend it. On lib, static, and a port the components don’t deploy at all, and each wiring section below opens with the files to read before writing their equivalents. Files you edit: SiteLayout.astro and styles/global.css. Files you create (skeletons below): the shop, category, and PDP pages with their island components, plus your home page.

Astro stack additionally gets:

What you build — this is the design job, not optional polish

You implement three surfaces yourself — each an SSR page plus its island, per the skeletons below — styled with Tailwind utilities on the @theme tokens, designed to fit the brief (the business, the tone, the audience — a toy brand and a jewelry house should not get the same store):

1. The shop page + ShopView (skeletons below) — category links, the shipped FilterPanel, and your grid of your tiles: image treatment, badges, price/sale presentation, hover behavior, grid rhythm (columns, density, maybe an editorial featured tile), each tile carrying the shipped QuickAdd. products === null → skeleton tiles, [] → an honest empty state. Decompose into ProductCard/ProductGrid files if you like — your call, nothing prescribes it. The category page (/category/[slug]) mounts the same ShopView scoped to one category — one island, two pages.
2. The PDP page + ProductDetailView (skeletons below) — gallery, price/sale, description, your option-selection UI (color options = real swatches), quantity, add-to-cart — on useProductDetail, which owns ALL selection/variant logic; you own how it looks. This is the surface that most often looks generic — make the layout the brand’s: an editorial split, a sticky buy column, a full-bleed gallery.
3. The home page — hero, featured products (fetch in frontmatter → your grid), brand story.

Plus the theme (edit the @theme block in styles/global.css — one edit; a dark brand is flipped token values; add brand fonts as extra tokens) and the chrome (header/footer in SiteLayout.astro, one edit pass; mount the shipped CartButton in your header).

What a complete storefront shows (recommended defaults)

These are the recommended defaults for a store whose brief says nothing about them. They are not requirements: when the user’s prompt asks for something different — a cart page instead of a drawer, no shop page, a particular layout or look — the prompt wins, and the item here that conflicts with it is dropped without discussion. Look at the catalog before designing (categories, assortment size, media, options, sales, ribbons) and design for this store, not for a stereotype of its category. Then, by default:

• Home: what the store sells and one shopping action in the first screen; real products under truthful headings (“Best Sellers” needs data behind it); not a repeat of the shop page. A category tile or link on the home page goes to that category’s page (/category/<slug>) — never to an anchor on the shop page that every tile shares — and its image is a product from THAT category (fetched with the category filter) or the category’s own image, never a positional guess into the all-products list.
• Shop: a real product card — image, name, price, link — in the first screen; the shipped FilterPanel around the grid (toolbar, then a filter sidebar beside the results on desktop and a sheet on phones) — a store with any filterable catalog ships it, not “when it fits”; the shipped QuickAdd as the last row of every tile; each category reachable by a real link (/category/<slug>) — from the nav, the home page, or the shop’s category row; loading, empty, no-results, and error states that look different.
• Product page: image, name, price, the first choice, and the buy button with blockedReason in the first screen at 390px wide too — on a phone the image is a bounded band (max-h-[45vh]), not a full-screen hero that pushes the price below the fold; every ribbon; every image reachable in the gallery; the main image follows the selection (imageUrl from the store when set, else the gallery’s first); breadcrumbs (Home › the category path › the product) when the product has a main category.
• Cart: the shipped drawer — it opens after every add, and checkout is a button in it.
• Overlays you build (quick-add, mobile nav, filters): mount at the document root (a fixed panel inside the backdrop-blur header gets clipped), lock background scroll, close on Escape, return focus on close — as the shipped CartDrawer does. An anchored picker is positioned inside its tile, not fixed with computed offsets. If you add dismiss-on-outside-click, decide inside/outside before anything re-renders (a capture-phase listener), or a click on a swatch that re-renders the panel reads as “outside” and closes it.
• A page whose slug resolves to nothing (category, product) shows only the not-found state — no heading, toolbar, or empty grid rendered around it.
• Copy: nothing the merchant didn’t supply — no invented reviews, scarcity, or delivery promises; no Wix IDs or technical words in visible text.

Pre-order (isPreorder, the merchant’s note), subscription plans (the picker), stock left, and notify-me ship in the components and show only when the catalog has them. Product groups and promotions are built only when the catalog has them — never fabricated; wix-docs has their contracts.

The contracts your components consume (everything you need — don’t read the source)

The pages and islands you create — skeletons

The class names in these skeletons are the Astro/React spelling of layout rules that hold on every stack, and each rule is also named in words beside its classes. On a stack where the shipped components don’t deploy (lib, static, a port), keep the rule and write it in your own CSS.

Nothing renders until you write these — the store IS your work. Each page is a thin SSR shell (fetch → DTO props → island); each island is a thin view over a hook. The pages’ frontmatter is machinery, not design — reproduce it as the skeletons show, exactly. Hooks first, branches after (an early return above a hook changes hook order between renders and React throws). The islands render on the server too (client:load SSRs), and by then the 200 and headers are already sent — a render throw truncates the body mid-stream and surfaces to the visitor as ERR_HTTP2_PROTOCOL_ERROR, not an error page. Render every state totally; nothing in a render path may throw.

The reference files for stacks where the components don’t deploy

On lib, static, and a port, nothing under components/ or hooks/ arrives (on static, read static.md in this folder). The state machines behind the hooks do arrive — wix/storefront/shop-store.ts, product-detail-store.ts, cart-store.ts — so you never rewrite them: create a store per surface, subscribe, render from getState(), call its actions. Their *State interfaces are the render contract; read those. What you write is the rendering — grid, product page, picker, filter panel, drawer — and for that read these first; they are tested code for exactly that behaviour, and rewriting them from the prose above is where the bugs come from:

1. components/storefront/QuickAdd.tsx — the three purchase paths decided from the summary DTO; the panel is positioned inside the tile (the tile is relative), a bottom sheet on small screens, never fixed with computed offsets; it closes on Escape, the close button, a successful add, or the scrim — there is NO outside-click handler (one that runs after a re-render sees the clicked swatch detached and closes on every pick).
2. components/storefront/OptionPicker.tsx — the purchase controls as working code: swatches vs pills, choices unavailable with the current picks disabled, text modifiers with their limit, the plan picker, quantity capped at the stock left, the gated button with its reason, the “Pre-order” label and note, the notify-me form; the PDP and the tile picker share it.
3. components/storefront/CartDrawer.tsx — the overlay contract as working code: root-level, scrim, scroll lock, Escape, focus in and back — plus the cart’s contents: struck discounted lines, per-status copy, the stock cap on “+”, promo code, note to seller (saved on blur), the totals breakdown (subtotal, discounts, fees, taxes unless prices include them, total).
4. components/storefront/FilterPanel.tsx — inline commits at once, the sheet stages until Apply; the price pair commits only when valid.

All under templates/storefront/app/.

Wiring — Astro (default)

1. Set the @theme tokens (one edit); brand SiteLayout.astro (one pass).
2. Create the shop, category, and PDP pages and their islands per the skeletons above — frontmatter machinery exact, presentation yours. Primary-content islands mount client:load with the SSR props; browser-state widgets (cart) are client:only="react".
3. Write pages/index.astro (home) on SiteLayout.

Wiring — another JS framework (--stack lib: Vue, Svelte, Solid, plain Vite)

Read the reference files listed above before writing any surface.

deploy.mjs storefront --stack lib put the data layer in src/wix/ and nothing else: sdk.ts (the visitor client, configured with the public client id), media.ts, money.ts, and wix/storefront/ — catalog.ts, cart.ts, types.ts, the *-core.ts rules, and the three stores shop-store.ts, product-detail-store.ts, cart-store.ts. None of it is React. The hooks and components don’t ship on this stack; the stores replace the hooks, and you write the components in your framework to the contracts on this page:

• bind the stores with your framework’s external-store primitive (Vue: shallowRef updated in subscribe; Svelte: readable(store.getState(), (set) => store.subscribe(() => set(store.getState()))); Solid: a signal set in subscribe). createShopStore(options) per listing (start() when mounted, stop() when unmounted), createProductDetailStore({ initial | slug }) per product surface, the cart store as-is (module-level). State in, actions out — exactly the hooks’ contracts above;
• your filter panel, quick add, and cart drawer to the contracts in “What a complete storefront shows” — the shipped FilterPanel.tsx, QuickAdd.tsx, CartDrawer.tsx are readable as behaviour specs (the overlay contract, the three purchase paths, the sidebar/sheet split).

Routes /shop, /category/:slug (via fetchCategoryBySlug, null → your 404), /products/:slug; dev server on 4321; a static build goes through npx @wix/cli@latest release with site.outputDirectory pointing at the build folder, an SSR build is hosted by you. Item-page tags from the entity’s seoData.

Wiring — static site (--stack static, no bundler)

Read static.md in this folder: it is the whole playbook for this stack, in one file. The pages import the modules from the site’s js/wix/ folder and write the purchase controls on the stores; static.md gives each control as tested code, with the listing, the product page, the routes, the rules and the seed.

Wiring — server-rendered, another language (Flask, Laravel, Rails, …)

Read the reference files listed above before writing any surface.

Run deploy.mjs storefront --stack static in the project folder anyway: js/wix/ is both the browser-side code and the readable spec. Then split by where the call runs. Reads on the server: port js/wix/catalog.ts and catalog-core.ts to your language — the same six functions returning the same DTO shapes as dicts, one anonymous visitor token per process for these public reads (mint and refresh per client.ts) — and render shop, category, and PDP in your templates to the contracts above, so product names and prices are in the HTML; item-page tags from the entity’s seoData. Buying in the browser: the cart drawer on ./js/wix/cart-store.js, the PDP’s option picker and the tile’s quick add on ./js/wix/product-detail-store.js (pass the product’s slug, or the rendered ProductDetail as initial in a JSON script tag), exactly as the static wiring above — the browser owns the shopper’s visitor token, so the server never handles per-shopper tokens. Routes stay /shop, /category/<slug>, /products/<slug>. Add your public https origin to the OAuth app’s allowed domains before checkout can return.

Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted. Same port for the reads, run at build time with one anonymous token; the generator must emit every product and category page (a URL generator over fetchCategories() plus a full searchCatalog walk by cursor — never only the first page). Run deploy.mjs storefront --stack static --out <build dir> so js/wix/ is inside the output the pages import from, point site.outputDirectory at that folder, wix release. Pages sit at different depths (/, /category/…, /products/…): give the templates one base path to js/wix/ (a template variable, or root-relative /js/wix/…), never a relative ./js/wix/ — it breaks one level down. The frozen grid is the first paint; the shop’s sort, filters, facets, search, and load-more still run client-side on it through createShopStore() from ./js/wix/shop-store.js, exactly as on a static site, so the gallery contract above applies. Close with the live URL, the rebuild + release command, and one line for the owner: dashboard edits to the catalog reach the site when that command runs; cart and checkout are live regardless.

Wiring — React SPA (Vite etc.)

Import ./styles/global.css once at the app entry (needs @tailwindcss/vite in the vite config plugins — deploy already added the dep). Write route wrappers in the project’s router: /shop → your shop component; /category/:slug → the same shop component with initialCategoryId resolved from fetchCategoryBySlug(slug) (null → your 404 view); /products/:slug → your detail component (useProductDetail({ slug }) — components fetch client-side when no initial is passed). Mount the shipped CartButton in the header and CartDrawer once. Deploy wrote the public client id into wix/config.ts; nothing else to configure.

Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly — hash routes, or one HTML file per route, decided before the first route is written; any URL handed to Wix as a return target must be one the host serves (SKILL.md step 1).

Hard rules

• Data and commerce logic only through the shipped exports — never rewrite their internals or re-derive a request shape. Extend by calling the exports or adding a new function in wix/storefront/ for what they don’t cover (API contracts: the wix-docs skill).
• Selection→cart goes through useProductDetail — never add a product with options by picking variants[0], and never gate canAdd yourself. On the PDP that is the shipped OptionPicker; in the gallery the shipped QuickAdd — a tile never adds a product with options itself, and never hides the buy path behind “go to the product page” for a product that has no options.
• Filters are the shipped FilterPanel — mounted in the gallery whenever the store has a catalog to filter; not rebuilt with fewer controls, not dropped because the brief didn’t ask.
• Categories are pages — /category/[slug] with its SEO block, linked from the chrome; a category that exists only as a state toggle on /shop has no URL to share or index.
• Don’t wrap shipped calls in your own API routes — they run client-side by design.
• Where the shipped components deploy (Astro, React): theme via the @theme tokens, and your markup uses Tailwind utilities on the same tokens — one design system across shipped and written code. No parallel theme files, no hardcoded palette values in components. Where they don’t (lib, static, a port): style with whatever your stack does well, on one token set of your own; the rule that survives is the token set, not Tailwind.
• Checkout only through the shipped cart (checkout()) — never a hand-built checkout URL.
• Live data or an honest empty state — never mock products, prices, reviews, or counts.
• Prices and ribbons come from the DTOs as-is — no computed percent-off, no “Sale” badge inferred from compareAtPrice, no struck price beside a range (the DTO already withholds it); a fromPrice summary reads “From {price}”, never a made-up top of the range.
• Cart totals come from cart (subtotal, discounts, fees, taxes, total — the estimate’s) — never summed or hardcoded in the client; shipping says “calculated at checkout”, tax too unless cart.taxes has rows or cart.pricesIncludeTax (the drawer already does).
• Your PDP page carries the SEO pieces (wixMetadata + loadSEOTagsServiceConfig + <SEO.Tags>) exactly as the skeleton shows — owners edit those tags in their dashboard.
• Browsing, cart and checkout need no login. They run on the Wix visitor session the shipped SDK client already holds. Don’t gate the shop, the PDP or the cart behind sign-in, and don’t add a members/auth flow unless the brief actually asks for accounts.
• Call every hook before any conditional return. A PDP that returns early for notFound/loading above its useState/useEffect changes hook order between renders and React throws. Hooks first, branches after.
• Sort and filter at the source, not on a loaded page. useShop‘s sort/filters/search and searchCatalog run on Wix across the whole catalog before cursor paging; re-ordering the array a hook already returned only sorts the slice you happen to have. Never sort/filter client-side, and never raise the page limit instead of paging (hasMore/loadMore).

Point the user to their dashboard

Hand the owner these links — {siteId} is siteId in wix.config.json (the deploy JSON also prints dashboardUrl, productsUrl, categoriesUrl); an entity id fills the placeholder from the seed result.

Real payments need a connected payment method and a premium plan. Until both are done, a visitor who reaches hosted checkout sees “We can’t accept online payments. Contact us for help with your order.” Hand both links above in the close; don’t treat it as a code failure.

Seeding

Per seed/SEED.md — a plain-data plan.json into seed-storefront.mjs, run from the project root. Independent of the frontend work; seed a catalog that exercises the UI (≥1 product with a color option, ≥1 on sale, an image per product) unless the brief says otherwise — and, when the brief wants them, a ribbon, a modifier (choices or free text), an info section, a pre-order item, per-variant prices, a category description/image: all plain plan fields (see seed/SEED.md).

A fresh Stores install carries Wix’s sample catalog (a dozen products such as “Baseball Cap” and “Ceramic Flower Vase”), and the shop lists them next to the seeded ones. Never delete them, or anything else on the site: the result’s preexisting[] names what the shop lists, and the closing message says so with the Manage products link so the owner removes them there — never release a store that sells “Baseball Cap” without telling the owner.