@wix/agent-skills 1.8.0 → 1.10.0

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>