@wix/agent-skills 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-headless/references/DESIGN_SYSTEM.md

@@ -1,6 +1,6 @@
 ---
 name: design-system-designer
-description: "The Designer role of the wix-headless design-system phase. Picks the brand's visual identity and authors it as DESIGN.md — the single, portable design-token format (palette, type, spacing, rounded, content widths) plus a small block of brand-voice strings. Writes DESIGN.md directly (its only file, at the dispatch's designMdPath) and returns just data.shell + the designMdPath, so the orchestrator never re-emits the tokens. emit-design-tokens.mjs reads DESIGN.md's frontmatter and projects .wix/design-tokens.css + .wix/site.d.ts; compose.mjs (astro) reads DESIGN.md to write the design-system files. Makes no rendering decision (no CSS, no Tailwind, no Astro)."
+description: "The Designer role of the wix-headless design-system phase. Picks the brand's visual identity and authors it as DESIGN.md — the single, portable design-token format (palette, type, rounded, content widths) plus a small block of brand-voice strings. Writes DESIGN.md directly (its only file, at the dispatch's designMdPath) and returns just data.shell + the designMdPath, so the orchestrator never re-emits the tokens. emit-design-tokens.mjs reads DESIGN.md's frontmatter and projects .wix/design-tokens.css + .wix/site.d.ts; compose.mjs (astro) reads DESIGN.md to write the design-system files. Makes no rendering decision (no CSS, no Tailwind, no Astro)."
 ---
 
 # Designer — the design itself
@@ -11,7 +11,7 @@ You author **`DESIGN.md`** (its YAML frontmatter is the spec) — see "What you
 
 Your output is small and mostly thinking: a coherent, complete brand visual expressed as `DESIGN.md` frontmatter, plus a handful of brand-voice strings (returned as `data.shell`). Speed comes from staying in this lane — one small spec file + a small return, not site files.
 
-> **DESIGN.md is the single design artifact — there is no separate "design tokens" JSON contract.** What you author *is* the DESIGN.md frontmatter (DESIGN.md vocabulary: `colors` / `typography` / `spacing` / `rounded` / `containers` / `googleFontsHref`). **You write `DESIGN.md` directly**; `emit-design-tokens.mjs` then projects `.wix/design-tokens.css` + `.wix/site.d.ts` from its frontmatter; `compose.mjs` (astro) reads the same frontmatter to write the site files; non-astro frontends import the token CSS. Because the **frontmatter** is what every consumer reads, your completeness bar is the whole game — a thin spec yields a thin DESIGN.md.
+> **DESIGN.md is the single design artifact — there is no separate "design tokens" JSON contract.** What you author *is* the DESIGN.md frontmatter (DESIGN.md vocabulary: `colors` / `typography` / `rounded` / `containers` / `googleFontsHref`). **You write `DESIGN.md` directly**; `emit-design-tokens.mjs` then projects `.wix/design-tokens.css` + `.wix/site.d.ts` from its frontmatter; `compose.mjs` (astro) reads the same frontmatter to write the site files; non-astro frontends import the token CSS. Because the **frontmatter** is what every consumer reads, your completeness bar is the whole game — a thin spec yields a thin DESIGN.md.
 
 ## Self-Loading
 
@@ -38,7 +38,7 @@ You do **not** receive (and do not need) loaded packs, navigation links, disable
 - Open the file with `---` on its own line and close the frontmatter with `---`.
 - **QUOTE every string value with double quotes — especially hex colors** (`paper: "#FFFBF0"`). An unquoted `#hex` after `: ` is read as a YAML comment and the token vanishes.
 - **2-space indent** for nested groups. `typography` entries may use an indented `fontFamily:` line or flow style `{ fontFamily: "..." }`.
-- Groups: `colors`, `typography`, `spacing`, `rounded`, `containers`; plus the top-level `googleFontsHref`. Fill every color role (completeness is your bar — see below).
+- Groups: `colors`, `typography`, `rounded`, `containers`; plus the top-level `googleFontsHref`. Fill every color role (completeness is your bar — see below).
 
 **The `DESIGN.md` you write** (frontmatter is canonical; the body is documentation, never parsed):
 
@@ -59,16 +59,6 @@ colors:
 typography:
   display: { fontFamily: "..." }
   body: { fontFamily: "..." }
-spacing:
-  2xs: "..."
-  xs: "..."
-  sm: "..."
-  md: "..."
-  lg: "..."
-  xl: "..."
-  2xl: "..."
-  3xl: "..."
-  4xl: "..."
 rounded:
   sm: "..."
   md: "..."
@@ -111,7 +101,7 @@ Concrete values with **semantic roles**, in the DESIGN.md vocabulary (`DESIGN_MD
 - **`colors`** — a complete palette covering semantic roles, not just brand accents. **All six core roles are required** (emit every one): `paper` (primary background), `paper-warm` (secondary surface), `ink` (primary text / dark fills), `mute` (muted text), `rule` (borders / dividers), `accent` (brand emphasis). Also emit the recommended `ink-soft`, `cream`, `error`. Every value a concrete hex string. These wix-native role names are valid DESIGN.md color tokens — use them directly. **Map the approved palette to roles — do not re-pick hues.** The **accent** hex from the Color palette input → `accent`; the dominant **background** → `paper`; the primary **text** → `ink`. The remaining roles (`paper-warm`, `ink-soft`, `mute`, `rule`, `cream`, `error`) are **tonal derivatives of that approved palette** — lighten/darken/desaturate **within the same hue family**, never a new hue and never a generic editorial default set. **`compose.mjs` derives a missing role only as a last-resort fail-safe** (e.g. `ink-soft` ≈ `ink` lightened) — that yields a less intentional palette, so completeness is on you.
 - **`typography`** — a map of levels to type tokens. **Use the exact `display` and `body` font families from the Typography input, verbatim** — no substitution, no "better" pairing, no swapping the approved serif for a different serif. The families are **given to you, not chosen by you**; you decide only `fontSize`/`fontWeight`/`lineHeight`/`letterSpacing` (optional — the wix pipeline consumes only `fontFamily`). Each level is `{ "fontFamily": "<the given family>" }` (e.g. `"Fraunces"`, `"Inter"`). Add `mono` only if the brand needs it.
 - **`googleFontsHref`** (top-level key in `data.design`) — the **ready** Google Fonts stylesheet href for the **given** `display` + `body` families, with the weight/optical axes each family actually supports. Emit the finished URL for those exact families: e.g. `"https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,400;0,9..144,600&family=Inter:wght@400;500;600&display=swap"`. If **both** families are system fonts (`system-ui`, `sans-serif`, etc.), emit `""` (the `<link>` is dropped). (If you omit it, `compose.mjs` builds a valid fallback with a standard 400–700 weight set, but the family-specific axes are lost — so emit it.)
-- **`spacing`** — a full rhythm scale, every step `2xs` through `4xl` (`2xs, xs, sm, md, lg, xl, 2xl, 3xl, 4xl`), each a concrete length (e.g. `"1rem"`). The brand's spacing rhythm, not container widths.
+- **(no `spacing`)** — do not author a spacing scale. The build uses Tailwind v4's built-in numeric spacing (`gap-4`, `py-24`, …); a named `--spacing-<size>` scale was removed because its t-shirt names collided with the width utilities. Spacing is not your concern.
 - **`rounded`** — corner radii (DESIGN.md's name for radius tokens): `sm` and `md` required; `lg`, `xl` if the brand uses larger curves. Concrete lengths.
 - **`containers`** — content/reading widths (a DESIGN.md extension this skill uses), **conceptually separate from spacing**: `prose` (a readable text column, ~`42rem`), plus `md`, `3xl`, `6xl` as page max-widths. Widths, not spacing steps — never reuse a spacing value as a container value (a reading column is ~`42rem`, not `5rem`).
 
@@ -141,12 +131,12 @@ You pick *what the brand looks like* — "paper = `#FAF6EF`", "display face = Fr
 | Write `global.css`, token CSS, or any **site** file | Write **only** `DESIGN.md` (your design spec) — `emit-design-tokens.mjs` projects the token CSS from it, `compose.mjs` authors site files |
 | Echo the tokens inline in your return | They live in `DESIGN.md`; return only `data.shell` + the `designMdPath` you wrote (keeps the tokens out of the orchestrator's output) |
 | Unquoted hex in frontmatter (`paper: #FFFBF0`) | Quote every string value (`paper: "#FFFBF0"`) — an unquoted `#hex` parses as a comment and the token is lost |
-| Emit an `@theme` block, `--color-*` names, or Tailwind utilities | Return DESIGN.md frontmatter (`colors`/`typography`/`spacing`/`rounded`/`containers`); `compose.mjs` maps them |
+| Emit an `@theme` block, `--color-*` names, or Tailwind utilities | Return DESIGN.md frontmatter (`colors`/`typography`/`rounded`/`containers`); `compose.mjs` maps them |
 | Return the old `designTokens` shape (`fonts`, `radii`) | Use the DESIGN.md vocabulary: `typography` (with `fontFamily`), `rounded` — there is no separate token JSON anymore |
 | Decide CSS structure, View-Transitions, `@apply`, markers, file layout | All application — `compose.mjs`'s domain |
 | Read `STYLING.md`, templates, or `.astro` files | Every input is inlined; read only `DESIGN_MD.md` + `RETURN_CONTRACT.md` |
 | Branch on framework (astro vs custom) or loaded packs | The DESIGN.md is framework- and pack-blind by construction |
-| Alias a container width to a spacing value | `containers.prose` ≈ `42rem`; `spacing.3xl` ≈ `5rem` — different axes |
+| Author a `spacing` scale | Removed — the build uses Tailwind's numeric spacing (`gap-4`, `py-24`); only `colors`/`typography`/`rounded`/`containers`/`googleFontsHref` |
 | Ship a thin palette ("downstream will add what it needs") | Completeness is the contract — fill every semantic role |
 | Substitute or "upgrade" the display/body family (swap the approved Fraunces for Playfair) | Use the exact `display`/`body` families from the Typography input verbatim; you choose only weights/axes |
 | Introduce a hue not in the approved palette for `paper`/`ink`/`accent`, or "improve" the brand color | `accent` = approved accent hex, `paper` = approved background, `ink` = approved text; other roles are tonal variants of those |

package/skills/wix-headless/references/astro/bookings/COMPONENTS.md

@@ -17,7 +17,7 @@ Read `references/shared/IMPLEMENTER.md` + `references/shared/STYLING.md` first.
 | File | From template | Role |
 |------|---------------|------|
 | `src/components/ServiceBookingFlow.tsx` | `…/ServiceBookingFlow.tsx` | `client:only` coordinator — holds the selected slot, swaps calendar → form, redirects on success. Mounted by `services/[slug].astro`. |
-| `src/components/AvailabilityCalendar.tsx` | `…/AvailabilityCalendar.tsx` | the **week calendar** — week strip + nav → the picked day's slots. APPOINTMENT → `availabilityTimeSlots`; CLASS → `eventTimeSlots`. |
+| `src/components/AvailabilityCalendar.tsx` | `…/AvailabilityCalendar.tsx` | the **week calendar** — week strip + nav → the picked day's slots. APPOINTMENT → `availabilityTimeSlots`; CLASS → `eventTimeSlots`. Optional **staff picker** (shown when >1 staff; filters availability + records `slot.resource`) and **location picker** (shown when the service has >1 business location; **always scopes availability to one location** — defaulting to the carried/first — so a multi-location service doesn't return duplicate per-location slots). Both fed by props from the SSR page. |
 | `src/components/BookingForm.tsx` | `…/BookingForm.tsx` | the **schema-driven** form — renders the `@wix/forms` field list (passed in from the SSR page), keys values by `target`, calls `bookingDriver.book()`. |
 
 ## astro-specific rules

package/skills/wix-headless/references/astro/bookings/SERVICES_PAGES.md

@@ -29,6 +29,17 @@ Plus the nav/home links (shell chain — see below).
    in frontmatter 500s in the deployed runtime (the env var is client-only).
    Always include **`appId`** in the filter. Single service by slug: the
    `.eq("mainSlug.name", slug).eq("appId", BOOKING_APP_ID).limit(1).find()` chain.
+   The same elevation works for `services.queryLocations` and
+   `categoriesV2.queryCategories` (used by the optional catalog filters, below).
+1b. **Optional catalog filters (location + category) — auto-skip; see `../../bookings/FLOW.md` §7.**
+   The catalog page reads `?locationId`/`?category` from the request URL and merges
+   them into the **same** `queryServices` filter (location → `locations.business.id`
+   $hasSome, or the synthetic `locations.type` mapping; category → `category.id` $eq).
+   It SSRs `queryLocations()` (show the selector only when business+custom+customer
+   count > 1) and `queryCategories().find()` (non-fatal — render without the bar on
+   failure; show only when > 1 category). The chosen location is carried into the
+   detail link (`ServiceCard` `locationId`/`locationType` props) so availability is
+   scoped to it. Reference: `…/templates/bookings/services/index.astro`.
 2. **The detail page fetches the booking-form schema server-side.** Read
    `service.form._id`'s form via `@wix/forms` (`auth.elevate(forms.getForm)(formId)`),
    map `formFields` to `{ label, target, required, componentType, identifier, options }`,
@@ -37,6 +48,14 @@ Plus the nav/home links (shell chain — see below).
    complex object-valued fields (e.g. the default form's multi-line `ADDRESS`), or
    `createBooking` fails with "must be object". Pass the full `service` too — the
    booking step reads its payment/policy. Same field-mapping as `../forms/CONTACT_FORM.md`.
+   Also pass, through to `<ServiceBookingFlow>`: `service.staffMemberDetails?.staffMembers`
+   (the staff picker — the service was queried with `STAFF_MEMBER_DETAILS`); the
+   service's **business `locations`** — sourced from `auth.elevate(services.queryLocations)()`
+   (the site's real business locations) intersected with the service's own location ids,
+   NOT from `service.locations` alone (its ids can be ones the availability engine doesn't
+   recognize → 0 slots) — so the calendar scopes availability to one location and avoids
+   duplicate per-location slots (FLOW.md §7); and the `?locationId` read from the request
+   URL (the picker's default).
 3. **Only the read pages are SSR.** The detail page SSRs the service info for SEO,
    then the booking UI runs in the `client:only` island. Do not SSR availability.
 4. **Confirmation renders from query params.** The booking step redirects with

package/skills/wix-headless/references/astro/cms/FAQ_KNOWLEDGE_BASE.md

@@ -180,7 +180,7 @@ Key details:
 
 ### 3. FAQ Page (`src/pages/faq/index.astro`)
 
-**Layout width:** Center the page column with `container-reading` (from designer `global.css`) or `max-w-6xl mx-auto px-lg` when `--container-6xl` exists in `@theme`. **Do not** use `max-w-3xl` unless `--container-3xl` is declared in `@theme` — with only a spacing scale, Tailwind maps `max-w-3xl` to ~5rem and the FAQ collapses to one word per line. See `references/shared/STYLING.md` § "Prose / reading width".
+**Layout width:** Center the page column with `container-reading` (from designer `global.css`) or `max-w-6xl mx-auto px-6` when `--container-6xl` exists in `@theme`. **Do not** use `max-w-3xl` unless `--container-3xl` is declared in `@theme` — with only a spacing scale, Tailwind maps `max-w-3xl` to ~5rem and the FAQ collapses to one word per line. See `references/shared/STYLING.md` § "Prose / reading width".
 
 ```astro
 ---
@@ -195,7 +195,7 @@ const categories = [...grouped.entries()].map(([name, items]) => ({ name, items
 
 <Layout title="FAQ">
   <main>
-    <div class="container-reading px-lg">
+    <div class="container-reading px-6">
       <h1>Frequently Asked Questions</h1>
       <p>Find answers to common questions below, or use the search to find what you need.</p>
 

package/skills/wix-headless/references/astro/designer/INSTRUCTIONS.md

@@ -102,8 +102,8 @@ All page scopes share common inputs and rules. Scope-specific details follow.
     </section>
     ```
 8. **Comments in frontmatter.** Use `//` or `/* */` — never HTML `<!-- -->` comments in `.astro` frontmatter (it's TypeScript, not HTML). HTML comments in the template section are fine.
-9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and the spacing scale from `@theme`.
-10. **Use Tailwind utility classes in templates.** For layout, spacing, typography, and responsive design — use utility classes directly in the markup. Contract classes are still required for components referenced by Phase 3/4 agents. Mix both: `<div class="product-grid grid grid-cols-1 md:grid-cols-3 gap-lg">`. Always use brand `@theme` tokens (e.g., `bg-bark`, `text-cream`) — never default Tailwind colors.
+9. **Responsive.** All pages must work at mobile (320px), tablet (768px), and desktop (1024px+). Use Tailwind responsive prefixes (`md:`, `lg:`) and Tailwind's numeric spacing scale (`gap-4`, `py-24`, …).
+10. **Use Tailwind utility classes in templates.** For layout, spacing, typography, and responsive design — use utility classes directly in the markup. Contract classes are still required for components referenced by Phase 3/4 agents. Mix both: `<div class="product-grid grid grid-cols-1 md:grid-cols-3 gap-6">`. Always use brand `@theme` tokens (e.g., `bg-bark`, `text-cream`) — never default Tailwind colors.
 11. **No duplicate files.** If two scopes list the same file (rare), the scope whose prompt explicitly names it as "owned" takes precedence. If unclear, write it and note the overlap in your return.
 12. **Do NOT write to `src/styles/components-<pack>.css` or `src/styles/global.css`** — `components-<pack>.css` is pre-copied from the skill template by the orchestrator (build-wave pre-batch); `global.css` is owned by the Composer. Writing to either causes double-write conflicts.
 
@@ -317,7 +317,7 @@ The JSON block MUST be the **last** content in your message — the parent parse
 | Author a `.tsx` React island in a page scope | Phase 3 Components writes the islands; the route only **mounts** them (`client:load`) |
 | Ship hardcoded data arrays as the final page | Query live SDK data in frontmatter (per the vertical reference) and bind it; hardcoded shapes are only a fallback for empty queries |
 | Write `global.css` or `@theme` tokens | The Composer owns `global.css`; you consume the published token contract |
-| Invent global semantic classes for layout/spacing/typography (`.featured-section`, `.page-header`) | Use Tailwind utilities derived from `@theme` tokens at the call site (`<section class="py-4xl">`); see `../../shared/STYLING.md` |
+| Invent global semantic classes for layout/spacing/typography (`.featured-section`, `.page-header`) | Use Tailwind utilities derived from `@theme` tokens at the call site (`<section class="py-24">`); see `../../shared/STYLING.md` |
 | Override `global.css` rules from page `<style>` blocks | Pages can add co-located styles for one-off decoration; never override Composer-owned global classes |
 | HTML `<!-- comment -->` in `.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript |
 | Use external placeholder image services (picsum, unsplash) | Use colored `<div>` placeholders with `data-decorative-slot` — the orchestrator injects Image Phase 1 URLs later |

package/skills/wix-headless/references/astro/ecom/CART_WIRING.md

@@ -22,7 +22,7 @@ Files this agent MUST NOT touch:
 
 Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave).
 
-For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
+For layout/spacing/typography, compose Tailwind utilities derived from `@theme` tokens at the call site (`<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-12">`). For published global semantic classes (`cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — the compound + interactive-state patterns), use the ACTUAL class name verbatim. Row-internal class names (`cart-item-qty`, `qty-btn`, etc.) come from the template — keep them as-is and live in `components-ecom.css`. See `references/shared/STYLING.md` and `references/shared/IMPLEMENTER.md` § "Styling: tokens-first, classes as exception".
 
 ## Template files
 
@@ -61,7 +61,7 @@ Full cart display with two-column layout, quantity editing, remove, unavailable
 Class names used (template provides them — do not invent):
 - **Global semantic classes** (in `global.css`, designer-owned): `cart-summary`, `cart-total`, `checkout-btn`, `cart-empty` — compound patterns + interactive states
 - **Row-internal classes** (in `components-ecom.css`, written by this scope): `cart-item-qty`, `qty-btn`, `qty-value`, `cart-item-unavailable`, `cart-item-actions`, `cart-item-prices`, `cart-item-full-price`, `cart-item-unit-price`, `cart-item-line-total`, `cart-item-remove`, `cart-item-image-link`, `cart-item-name-link`, `cart-discount`, `cart-discount-name`, `cart-discount-amount`, `cart-applied-discounts`, `cart-applied-discounts-name`, `cart-item-option`, `cart-item-modifiers`
-- **Layout/spacing in markup as utilities**: `cart-grid` → `<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-2xl md:gap-3xl md:items-start">`; `cart-items` → `<div class="flex flex-col gap-lg">`; `cart-item` → `<div class="flex gap-lg pb-lg border-b border-rule last:border-0">`; `cart-subtotal` → `<div class="flex justify-between items-baseline">`; `cart-item-image` → utilities; `cart-item-info` → utilities; `cart-item-name` → `class="font-display text-lg leading-tight"`
+- **Layout/spacing in markup as utilities**: `cart-grid` → `<div class="grid grid-cols-1 md:grid-cols-[1fr_22rem] gap-12 md:gap-16 md:items-start">`; `cart-items` → `<div class="flex flex-col gap-6">`; `cart-item` → `<div class="flex gap-6 pb-6 border-b border-rule last:border-0">`; `cart-subtotal` → `<div class="flex justify-between items-baseline">`; `cart-item-image` → utilities; `cart-item-info` → utilities; `cart-item-name` → `class="font-display text-lg leading-tight"`
 
 ### 2. `src/components/CartBadge.tsx`
 

package/skills/wix-headless/references/astro/ecom/COMPONENTS_CSS.md

@@ -23,7 +23,7 @@ You only need:
 2. **`<SKILL_ROOT>/references/shared/STYLING.md`** — the styling-contract conventions (how to use `@apply`, the `@theme` token utilities, the no-default-Tailwind-colors rule, and the global-vs-scoped CSS ownership boundary).
 3. **`<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`** — the return JSON shape.
 4. **`src/styles/global.css`** in the project — read to audit for ecom-class leaks (see § "Global-CSS leak audit" below).
-5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
+5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`rounded`/`containers`; spacing is Tailwind's numeric scale, not a token) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
 
 You do NOT need to read `INSTRUCTIONS.md`, `CART_WIRING.md`, the TSX templates, the `discounts.ts` util, or any other reference. Skipping those reads is the point of the split.
 
@@ -35,7 +35,7 @@ You do NOT need to read `INSTRUCTIONS.md`, `CART_WIRING.md`, the TSX templates,
 <SKILL_ROOT>/references/astro/templates/ecom/components-ecom.css
 ```
 
-This is the canonical scoped CSS for the ecom pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--spacing-md`, `--font-display`, etc.). **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
+This is the canonical scoped CSS for the ecom pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--radius-md`, `--font-display`, etc.); spacing uses Tailwind's numeric scale (`gap-4`, `py-24`), not a token. **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
 
 ### 2. The two `@reference` directives are mandatory
 
@@ -46,7 +46,7 @@ The first two non-comment lines of `components-ecom.css` MUST be:
 @reference "./global.css";
 ```
 
-Without these, Tailwind v4 fails the build with `"Cannot apply unknown utility class"` on any `@apply` rule that uses a utility like `size-6` or `gap-md`. The template ships them; do not remove.
+Without these, Tailwind v4 fails the build with `"Cannot apply unknown utility class"` on any `@apply` rule that uses a utility like `size-6` or `gap-4`. The template ships them; do not remove.
 
 ### 3. Class ownership
 

package/skills/wix-headless/references/astro/gift-cards/COMPONENTS.md

@@ -18,7 +18,7 @@ Files this agent MUST NOT touch:
 
 ## Coordination: design tokens
 
-Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). Reference token CSS variables (`var(--color-cream)`, `var(--spacing-lg)`, etc.) from `components-gift-cards.css`.
+Read the design tokens from `.wix/design-tokens.css` (on disk, gate-verified present before the wave). Reference token CSS variables (`var(--color-cream)`, `1.5rem`, etc.) from `components-gift-cards.css`.
 
 ## Critical rules
 
@@ -81,7 +81,7 @@ Scoped styles for:
 
 The page-section and teaser styles live here (not inside the .astro `<style>` blocks) so the same separation as `components-stores.css` / `components-ecom.css` holds. The pages-scope agent imports this stylesheet via `Layout.astro`'s existing CSS chain (designer foundation already wires up the `components-*.css` import).
 
-Use brand `@theme` utilities (`bg-cream`, `text-ink`, etc.) where natural; fall back to `var(--color-*)` / `var(--spacing-*)` directly when a property isn't covered. Do not introduce new design-token names.
+Use brand `@theme` utilities (`bg-cream`, `text-ink`, etc.) where natural; fall back to `var(--color-*)` directly (spacing is Tailwind's numeric scale — `gap-4`, `py-24`) when a property isn't covered. Do not introduce new design-token names.
 
 ## Return format
 

package/skills/wix-headless/references/astro/stores/BACK_IN_STOCK.md

@@ -77,11 +77,11 @@ The `components-stores.css` template already covers options/quantity/modifiers/s
 ```css
 /* --- Back-in-stock subscribe form (BackInStockForm.tsx) --- */
 .back-in-stock-form {
-  @apply flex flex-col gap-md mt-md p-lg border border-rule rounded;
+  @apply flex flex-col gap-4 mt-4 p-6 border border-rule rounded;
   background-color: var(--color-cream);
 }
 .back-in-stock-headline {
-  @apply flex flex-col gap-sm;
+  @apply flex flex-col gap-3;
 }
 .back-in-stock-eyebrow {
   @apply font-heading text-xs uppercase tracking-wider text-bark/70;
@@ -94,10 +94,10 @@ The `components-stores.css` template already covers options/quantity/modifiers/s
   @apply font-heading text-xs uppercase tracking-wider text-bark/70;
 }
 .back-in-stock-row {
-  @apply flex flex-row flex-wrap gap-sm;
+  @apply flex flex-row flex-wrap gap-3;
 }
 .back-in-stock-input {
-  @apply flex-1 px-md py-sm font-body text-sm border border-rule rounded bg-parchment text-ink;
+  @apply flex-1 px-4 py-3 font-body text-sm border border-rule rounded bg-parchment text-ink;
   min-width: 0;
   transition: border-color 0.15s ease;
 }
@@ -108,7 +108,7 @@ The `components-stores.css` template already covers options/quantity/modifiers/s
   @apply border-rust;
 }
 .back-in-stock-submit {
-  @apply px-lg py-sm font-heading text-xs uppercase tracking-wider bg-bark text-cream rounded cursor-pointer transition-colors;
+  @apply px-6 py-3 font-heading text-xs uppercase tracking-wider bg-bark text-cream rounded cursor-pointer transition-colors;
   border: 1px solid var(--color-bark);
 }
 .back-in-stock-submit:hover:not(:disabled) {
@@ -121,7 +121,7 @@ The `components-stores.css` template already covers options/quantity/modifiers/s
   @apply font-body text-sm text-rust;
 }
 .back-in-stock-success {
-  @apply mt-md p-lg border border-rule rounded;
+  @apply mt-4 p-6 border border-rule rounded;
   background-color: var(--color-cream);
 }
 .back-in-stock-success-headline {
@@ -134,7 +134,7 @@ The `components-stores.css` template already covers options/quantity/modifiers/s
   margin: 0;
 }
 .stock-status.back-in-stock-alt {
-  @apply mt-sm font-body text-sm italic text-bark/70;
+  @apply mt-3 font-body text-sm italic text-bark/70;
 }
 ```
 

package/skills/wix-headless/references/astro/stores/COMPONENTS_CSS.md

@@ -23,7 +23,7 @@ You only need:
 2. **`<SKILL_ROOT>/references/shared/STYLING.md`** — the styling-contract conventions (how to use `@apply`, the `@theme` token utilities, the no-default-Tailwind-colors rule, and the global-vs-scoped CSS ownership boundary).
 3. **`<SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`** — the return JSON shape.
 4. **`src/styles/global.css`** in the project — read to audit for stores-class leaks (see § "Global-CSS leak audit" below).
-5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
+5. **Design tokens (on disk)** — read the design tokens (the DESIGN.md vocabulary — `colors`/`typography`/`rounded`/`containers`; spacing is Tailwind's numeric scale, not a token) from `.wix/design-tokens.css` (gate-verified present before the wave). They are NOT inlined in your prompt.
 
 You do NOT need to read `INSTRUCTIONS.md`, `SHARED_WIRING.md`, `BACK_IN_STOCK.md`, the TSX templates, the back-in-stock util, or any other reference. Skipping those reads is the point of the split — they would consume tokens for context this scope doesn't use.
 
@@ -35,7 +35,7 @@ You do NOT need to read `INSTRUCTIONS.md`, `SHARED_WIRING.md`, `BACK_IN_STOCK.md
 <SKILL_ROOT>/references/astro/templates/stores/components-stores.css
 ```
 
-This is the canonical scoped CSS for the stores pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--spacing-md`, `--font-display`, etc.). **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
+This is the canonical scoped CSS for the stores pack. Adapt sizing/spacing to the brand's aesthetic — use the design tokens from your prompt (`--color-bark`, `--color-cream`, `--radius-md`, `--font-display`, etc.); spacing uses Tailwind's numeric scale (`gap-4`, `py-24`), not a token. **Do not rename the class names or state modifiers** — they must match the contract keys the TSX components reference.
 
 ### 2. Use `@apply` with brand `@theme` utilities
 
@@ -49,8 +49,8 @@ Do **NOT** use default Tailwind colors (`bg-green-50`, `text-red-600`). The bran
 
 Classes you own (define rules in `components-stores.css`):
 
-- **`.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index`** — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: var(--spacing-md)` on the card plus horizontal padding on each text block when you set the radius.
-- **`.product-grid`** — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: var(--spacing-xl);` plus the View-Transitions opacity fade for in-flight navigations.
+- **`.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index`** — the product card itself, including the `overflow: hidden` + `border-radius` clipping context. Whoever writes the `border-radius` here also writes any inner padding required to keep child content inside the rounded edges. Without inner padding, a price `<p>` sits flush against the rounded bottom corner and descenders get clipped. Add `padding-bottom: 1rem` on the card plus horizontal padding on each text block when you set the radius.
+- **`.product-grid`** — the layout that lists product cards. Both `/products` (pages-products scope) and `/category/[slug]` (pages-categories scope) consume it from one place. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 2rem;` plus the View-Transitions opacity fade for in-flight navigations.
 - **`.offer-callout` family (`.offer-callout`, `-item`, `-badge`, `-name`, `-detail`, `-foot`)** — discount panel rendered above `<ProductPurchase>` on `/products/[slug]`.
 - **Option-selector contract classes** — `option-group`, `option-label`, `option-choices`, `option-pill` (with `.selected` state modifier).
 - **Quantity-stepper contract classes** — `quantity-selector`, `quantity-btn`, `quantity-value`.

package/skills/wix-headless/references/astro/stores/PRODUCT_PAGES.md

@@ -21,7 +21,7 @@ Files this agent MUST NOT touch:
 ## Inputs (from parent prompt)
 
 - **Phase 1 return data** — `products: [{id, name, slug, variantId, price, inventory, sku}]` — use slugs when needed (rarely; `queryProducts` returns them already).
-- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-4xl flex flex-col gap-md font-display"`) at the call site rather than inventing semantic classes for layout/spacing/typography. Retained global semantic classes are limited to compound patterns (`offer-callout`, `cart-summary`), interactive primitives (`btn-primary`, `product-card`), and JS targets — see `references/shared/STYLING.md`.
+- **Design tokens** — read the design tokens (the DESIGN.md vocabulary) from `.wix/design-tokens.css` (on disk) for the published color/spacing/typography vocabulary; compose Tailwind utilities derived from those tokens (`class="py-24 flex flex-col gap-4 font-display"`) at the call site rather than inventing semantic classes for layout/spacing/typography. Retained global semantic classes are limited to compound patterns (`offer-callout`, `cart-summary`), interactive primitives (`btn-primary`, `product-card`), and JS targets — see `references/shared/STYLING.md`.
 - **Designer visual spec** — the layout, contract classes, and decorative-slot conventions for `products/index.astro`, `products/[slug].astro`, `ProductCard.astro` (from `references/astro/designer/INSTRUCTIONS.md` → `store-pages`), applied in the same pass as the live queries.
 
 ## Critical rules (all must be honored)
@@ -33,7 +33,7 @@ Files this agent MUST NOT touch:
 5. **Mount `ProductPurchase` with `client:load` and a single `product` prop, plus the back-in-stock probe + price props.** `<ProductPurchase client:load product={product} inventoryByVariant={inventoryByVariant} backInStockEnabled={backInStockEnabled} priceAmount={priceAmount} />`. The component destructures internally; passing flat props (`productId={product._id}`, `options={product.options}`, …) silently renders nothing because the new contract expects `product`. The `backInStockEnabled` boolean comes from `await getBackInStockEnabled()` (template imports it from `../../utils/back-in-stock`); `priceAmount` is the numeric price already computed in the frontmatter. See `BACK_IN_STOCK.md` for why both are needed.
 6. **SSR only — do NOT add `export const prerender = true` or `getStaticPaths()`.** The productsV3 SDK depends on request-context auth (tenant resolution, site headers). At prerender time there is no request, and `.queryProducts().limit()` short-circuits to `"is not a function"`. Keep `[slug].astro` server-rendered with `Astro.params.slug`.
 7. **No HTML comments in `.astro` frontmatter.** Build fails with "Legacy HTML single-line comments are not allowed".
-8. **Default to tokens-as-utilities for layout/spacing/typography.** When you need a section padding, a flex column, a typographic treatment — write Tailwind utilities derived from `@theme` tokens (`<section class="py-4xl flex flex-col gap-md">`, `<h1 class="font-display text-4xl">`). Do NOT invent semantic classes like `.featured-section`, `.page-header`, `.products-header-image` — Tailwind v4 silently drops undeclared classes. Use a global semantic class only when one is published in designer `INSTRUCTIONS.md`'s always-required list (`product-card`, `product-card-ribbon`, `offer-callout` family). For one-off page decoration, write a co-located `<style>` block at the bottom of the same `.astro` file using `var(--color-foo)` token references.
+8. **Default to tokens-as-utilities for layout/spacing/typography.** When you need a section padding, a flex column, a typographic treatment — write Tailwind utilities derived from `@theme` tokens (`<section class="py-24 flex flex-col gap-4">`, `<h1 class="font-display text-4xl">`). Do NOT invent semantic classes like `.featured-section`, `.page-header`, `.products-header-image` — Tailwind v4 silently drops undeclared classes. Use a global semantic class only when one is published in designer `INSTRUCTIONS.md`'s always-required list (`product-card`, `product-card-ribbon`, `offer-callout` family). For one-off page decoration, write a co-located `<style>` block at the bottom of the same `.astro` file using `var(--color-foo)` token references.
 9. **Preserve designer classes.** When the designer used a published global semantic class on existing markup, keep it; don't rename. Add Tailwind utilities alongside if you need additional layout adjustment.
 
 ## Wix Site Structure — `wixMetadata` + `@wix/astro-pages`

package/skills/wix-headless/references/astro/templates/Footer.astro

@@ -10,18 +10,18 @@
 const year = new Date().getFullYear();
 ---
 <footer class="site-footer" transition:persist="site-footer">
-  <div class="max-w-6xl mx-auto px-lg py-3xl flex flex-col md:flex-row md:items-start md:justify-between gap-xl">
-    <div class="flex flex-col gap-sm max-w-prose">
+  <div class="max-w-6xl mx-auto px-6 py-16 flex flex-col md:flex-row md:items-start md:justify-between gap-8">
+    <div class="flex flex-col gap-3 max-w-prose">
       <span class="font-display text-lg text-ink">{{brand.name}}</span>
       <p class="text-sm">{{shell.footerTagline}}</p>
     </div>
     <nav>
-      <ul class="flex flex-col gap-sm text-sm">
+      <ul class="flex flex-col gap-3 text-sm">
         {{nav.links}}
       </ul>
     </nav>
   </div>
-  <div class="max-w-6xl mx-auto px-lg pb-xl text-xs">
+  <div class="max-w-6xl mx-auto px-6 pb-8 text-xs">
     <p>© {year} {{brand.name}}. All rights reserved.</p>
   </div>
 </footer>

package/skills/wix-headless/references/astro/templates/Navigation.astro

@@ -9,7 +9,7 @@
 // the empty <div class="nav-actions"> mount, the mobile hamburger toggle.
 ---
 <header class="site-nav" transition:persist="site-nav">
-  <nav class="max-w-6xl mx-auto px-lg flex items-center justify-between gap-lg py-md">
+  <nav class="max-w-6xl mx-auto px-6 flex items-center justify-between gap-6 py-4">
     <a href="/" class="font-display text-lg tracking-tight">{{shell.navBrandMark}}</a>
 
     <input type="checkbox" id="nav-toggle" class="peer hidden" aria-hidden="true" />
@@ -25,10 +25,10 @@
 
     <div
       class="hidden peer-checked:flex md:flex absolute md:static top-full left-0 right-0 md:right-auto
-             flex-col md:flex-row gap-md md:gap-lg items-start md:items-center
-             bg-paper md:bg-transparent border-b md:border-0 border-rule px-lg md:px-0 py-md md:py-0"
+             flex-col md:flex-row gap-4 md:gap-6 items-start md:items-center
+             bg-paper md:bg-transparent border-b md:border-0 border-rule px-6 md:px-0 py-4 md:py-0"
     >
-      <ul class="flex flex-col md:flex-row gap-md md:gap-lg items-start md:items-center">
+      <ul class="flex flex-col md:flex-row gap-4 md:gap-6 items-start md:items-center">
         {{nav.links}}
         <!-- nav:links -->
       </ul>