INSTRUCTIONS

The file map (deployed into src/)

Don’t read the shipped files — this table and the contracts below are everything you need. Open a shipped file’s source only on a real fallback: a runtime error, or a field this playbook doesn’t cover. 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.
• 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.
• 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.
• 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 ships (isPreorder). Subscriptions, product groups, promotions, and notify-me 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

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.

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 — 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.

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. In the gallery that is 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.
• Theme via the @theme tokens; your markup uses Tailwind utilities on the same tokens. No parallel theme files, no hardcoded palette values in components.
• 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).
• Cart totals come from cart — never summed or hardcoded in the client; shipping and tax say “calculated at checkout” (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

Give the owner the dashboard, products, and categories links — the deploy step’s JSON output already printed them ready-made (dashboardUrl, productsUrl, categoriesUrl); copy, don’t re-derive. Real payments additionally need a premium plan + a connected payment method (dashboard) — mention it, don’t treat it as a code failure.

Seeding

Per seed/SEED.md — a plain-data plan.json into seed-store.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.

Verify (before declaring done)

• Not done: /shop renders live products SSR (view-source shows product names) through your grid/card; the FilterPanel shows the result count, and on desktop a sidebar beside the grid with the price slider and this catalog’s facets (a Color option → swatches); category links lead to /category/<slug>, which renders scoped and carries the SEO tags in view-source; an unknown slug is a 404; empty catalog shows your honest empty state.
• Not done: Shop first screen: at 1280×720 and at 390px wide, at least one full tile — image, name, price — is visible without scrolling; the tile with the longest product name and a price range shows the whole price at 390px, nothing clipped.
• Not done: Tiles: the buy control sits under name and price (not over the image) and OUTSIDE the tile’s link — clicking “Add to cart” stays on the shop page and opens the drawer, it does not navigate to the product; full product names are readable (no truncation); in a row that mixes an optioned product (swatches) with plain ones, the buy buttons share one baseline; a product with no options adds to the cart in one click; a product with options opens the picker across the full tile width (a bottom sheet at 390px wide) and adds the chosen variant; the drawer opens after either.
• Not done: Your PDP at 390px wide: image, name, price, the first option, and the buy button are all visible before scrolling. Color options render as swatches, the button shows blockedReason (“Choose Size”) until every option is picked, the price is the range until then and the variant’s price after, a sale shows the labelled “was”, a sold-out combination reads “Out of stock”, a pre-orderable one reads “Pre-order”.
• Not done: Cards: every product image renders (not its alt text) on the shop, the category page, and the home page; every ribbon renders; a multi-price product shows a range with no struck price; a product with a color option shows its swatches.
• Not done: PDP gallery: one thumbnail per distinct photo — never two selectors leading to the same image.
• Not done: Cart: a subscription line shows its plan terms under the product name.
• Not done: Cart: add / quantity ± / remove work; badge count is live; subtotal shows; cart survives a reload (same visitor token).
• Not done: Checkout button redirects to Wix-hosted checkout.
• Not done: PDP view-source carries the SEO tags (Astro).
• Not done: Shop/PDP/home are YOUR designs on the tokens; the data-layer/hook/cart files are unedited.
• Not done: Dashboard links handed to the owner.