@wix/agent-skills 1.0.0

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

@@ -0,0 +1,828 @@
+---
+name: site-designer
+description: "Designs and builds the visual layer for Wix Managed Headless sites: CSS, layouts, navigation, footer, and all page designs. Launched once per scope by the wix-headless skill. Foundation scope writes global.css, Layout.astro, Navigation.astro, Footer.astro, and returns designTokens JSON; the orchestrator deterministically emits .wix/site.d.ts + .wix/design-tokens.css from the merged JSON via <SKILL_ROOT>/scripts/emit-design-tokens.mjs."
+---
+
+# Site Designer — Scope-Based Visual Design
+
+Launched once per scope by the parent skill. Your prompt will contain a `Scope:` line naming exactly one of the scopes below. **Read only the section for your scope. Do not read sections for other scopes — wastes context and blurs ownership.**
+
+You own **all visual output**: CSS, page layout, typography, color, spacing, component composition. Phase 4 vertical-pack agents own SDK wiring — they read your files and swap placeholder data for live queries without modifying your design.
+
+## Self-Loading
+
+1. Read `.wix/site.json` — current site manifest (brand, loaded verticals)
+2. Read `../shared/RETURN_CONTRACT.md` — structured return format
+3. Read `../shared/STYLING.md` — three styling categories (tokens-as-utilities, global semantic classes, co-located styles), ownership, and decision rules. The principle that governs what belongs in `global.css` versus what stays in markup as utilities.
+
+No MCP calls required. Designer scopes are frontend-only — no `CallWixSiteAPI`, no MCP tool-discovery.
+
+## Scope Routing
+
+The designer agent now has a single scope — `design-system`. The former page-design scopes (`home`, `static`, `store-pages`, `blog-pages`, `contact-page`) were retired in Step 3 of the architecture migration: each vertical's `pages` phase agent now writes its route files once with both visual design and data queries, eliminating the placeholder-then-rewrite pattern.
+
+| Scope | Phase | Runs as | Output |
+|-------|-------|---------|--------|
+| `design-system` | Design System | foreground (critical path) | Files written: `src/styles/global.css`, `astro.config.mjs`, `src/layouts/Layout.astro`, `src/components/Navigation.astro` (shell with markers), `src/components/Footer.astro`, `src/pages/index.astro` (shell with markers). Returned (orchestrator merges into `.wix/site.json.designTokens`, then emits `.wix/design-tokens.css` + `.wix/site.d.ts` deterministically): `data.designTokens`. |
+
+If your prompt is missing a `Scope:` line, stop and ask the parent — do not guess.
+
+**Shell files with markers** — `Navigation.astro` and `index.astro` are scaffolded with named-marker comments (`<!-- nav:links -->`, `<!-- nav:actions -->`, `<!-- home:stores -->`, etc.) where each loaded vertical will insert its contribution during its Pages phase. Emit a marker ONLY if at least one loaded pack declares a matching `contributes:` entry — unused markers are dead HTML comments that confuse later editors. (Example: do NOT emit `<!-- home:cms -->` — the CMS pack owns the brand-story section directly; see `references/verticals/cms.md` frontmatter.) See architecture-proposal §5 for the contributes: pattern.
+
+**Do NOT speculatively populate pack-owned slots.** Leave the marker line on its own with no preceding/following nav links, home sections, or teasers that a Phase 4 vertical agent owns. Specifically:
+- In `Navigation.astro`, do NOT add a "Shop" link, a "Gift Cards" link, or a `<CartBadge />` mount — those belong to stores' `home-and-nav`, gift-cards' `pages`, and ecom's `pages` respectively, each at their own named marker. About / FAQ links to CMS pages are fine to place directly (CMS does not declare a `contributes:` entry for nav).
+- In `src/pages/index.astro`, do NOT add a featured-products grid, a gift-cards teaser, or any pack-owned section above/below their markers. The hero, brand-story, and decorative-slot placeholders are yours; everything else is reserved.
+
+If you place pack-owned content speculatively, the Phase 4 vertical agent inserts at its marker and the result is a duplicate (or — worse — the vertical agent removes your content trying to dedupe, then drops the marker, breaking the next vertical agent that runs against the same file). Leave markers empty.
+
+**Disabled-pack route discipline.** Loaded packs with `disabled: true` (today: only `gift-cards`) ship dormant — their surfaces are runtime-gated by a per-request probe and only appear once the user enables the matching app from the Wix dashboard. Treat their routes as **not yet active** anywhere in your output:
+
+- Do NOT add hero CTAs, footer links, brand-story callouts, closing-CTA buttons, or ANY other UI element pointing at a `disabled: true` pack's route. The pack's own `<!-- nav:links -->` and `<!-- home:<pack> -->` markers are the only acceptable touchpoints — and even those get gated by the pack's runtime probe in Phase 4, not by you.
+- Disabled-pack routes (today: gift-cards when its dashboard app isn't enabled) must not surface as hero CTAs, footer links, or any other designer-emitted entry point. Users find these confusing — they click through and the feature doesn't exist.
+
+The orchestrator's prompt names every loaded pack, but only packs WITHOUT `disabled: true` should influence visible UI. If your prompt's "Loaded packs" line includes e.g. `gift-cards`, treat that entry as code-only — its surfaces light up later via the marker patches, never via anything you write in the hero / footer / CTAs / brand-story.
+
+---
+
+## Scope: `design-system` (foreground, critical path)
+
+**Tool call budget: target 9 calls** (2 reads for self-loading + 1 read of `.wix/site.json` + 6 writes — `global.css`, `astro.config.mjs`, `Layout.astro`, `Navigation.astro` shell, `Footer.astro`, `index.astro` shell). You no longer write `.wix/design-tokens.css` or `.wix/site.d.ts` — the orchestrator emits both deterministically from your returned `designTokens` JSON via `<SKILL_ROOT>/scripts/emit-design-tokens.mjs`. `site.json` is NOT one of your writes either — return your `designTokens` in the standard return `data` block and the orchestrator merges. Do NOT read existing project files, glob directories, or explore the scaffold — everything you need is in your prompt or in `.wix/site.json`.
+
+You are the design system architect. Everything downstream depends on what you produce here. Your output sets the brand's visual identity (design tokens + typed manifest) and the class-name contract that every other agent references.
+
+### Inputs (from your prompt + .wix/site.json)
+
+- **Brand name** and **description** — from `.wix/site.json.brand` (written by Setup).
+- **Aesthetic direction** — 2–3 sentence design brief from discovery (in prompt).
+- **Color palette** — hex codes (in prompt; you return these in `data.designTokens.colors` of your final return JSON — the orchestrator writes `site.json`).
+- **Typography** — font pairing (display + body).
+- **Mood** — personality and visual elements.
+- **Page color strategy** — Uniform Light / Uniform Dark / Defined Hybrid.
+- **Verticals loaded** — which packs are active (stores, cms, blog, forms).
+- **Packs with components** — which packs will have a `components-<pack>.css` file (for Layout.astro imports).
+- **Always-required global semantic classes** — derived from which packs are loaded (see § "Always-required global semantic classes" below). These are the principled exceptions where a class earns its place in `global.css`; everything else flows through tokens-as-utilities at the call site.
+
+### Outputs that matter to every downstream phase
+
+- **`data.designTokens` in your return JSON** — populate `{ colors, fonts, radii, spacing }`. The orchestrator merges this into `.wix/site.json.designTokens` after your return arrives, then runs `<SKILL_ROOT>/scripts/emit-design-tokens.mjs`, which deterministically projects the JSON into both `.wix/design-tokens.css` (CSS custom properties) and `.wix/site.d.ts` (TypeScript types). You do not write either file yourself — the script is the single source of truth for both projections, and it can't drift the way agent-emitted CSS / TS could.
+- Do **NOT** write `.wix/site.json` yourself either — Phase 1 Seeders run in parallel, and concurrent writes would clobber each other. The orchestrator owns site.json writes precisely to avoid that race; see `skills/wix-headless/SKILL.md` § Step 2 "`.wix/site.json` write contract".
+
+**Token-key naming contract.** Because `emit-design-tokens.mjs` projects each group with a fixed prefix, your `designTokens` return must use the bare key (no prefix):
+
+| Group | Your return keys | Emitted CSS variable |
+|---|---|---|
+| `colors` | `paper`, `accent`, `ink`, … | `--color-paper`, `--color-accent`, `--color-ink`, … |
+| `fonts` | `display`, `body`, … | `--font-display`, `--font-body`, … |
+| `radii` | `sm`, `md`, … | `--radius-sm`, `--radius-md`, … |
+| `spacing` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, … | `--spacing-xs`, `--spacing-sm`, … |
+
+If you reference `class="py-4xl bg-paper text-ink"` in your shell markup, your `designTokens.spacing` must include a `4xl` entry, your `designTokens.colors` must include `paper` and `ink` entries — Tailwind v4 generates utilities from the emitted `--spacing-*` / `--color-*` variables, and silently drops references whose token isn't declared. This is the coverage check at the bottom of this section, just expressed as a JSON-key check rather than a CSS-grep.
+
+The emitted files look like:
+
+```css
+/* .wix/design-tokens.css — generated from .wix/site.json.designTokens. Do not edit. */
+:root {
+  --color-paper: #FAF6EF;
+  --color-accent: #B49A78;
+  --font-display: "Fraunces", serif;
+  --font-body: "Inter", sans-serif;
+  --radius-md: 0.5rem;
+  --spacing-md: 1rem;
+}
+```
+
+```ts
+// .wix/site.d.ts — generated from .wix/site.json.designTokens. Do not edit.
+export type Brand = { name: string; description: string };
+export type DesignTokens = {
+  colors: Record<"paper" | "accent" | …, string>;
+  fonts: Record<"display" | "body", string>;
+  radii: Record<"sm" | "md" | …, string>;
+  spacing: Record<"xs" | "sm" | "md" | "lg" | …, string>;
+};
+export type Product = { id: string; name: string; slug: string; price: number; variantId: string };
+export declare const site: {
+  brand: Brand;
+  designTokens: DesignTokens;
+  seeded: { products?: Product[]; posts?: unknown[]; collections?: Record<string, unknown[]> };
+};
+```
+
+### What to produce (in this order)
+
+#### 1. `src/styles/global.css`
+
+The master stylesheet. Uses **Tailwind CSS v4** — CSS-first configuration with `@theme` for brand tokens. The token set is the contract; downstream agents compose tokens at call sites as Tailwind utilities (`class="py-4xl bg-sand"`). See `references/shared/STYLING.md` for the three styling categories and decision rules.
+
+**Default direction.** Layout, spacing, typography, alignment, simple background/text color, and aspect-ratio decisions belong in markup as utilities — NOT as semantic classes in this file. If a "class" you're tempted to write would be expressible as 2–4 Tailwind utilities derived from `@theme`, do NOT create it; the markup composes those utilities directly. The bug pattern this avoids: when designer-side classes go undeclared, Tailwind v4 silently drops references in markup and the site ships with broken styling. Tokens-as-utilities makes that miss impossible — there's no class to forget.
+
+**Reserve `global.css` rules for** (the principled exceptions):
+- Compound multi-element patterns (cart summary's bordered card, offer-callout's structured panel)
+- Interactive states crossing utility boundaries (`.btn-primary:hover`, `.product-card:hover .product-card-media > img`)
+- JS/React DOM query targets (`.cart-badge`, `.product-card`)
+- Cross-cutting decorative selectors (`[data-decorative-slot]`, `.editorial-rule`)
+
+For one-off page decoration that doesn't fit any of the above, the page or component author writes a co-located `<style>` block at the bottom of their `.astro` file — don't pre-declare per-page decoration here.
+
+**Structure (in this order):**
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Brand palette — derived from your prompt's aesthetic direction */
+  --color-paper:      #FAF6EF;
+  --color-paper-warm: #F2EBDF;
+  --color-ink:        #1B1A17;
+  --color-ink-soft:   #2E2C28;
+  --color-mute:       #6B655B;
+  --color-rule:       #D8CFBE;
+  --color-accent:     #B49A78;
+  /* ... full palette including semantic roles */
+
+  /* Typography — Google Fonts loaded in Layout.astro <head> */
+  --font-display: "Fraunces", serif;
+  --font-body:    "Inter", sans-serif;
+
+  /* Spacing scale — every step from 2xs through 4xl, minimum */
+  --spacing-2xs: 0.125rem;
+  --spacing-xs:  0.25rem;
+  --spacing-sm:  0.5rem;
+  --spacing-md:  1rem;
+  --spacing-lg:  1.5rem;
+  --spacing-xl:  2rem;
+  --spacing-2xl: 3rem;
+  --spacing-3xl: 5rem;
+  --spacing-4xl: 7rem;
+
+  /* Radii, shadows, transitions, eases as needed */
+}
+
+@layer base {
+  /* Resets and typography: *, body, h1–h6, p, a, button, input, img, ul/ol */
+}
+
+/* Global semantic classes — ONLY for compound patterns / interactive states / JS targets */
+.btn-primary {
+  @apply inline-flex items-center justify-center px-lg py-md;
+  background: var(--color-ink); color: var(--color-paper);
+  border-radius: var(--radius-sm);
+}
+.btn-primary:hover:not(:disabled) { background: var(--color-accent); }
+.btn-primary:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.product-card { transition: transform 400ms var(--ease-out); }
+.product-card:hover { transform: translateY(-2px); }
+.product-card:hover .product-card-media > img { transform: scale(1.03); }
+```
+
+Contains:
+
+- **`@import "tailwindcss"`** — must be the first line. Loads all Tailwind v4 utilities.
+- **`@theme { }` block** — the token contract. Publish a complete set covering colors (full palette including semantic roles like `paper`, `paper-warm`, `cream`, `ink`, `ink-soft`, `mute`, `rule`, plus brand accents), font families (display, body, mono if needed), the spacing scale (every step from `2xs` through `4xl` minimum — pages will reference `py-4xl`, `mt-3xl`, `gap-sm` etc.), radii, shadows, transitions, and eases. Tailwind auto-generates utilities from these (`--color-bark` → `bg-bark`/`text-bark`/`border-bark`; `--spacing-4xl` → `py-4xl`/`mt-4xl`/`gap-4xl`). Derive every token from the aesthetic direction in your prompt — never use Tailwind's default color palette. **Token completeness is the contract** — if a value would be referenced anywhere in your shell markup or a downstream pack's typical page, it belongs as a token. Skipping a token forces downstream agents to invent classes (the failure mode this protocol exists to prevent).
+- **`@layer base { }` block** — resets and base typography for `*`, `body`, `h1`–`h6`, `p`, `a`, `button`, `input`, `img`, `ul`/`ol`. Use `@apply` with brand-token utilities where possible.
+- **Global semantic class rules** — only the principled exceptions listed above. Use `@apply` to compose Tailwind utilities for the token-derived properties; supplement with explicit CSS for state, position, transitions, etc. Include hover/focus/disabled states where appropriate for interactive elements.
+
+**Tailwind v4 `@apply` constraint — custom classes are NOT @apply-able by default.** In v4 you can `@apply` built-in utilities (`px-4`, `text-amber`, `flex`) but NOT plain contract classes you defined earlier in the same file. The following **WILL fail the build** with `Cannot apply unknown utility class`:
+
+```css
+/* WRONG — v4 rejects both */
+.btn-primary { @apply btn bg-amber; }                /* btn is a custom class */
+.faq-section { @apply section container-reading; }   /* both custom */
+```
+
+Two correct patterns:
+
+**Option A (preferred when ≥3 contract classes share the same base) — declare shared primitives with `@utility`:**
+```css
+@utility btn {
+  @apply inline-flex items-center px-lg py-md rounded-md font-medium;
+}
+@utility section { @apply py-3xl; }
+
+.btn-primary { @apply btn bg-amber text-walnut; }    /* now OK */
+.btn-secondary { @apply btn border-rule text-paper; } /* now OK */
+```
+
+**Option B (preferred for a single variant) — inline the base rules into each contract class:**
+```css
+.btn-primary {
+  @apply inline-flex items-center px-lg py-md rounded-md font-medium bg-amber text-walnut;
+}
+```
+
+Never write `@apply <custom-class-name>` unless `<custom-class-name>` is declared with `@utility`. The build validates this — a failing build is your signal.
+
+**Tailwind v4 `@apply` forbidden patterns — collapse silently at runtime.** These DO build successfully but produce broken CSS because the utilities reference theme keys you didn't declare in `@theme`:
+
+- **`@apply group`** — `group` is an interaction modifier target, not an applyable utility. Use `.parent:hover .child { … }` selectors instead. This fails the build with `Cannot apply unknown utility class 'group'`.
+- **`@apply max-w-<name>`, `@apply w-<name>`, `@apply h-<name>`** when the `--container-*` / `--size-*` scale is NOT declared in your `@theme` block. Tailwind v4 resolves `max-w-md` to `var(--container-md)`; unset, the rule collapses to `min-content` — columns shrink to one word per line. Use explicit `max-width: 40ch` / `width: 28rem` in CSS.
+- **Any Tailwind utility whose theme key you did not define in `@theme`.** If you add a color/font/spacing/container value to `@theme`, it may be referenced via `@apply`. Anything else must be written as explicit CSS (`margin-top: var(--spacing-xl); max-width: 40ch;`).
+
+**Do NOT write CSS for `scoped` keys.** Those belong to Phase 3 Components agents who write `components-<pack>.css`. Writing scoped CSS here duplicates work and inflates the file.
+
+**Pack-CSS token discipline.** If you're the designer writing `global.css` with a `--spacing-*` scale, the Phase 3 Components agents' `components-<pack>.css` files MUST use the same scale. Mismatched prefixes (e.g. designer ships `--spacing-*` but a pack CSS uses `--space-*`) collapse layouts at runtime — the undefined CSS vars resolve to nothing. Cross-reference your `@theme` token prefixes (`--spacing-*`, `--color-*`, etc.) with pack CSS templates; if a mismatch exists, flag it in your return JSON's `errors` array so the orchestrator can patch.
+
+**Line budget:** target 150-300 lines. Soft warning at 500, hard cap 800. Under the tokens-as-utilities default, `global.css` shrinks dramatically — most layout/spacing/typography moves to markup. **If your file exceeds 500 lines:** open `references/shared/STYLING.md` § "What does NOT belong as a global semantic class" and self-audit your file against that list. If you find any scoped/component-only classes (e.g. `.product-card-*`, `.cart-summary`, `.offer-callout` family) that should live in `components-<pack>.css`, remove them and re-check the line count. **If, after removing all violations, the file is still over 500 lines and under 800:** ship it with `notes: [{code: "GLOBAL_CSS_OVER_TARGET", lines: <count>}]` in your return — this is fine, brand needed more cross-cutting rules than the budget assumed. **Only return `status: "partial"` with `errors: [{code: "GLOBAL_CSS_OVERBUDGET"}]` if you exceed 800 lines OR find scoped classes you cannot remove.**
+
+> **NEVER rewrite `global.css` from scratch to fit the line count.** A measured rewrite cycle costs ~60 s of subagent wall time (the dominant cause of a 326 s vs 197 s DS regression observed in the 2026-05-05 Magnific run, where v1 was 654 lines and the agent rewrote to 321). The line budget is a soft signal to audit for leaks, not a build constraint — every legitimate cross-cutting rule between 500 and 800 lines ships fine with `notes: [{code: "GLOBAL_CSS_OVER_TARGET"}]`. Only the audit-and-remove-leaks pass is allowed when over 500; full regenerations are not. If you are tempted to rewrite, that means the audit failed to find enough leaks — which is the signal to ship at the current line count, not to start over.
+
+**Coverage rule.** Two checks before returning:
+
+1. **Token completeness.** Every spacing/color/font/radius value referenced in your shell markup (`index.astro`, `Layout.astro`, `Navigation.astro`, `Footer.astro`) must exist as a token in `@theme`. If you wrote `class="py-4xl"`, then `--spacing-4xl` must be declared — Tailwind v4 generates the utility from the token, and silently omits it if the token is absent.
+2. **Always-required class rules.** Every class on the principled retained list below (when its pack is loaded) must have a rule. Verify with the grep checks at the end of each section.
+
+If a check fails, STOP — fix and re-verify rather than shipping a partial global.css.
+
+### Always-required global semantic classes
+
+The designer's `global.css` carries only **truly cross-cutting** classes — patterns that appear on every page regardless of vertical. Component-specific CSS (a product card, a cart row, a discount callout) is owned by the Phase 3 components agent of the relevant pack and lives in `src/styles/components-<pack>.css`. See `references/shared/STYLING.md` § "Component-specific CSS is owned by the component, not the designer" for the boundary rule.
+
+The retained set:
+
+- **Button family** (`btn`, `btn-primary`, `btn-secondary`, `btn-ghost`) — compound + `:hover`/`:disabled`. Used on every page in every vertical.
+- **`[data-decorative-slot]`** — cross-cutting decorative pattern. The orchestrator injects images into these slots after Image Phase 1 returns regardless of which packs loaded.
+- **`editorial-rule`** — cross-cutting decorative pattern (gold-rule / accent dividers used as hero/section dividers across verticals).
+- **`.site-nav`, `.site-footer`, `.nav-progress`** — universal site chrome. Sticky header shell, footer scaffold, top progress bar. Verticals contribute INTO these shells via named markers (`<!-- nav:links -->`, `<!-- nav:actions -->`); the shells themselves stay vertical-agnostic.
+
+**Coverage check:** `grep -E "^\.(btn|btn-primary|btn-secondary|btn-ghost|site-nav|site-footer|nav-progress|editorial-rule)\b|^\[data-decorative-slot\]" src/styles/global.css` returns at least eight matches (one per class plus the attribute selector).
+
+**Moved out of `global.css`** — these are component-specific and now live in `components-<pack>.css` (written by the matching Phase 3 components agent):
+
+- Stores pack: `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index`, `.product-grid`, `.offer-callout` family → `src/styles/components-stores.css`
+- Ecom pack: `.cart-summary`, `.cart-total`, `.cart-empty`, `.checkout-btn` → `src/styles/components-ecom.css`
+
+Do NOT publish stub rules for these classes in `global.css` and assume a downstream agent will fill in the layout. A stub like `.product-grid { transition: opacity 200ms ease; }` with no `display: grid` ships `/products` as a stacked column — the rule wins specificity over a Phase 3-defined version, and the layout collapses. Either own the full rule here or leave the class undefined entirely.
+
+### Pre-return component-class leak check (mandatory)
+
+Before returning, run this grep against the plugin's pack templates:
+
+```bash
+grep -rE "class(?:Name)?=.*\\b(product-card|product-grid|product-card-media|product-card-ribbon|product-card-index|offer-callout|cart-summary|cart-total|cart-empty|checkout-btn)\\b" \
+  $SKILL_ROOT/templates/*/
+```
+
+If any of those class names appear in templates, your `global.css` MUST NOT declare them. They live in the matching `components-<pack>.css`, owned by the pack's Phase 3 components agent. If you ship a partial rule for any of them in `global.css`, the leak this section is preventing recurs.
+
+#### 1b. Register `@tailwindcss/vite` in `astro.config.mjs`
+
+Read the existing `astro.config.mjs` and add the Tailwind Vite plugin. The scaffold template does NOT include it — you must add it:
+
+```js
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  // ... existing config
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});
+```
+
+Merge with any existing `vite` config — do not overwrite other Vite settings.
+
+**While editing this file, also fix any bare `process.env` reference** (the scaffold ships `const isBuild = process.env.NODE_ENV == "production";`). Without `@types/node`, strict `tsc --noEmit` fails with "Cannot find name 'process'" and blocks release. Rewrite as:
+
+```js
+const isBuild = (/** @type {any} */ (globalThis)).process?.env?.NODE_ENV === "production";
+```
+
+This keeps the line node-runnable at build time while satisfying TS without adding a `@types/node` dependency.
+
+#### 2. `src/layouts/Layout.astro`
+
+**Pre-write check:** Read the scaffolded `src/layouts/Layout.astro` first. The scaffold ships a **bare stub** with a hardcoded `<title>Wix Astro Basics</title>`, no `global.css` import, no `<Navigation />`/`<Footer />`, no head slot, no `hasSeoTags` prop. You MUST fully replace it — do not merge into the stub. If you skip the full rewrite, downstream Phase-2 agents detect the stub (`LAYOUT_SIGNATURE_MISSING`) and have to re-extend it themselves, duplicating work.
+
+After writing, self-verify the file contains all of: `import '../styles/global.css'`, every required `components-<pack>.css` import (see Concrete import example below), `<Navigation />`, `<slot />`, `<Footer />`, `<slot name="head" />` inside `<head>`, the `hasSeoTags` prop pattern, and the `Props` interface. Missing any of these means you didn't fully replace the stub — rewrite.
+
+The site shell. Contains:
+
+- `<head>` with meta tags, Google Fonts link for the chosen fonts, favicon, viewport. Do not rely on `/favicon.svg` as the browser-facing href; Wix may intercept that root path. If you create a custom SVG favicon, keep the readable source in `public/favicon.svg` and embed the browser-facing icon as `data:image/svg+xml;base64,...` in `<link rel="icon">` unless the orchestrator gives you a verified site-favicon URL.
+- `import '../styles/global.css'`
+- One `import '../styles/components-<pack>.css'` per pack **that has a `components` agent** (listed in your prompt as "Packs with shared wiring"). Packs without shared wiring (e.g., `cms`) do NOT get an import — no agent writes that file, and importing it breaks the build.
+- `import { ClientRouter } from 'astro:transitions'` and `<ClientRouter />` rendered inside `<head>` — enables Astro View Transitions across the site so category-rail clicks feel like in-place filtering instead of full page loads.
+- `<Navigation />` component
+- `<main><slot /></main>`
+- `<Footer />` component
+- `<slot name="head" />` inside `<head>` for per-page SEO injection
+- `hasSeoTags` prop pattern: when true, skip the default `<title>` and `<meta name="description">` (Phase 2 injects `SeoTags` via the head slot)
+- A top-of-body progress bar (`<div class="nav-progress" data-nav-progress aria-hidden="true"></div>`) that lights up between `astro:before-preparation` and `astro:after-swap` — paired with a small inline `<script>` block (see "View Transitions wiring" below) that drives the bar, syncs the persisted CategoryRail's `aria-current`, and anchors the rail's viewport position across listing-to-listing navigations.
+
+**Concrete import example** for a stores + ecom + cms run — these exact lines MUST appear in frontmatter, in this order:
+```astro
+import '../styles/global.css';
+import '../styles/components-stores.css';
+import '../styles/components-ecom.css';
+```
+
+Missing any `components-<pack>.css` import = every React island that uses scoped contract classes (quantity selectors, variant pills, cart badges, cart line items) renders unstyled in production. Do not ship without all imports.
+
+**Self-check before finishing:** for every pack listed in "Packs with shared wiring", grep your own Layout.astro output for `components-<pack>.css`. If missing, add it. If still unrecoverable, return `status: "partial"` with `errors: [{code: "MISSING_COMPONENT_CSS_IMPORT", pack: "<name>"}]`.
+
+Interface:
+```typescript
+interface Props {
+  title?: string;
+  description?: string;
+  hasSeoTags?: boolean;
+}
+```
+
+##### 2a. View Transitions wiring (mandatory)
+
+The Layout owns the cross-page swap behavior used by the stores pack's category rail and pagination. Without this wiring, every category-pill click is a full page reload and the persisted rail re-renders on every navigation.
+
+Required additions inside `Layout.astro`:
+
+```astro
+---
+import { ClientRouter } from 'astro:transitions';
+// ... other imports
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <!-- ... meta, fonts, css imports ... -->
+    <slot name="head" />
+    <ClientRouter />
+  </head>
+  <body>
+    <div class="nav-progress" data-nav-progress aria-hidden="true"></div>
+    <Navigation />
+    <main><slot /></main>
+    <Footer />
+    <script>
+      // Persisted rail aria-current sync + top loading bar + rail-anchored
+      // scroll across listing-to-listing navigation. Stores pack relies on
+      // all three; do not split into separate scripts.
+      function syncCategoryRail() {
+        const path = window.location.pathname;
+        const activeSlug = path.startsWith("/category/")
+          ? path.slice("/category/".length).replace(/\/$/, "")
+          : path === "/products" || path === "/products/"
+            ? ""
+            : null;
+        if (activeSlug === null) return;
+        const pills = document.querySelectorAll<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        for (const pill of pills) {
+          const slug = pill.dataset.categorySlug ?? "";
+          if (slug === activeSlug) pill.setAttribute("aria-current", "page");
+          else pill.removeAttribute("aria-current");
+        }
+      }
+      // Eager click feedback — flip aria-current before the network call.
+      document.addEventListener("click", (event) => {
+        const target = event.target as HTMLElement | null;
+        const pill = target?.closest<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        if (!pill) return;
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        const pills = document.querySelectorAll<HTMLAnchorElement>(
+          "[data-category-rail] .category-pill",
+        );
+        for (const p of pills) p.removeAttribute("aria-current");
+        pill.setAttribute("aria-current", "page");
+      }, true);
+      const progress = document.querySelector<HTMLElement>("[data-nav-progress]");
+      function startProgress() {
+        if (!progress) return;
+        progress.dataset.state = "loading";
+        document.body.dataset.navigating = "true";
+      }
+      function endProgress() {
+        if (!progress) return;
+        progress.dataset.state = "done";
+        delete document.body.dataset.navigating;
+        window.setTimeout(() => {
+          if (progress.dataset.state === "done") delete progress.dataset.state;
+        }, 320);
+      }
+      // Anchor the persisted rail across listing-to-listing navigation. The
+      // page-header above the rail differs between /products and /category/[slug]
+      // (breadcrumbs, lede, optional image), so naive scroll preservation reads
+      // as a jump. Capture rail.getBoundingClientRect().top before the swap and
+      // re-equalize after.
+      const isListing = (p: string) =>
+        p === "/products" || p === "/products/" || p.startsWith("/category/");
+      let railAnchorTop: number | null = null;
+      document.addEventListener("astro:before-preparation", (event: any) => {
+        const from = window.location.pathname;
+        const to = event?.to?.pathname ?? from;
+        const rail = document.querySelector<HTMLElement>("[data-category-rail]");
+        railAnchorTop =
+          rail && isListing(from) && isListing(to)
+            ? rail.getBoundingClientRect().top
+            : null;
+        startProgress();
+      });
+      document.addEventListener("astro:after-swap", () => {
+        syncCategoryRail();
+        if (railAnchorTop !== null) {
+          const rail = document.querySelector<HTMLElement>("[data-category-rail]");
+          if (rail) {
+            const delta = rail.getBoundingClientRect().top - railAnchorTop;
+            if (Math.abs(delta) > 0.5) {
+              window.scrollBy({ top: delta, left: 0, behavior: "instant" as ScrollBehavior });
+            }
+          }
+        }
+        railAnchorTop = null;
+        endProgress();
+      });
+      document.addEventListener("astro:page-load", endProgress);
+      syncCategoryRail();
+    </script>
+  </body>
+</html>
+```
+
+Mandatory companion CSS (insert into `global.css` — do not split into a separate file):
+
+```css
+/* Disable default ClientRouter root cross-fade. With rail-anchored scroll
+   adjustment, an instant swap reads as "header content changed in place"
+   instead of "whole page faded between two heights". The progress bar +
+   grid-dim handle navigation feedback. */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation: none;
+  mix-blend-mode: normal;
+}
+
+.nav-progress {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 2px;
+  background: var(--color-accent, currentColor);
+  transform: scaleX(0);
+  transform-origin: left;
+  z-index: 1000;
+  pointer-events: none;
+  opacity: 0;
+}
+.nav-progress[data-state="loading"] {
+  opacity: 1;
+  transform: scaleX(0.85);
+  transition: transform 1.6s cubic-bezier(0.2, 0.8, 0.2, 1), opacity 120ms ease;
+}
+.nav-progress[data-state="done"] {
+  opacity: 0;
+  transform: scaleX(1);
+  transition: transform 200ms ease, opacity 240ms ease 60ms;
+}
+
+/* Dim the product grid while ClientRouter fetches/swaps so the click has
+   immediate visual response. */
+body[data-navigating="true"] .product-grid {
+  opacity: 0.55;
+  transition: opacity 140ms ease;
+  pointer-events: none;
+}
+.product-grid {
+  transition: opacity 200ms ease;
+}
+```
+
+The `--color-accent` token is the fallback the bar uses; if the design tokens don't expose `accent`, fall back to a brand-appropriate `--color-*` value or `currentColor`. The bar must be visible against the background — pick something with at least 3:1 contrast against `--color-paper` or whatever the topmost background is.
+
+##### 2b. Navigation submenu CSS (mandatory)
+
+The stores pack's `pages-home-and-nav` scope inserts a Shop submenu (`.site-nav-submenu` containing `.site-nav-sublink` anchors) at the `<!-- nav:links -->` marker in `Navigation.astro`. The submenu must be styled by the designer's `global.css` — vertical packs do NOT write nav CSS. Required classes (only when the stores pack is loaded):
+
+- `.site-nav-item.has-submenu` — relative-positioned wrapper
+- `.site-nav-submenu` — absolutely-positioned dropdown, hidden by default, revealed on hover/focus-within
+- `.site-nav-sublink` — submenu item styling (smaller text, `aria-current="page"` highlight)
+
+Use the same typographic scale and color vocabulary as the rest of the nav. Keyboard-accessible: `:focus-within` on `.site-nav-item.has-submenu` must reveal the submenu.
+
+##### 2c. CategoryRail + pagination CSS (mandatory)
+
+The stores pack ships a shared `CategoryRail` component (`src/components/CategoryRail.astro`) with these classes — designer's `global.css` must style them:
+
+- `.category-rail` — horizontal strip, paper-warm background, bottom rule
+- `.category-rail-inner` — flex-wrap container with token-based gaps and padding-block
+- `.category-pill` — pill button (border, radius, uppercase letter-spacing); `:hover` and `[aria-current="page"]` states
+- `.pagination`, `.pagination-inner`, `.pagination-link` (with `.is-disabled` modifier) — Prev/Next anchors
+- `.breadcrumbs` — used on `/category/[slug]` page header
+
+Style with the published design tokens (`--color-rule`, `--color-paper-warm`, `--color-ink`, `--color-ink-soft`, `--color-taupe` or accent equivalents, `--spacing-md`).
+
+#### 3. `src/components/Navigation.astro`
+
+Top navigation bar. Contains:
+
+- Brand name / logo linking to `/`
+- Navigation links — **must exactly match the `Navigation links:` list in the prompt**. Use the hrefs and labels verbatim. Do NOT coin editorial rebrands (no "Journal" for `/about`, no "Notes" for `/faq`, no "Collection" for `/products`, etc.). Do NOT add links for routes not in the list. One `<a>` per list entry — no duplicates. Never include cart, login, account, or other action pages — those are handled by interactive components in the `nav-actions` slot.
+
+  **Pre-filter context.** The orchestrator pre-filters the `Navigation links:` list to exclude routes from packs that contribute at `<!-- nav:links -->` (today: stores splices a Shop submenu there in Phase 4; gift-cards, when its runtime probe returns active, splices a Gift Cards link). If your prompt's list omits `/products` even though stores is loaded, that's intentional — do NOT "helpfully" add a Products link. Adding it produces duplicate top-level links pointing at the same route once Phase 4's marker patch runs. If your prompt is missing the `Navigation links:` line entirely, return `status: "partial"` with `errors: [{code: "NAV_LINKS_NOT_PROVIDED"}]` rather than guessing — the orchestrator should compute and pass it.
+- Mobile-responsive hamburger menu (CSS-only or minimal inline `<script>`)
+- A `<div class="nav-actions"></div>` slot for Phase 2 to mount interactive components (CartBadge, etc.) — leave it empty, do not place placeholder links or icons there
+- Uses contract classes where applicable (e.g., `cart-badge` class on the mount point)
+- **`transition:persist="site-nav"` on the root `<header>`** — keeps the nav alive across `<ClientRouter />` swaps (instead of re-rendering on every navigation). The directive must be on the root element directly; setting it on the `<Navigation />` mount in Layout doesn't propagate to the rendered root.
+- A `<!-- nav:links -->` marker comment in the link `<ul>` where vertical packs splice their primary nav contributions. Stores splices a Shop link + submenu of categories here in Phase 4.
+
+**Why the verbatim rule:** an editorial brand vibe tempts the designer to coin label rebrands ("Journal" → /about, "Notes" → /faq, "Collection" alongside Shop). Users notice the drift immediately and the duplicates produce broken navigation. Use the labels supplied in `Navigation links:` verbatim.
+
+**CartBadge ownership:** `CartBadge.tsx` is a React island that renders its own `<a href="/cart">` link with cart text and count badge. Do NOT wrap it in another `<a>` tag, do NOT add cart SVG icons or cart links inside `nav-actions`. Browsers break nested `<a>` elements apart, which produces multiple cart icons rendering side by side.
+
+#### 4. `src/components/Footer.astro`
+
+Site footer. Contains:
+
+- Brand name / copyright
+- Navigation links (mirror of header or subset) — same exclusion: no cart, login, or account links
+- Minimal, on-brand styling
+- **`transition:persist="site-footer"` on the root `<footer>`** — same rationale as Navigation: keeps the footer alive across `<ClientRouter />` swaps. Apply to the root element directly, not to `<Footer />` in Layout.
+
+
+---
+
+## Page Designer Scopes (Phase 4 — Step 7, background)
+
+All page scopes share common inputs and rules. Scope-specific details follow.
+
+### Common inputs (from your prompt)
+
+- **Brand context** — name, vibe, aesthetic direction, colors, fonts, mood
+- **Pages to design** — list of routes and their contract class associations
+- **Pack home-section snippet** (home scope only) — section stubs from every loaded pack
+- **Placeholder data instruction** — use plausible brand-contextual placeholder text, prices, images where live data is not yet available
+
+### Common rules for all page scopes
+
+1. **Use contract classes.** Every component that corresponds to a contract key uses that class name. Do not invent replacements.
+2. **Use the Layout.** Every page wraps content in `<Layout>`:
+   ```astro
+   ---
+   import Layout from '../layouts/Layout.astro';
+   ---
+   <Layout title="Page Title">
+     <!-- page content -->
+   </Layout>
+   ```
+3. **Placeholder data, not empty.** Write plausible placeholder text, prices, and image placeholders that match the brand. The designed page must look complete and reviewable on its own.
+4. **No SDK imports in design-only scopes.** The designer's pure design scopes do not import `@wix/stores`, `@wix/data`, `@wix/blog`, or any SDK package. Use hardcoded placeholder arrays/objects that mirror the shape live data will have. (Merged design+wire Phase 4 scopes owned by vertical packs DO import SDKs — this rule applies to designer scopes only.)
+5. **No React islands.** Do not import or mount `.tsx` components. Phase 3 Components writes the islands; Phase 4 Pages mounts them. Page designers write pure `.astro` files.
+6. **Scoped page styles allowed.** Pages may add `<style>` blocks for page-specific ornamental styling (section backgrounds, decorative elements, page-specific spacing adjustments). These are local to the page — do not override contract class rules from `global.css`.
+7. **Image placeholders — decorative slot convention.** Every decorative image (hero, about visual, page-header art) MUST be emitted as a `<div>` placeholder carrying a `data-decorative-slot="<key>"` attribute. **Use ONLY canonical slot keys from this fixed vocabulary:**
+
+    | Key | Where it lives | Required when |
+    |---|---|---|
+    | `hero` | Homepage hero image | Always |
+    | `about` | About-page (or home brand-story) editorial visual | Always |
+    | `productsHeader` | `/products` listing header decorative | Stores pack loaded |
+    | `cmsHeader` | `/about` or `/faq` page header decorative | CMS pack loaded (optional) |
+
+    Do NOT invent keys like `aboutFeature`, `background`, `heroAlt`, etc. The image agent receives this canonical list as its `decorativeSlots` input and generates exactly those keys — invented keys will not have images, and orphan generated images go unused. The vocabulary is intentionally small to keep the slot ↔ image agent contract tight; if a page needs more visual interest, use scoped CSS / SVG / brand-color blocks instead of additional generated images. The orchestrator runs a post-Phase-2 Edit pass (SKILL.md Step 4.6) that injects the actual `<img>` for each slot once Image Phase 1 finishes; your job is to make the slot visible. Rules:
+    - Use aspect-ratio + background-color on the placeholder so the page looks complete even if Image Phase 1 never completes.
+    - Keep decorative overlays (stamps, rules, frames) as siblings of the slot `<div>` — the orchestrator injects the `<img>` as the FIRST child of the slot, so anything you want to layer over it must stay outside the slot `<div>` (or inside with explicit z-index).
+    - Do NOT conditionally read `.wix/image-urls.md` — the file won't exist at designer-time because Image Phase 1 runs in parallel with you. The slot mechanism is the replacement for the old "read the file if it exists" branch and must not coexist with it.
+    - Do not use external placeholder services (picsum, unsplash, etc.).
+
+    Example:
+    ```astro
+    <section class="hero-section relative">
+      <div
+        class="hero-image"
+        data-decorative-slot="hero"
+        style="aspect-ratio: 4/5; background-color: var(--color-bark);"
+      >
+        <!-- orchestrator injects <img src={decorativeImages.hero} …> here -->
+      </div>
+      <div class="hero-stamp">{/* decorative overlay, stays outside the slot */}</div>
+    </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.
+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`** — these files are owned by Phase 3 Components agents. Writing to them causes double-write conflicts when Phase 3 also writes the same file.
+
+### Scope: `home`
+
+Composes the home page from every loaded pack's `homeSection` snippet plus brand-specific hero and CTA sections.
+
+**Inputs (additional):**
+- `Pack home-section snippets` — one per loaded pack. Each names a section (e.g., "Featured products", "Brand story", "Latest posts", "Contact CTA") with a description and contract classes.
+
+**Structure:**
+1. **Hero section** — full-width, impactful brand moment. Uses `hero-section` contract class. Emit a `data-decorative-slot="hero"` placeholder per Common rule #7 — do not inline an Image Phase 1 URL, even if `.wix/image-urls.md` happens to exist; the orchestrator injects the `<img>` after Image Phase 1 completes.
+2. **Pack sections** — one section per loaded pack's `homeSection`, in a sensible order (typically: featured content first, then story, then CTA).
+3. **Optional closing CTA** — if no pack contributes a CTA section, add a minimal brand-appropriate closing.
+
+**Files:** `src/pages/index.astro`
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-home",
+  "scope": "home",
+  "data": {
+    "pagesDesigned": ["src/pages/index.astro"],
+    "contractClassesHonored": ["hero-section", "product-grid", "product-card", "brand-story", ...]
+  },
+  "files": ["src/pages/index.astro"]
+}
+```
+
+### Scope: `static`
+
+About and FAQ pages — content pages with similar layout demands.
+
+**Files:** `src/pages/about.astro`, `src/pages/faq.astro`
+
+**About page:**
+- Hero/header section with `about-hero` class
+- Body content with `about-body` class
+- Placeholder brand story text (2-3 paragraphs, brand-contextual)
+- Image placeholder for brand/team visual
+
+**FAQ page:**
+- Section wrapper with `faq-section` class
+- Individual Q&A items with `faq-item`, `faq-question`, `faq-answer` classes
+- 4-6 placeholder FAQ items contextual to the business type
+- Accordion or expandable pattern (CSS-only, using `<details>`/`<summary>` or checkbox hack)
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-static",
+  "scope": "static",
+  "data": {
+    "pagesDesigned": ["about", "faq"],
+    "contractClassesHonored": ["about-hero", "about-body", "faq-section", "faq-item", "faq-question", "faq-answer"]
+  },
+  "files": ["src/pages/about.astro", "src/pages/faq.astro"]
+}
+```
+
+### Scope: `store-pages`
+
+All store-facing pages designed together for visual coherence.
+
+**Files:** `src/pages/products/index.astro`, `src/pages/products/[slug].astro`, `src/components/ProductCard.astro`, `src/pages/cart.astro`, `src/pages/thank-you.astro`
+
+**Products listing (`/products`):**
+- Page heading
+- Product grid using `product-grid` class
+- 3-6 placeholder product cards using `ProductCard` component
+
+**Product detail (`/products/[slug]`):**
+- Product image (large, placeholder)
+- Product info section with `product-detail` class
+- Purchase area with `product-purchase` class — placeholder price, placeholder variant selector, Add to Cart button with `add-to-cart-btn` class
+- Product description area
+
+**ProductCard component:**
+- Accepts a single `product` prop (object with name, price, slug, image fields)
+- Uses `product-card` class
+- Image, name, price, link to `/products/${product.slug}`
+- **Important:** Phase 2 `product-pages` rewrites this to accept the full Wix product object. Design with a simple prop interface: `{ product: { name: string; slug: string; price: number; image?: string } }`
+
+**Cart (`/cart`):**
+- Two-column grid layout: `.cart-grid` — items column left, order summary right. Stacks vertically on mobile
+- Items column with `.cart-items`, `.cart-item`, `.cart-item.unavailable` (reduced opacity), `.cart-item-image`, `.cart-item-info`, `.cart-item-name`, `.cart-item-option`, `.cart-item-modifiers` classes
+- Quantity selector with `.cart-item-qty`, `.qty-btn`, `.qty-value` classes — include `:disabled` states (reduced opacity + `cursor: not-allowed`)
+- Price display with `.cart-item-actions`, `.cart-item-prices`, `.cart-item-full-price` (strikethrough for discounts), `.cart-item-unit-price`, `.cart-item-line-total` classes
+- Remove button with `.cart-item-remove` class (muted color, underline on hover)
+- Summary column with `.cart-summary` (sticky on desktop), `.cart-subtotal`, `.checkout-btn` (with `:disabled` state), `.cart-empty` classes
+- Unavailable item warning with `.cart-item-unavailable` class (red text)
+- Empty state with `.cart-empty` class (centered, muted text + "Browse Products" link)
+- **All cart CSS must be in `<style is:global>`** — `CartView` is a React island; scoped Astro styles do not reach its children
+- Placeholder cart items (2-3)
+
+**Thank you (`/thank-you`):**
+- Confirmation message with `order-summary` class
+- Placeholder order details
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-store-pages",
+  "scope": "store-pages",
+  "data": {
+    "pagesDesigned": ["products/index.astro", "products/[slug].astro", "ProductCard.astro", "cart.astro", "thank-you.astro"],
+    "contractClassesHonored": <count>
+  },
+  "files": [
+    "src/pages/products/index.astro",
+    "src/pages/products/[slug].astro",
+    "src/components/ProductCard.astro",
+    "src/pages/cart.astro",
+    "src/pages/thank-you.astro"
+  ]
+}
+```
+
+### Scope: `blog-pages`
+
+Blog feed listing and post detail designed together.
+
+**Files:** `src/pages/blog/index.astro`, `src/pages/blog/[slug].astro`
+
+**Blog listing (`/blog`):**
+- Page heading
+- Post grid/list using `blog-feed` class
+- 3 placeholder post cards using `blog-post-card` class (title, date, excerpt, cover image placeholder)
+
+**Blog post detail (`/blog/[slug]`):**
+- Post header with title, date, author, cover image placeholder
+- Body area with `blog-post` and `blog-post-body` classes
+- Meta section with `blog-post-meta` class (tags, share links)
+- Good reading typography (max-width prose container, comfortable line height)
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-blog-pages",
+  "scope": "blog-pages",
+  "data": {
+    "pagesDesigned": ["blog/index.astro", "blog/[slug].astro"],
+    "contractClassesHonored": ["blog-feed", "blog-post-card", "blog-post", "blog-post-body", "blog-post-meta"]
+  },
+  "files": ["src/pages/blog/index.astro", "src/pages/blog/[slug].astro"]
+}
+```
+
+### Scope: `contact-page`
+
+Contact page with form placeholder.
+
+**Files:** `src/pages/contact.astro`
+
+**Contact page:**
+- Page heading and descriptive text
+- Contact CTA section using `contact-cta` class (if on home, this mirrors the home CTA's visual language)
+- Form placeholder area — a styled `<div>` where Phase 2 mounts the `ContactForm.tsx` island. Use a placeholder form layout (name, email, message fields, submit button) so the page looks complete, but Phase 2 replaces this with the real React island.
+- Optional: map embed placeholder, business hours, address (if brand context suggests it)
+
+**Return:**
+```json
+{
+  "status": "complete",
+  "phase": "designer-contact-page",
+  "scope": "contact-page",
+  "data": {
+    "pagesDesigned": ["contact.astro"],
+    "contractClassesHonored": ["contact-cta"]
+  },
+  "files": ["src/pages/contact.astro"]
+}
+```
+
+---
+
+## Return Contract
+
+At the end of your work, emit a structured JSON block per `../shared/RETURN_CONTRACT.md`. Do **not** write sidecar files to `.wix/logs/*`.
+
+The JSON block MUST be the **last** content in your message — the parent parses it as the last fenced JSON. No trailing prose after the closing ` ``` `.
+
+## Anti-Patterns (apply to all scopes)
+
+| WRONG | CORRECT |
+|-------|---------|
+| Import `@wix/stores`, `@wix/data`, or any SDK package | Page designers are visual-only — SDK imports belong to Phase 4 vertical-pack scopes |
+| Import or mount `.tsx` React islands | Phase 3 Components writes islands; Phase 4 Pages mounts them |
+| 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 `references/shared/STYLING.md` for the three categories |
+| Override `global.css` rules from page `<style>` blocks | Pages can add co-located styles for one-off decoration; never override designer-owned global classes |
+| HTML `<!-- comment -->` in `.astro` frontmatter | Use `//` or `/* */` — frontmatter is TypeScript |
+| Use external placeholder image services (picsum, unsplash) | Use colored `<div>` placeholders or `.wix/image-urls.md` URLs |
+| Write `components-<pack>.css` (Phase 2 or page scope) | Phase 3 Components creates that file — Phase 2 imports it in Layout; page scopes must not write it |
+| Write CSS for scoped contract keys (Phase 2 scope) | Only global keys get CSS in `global.css`; scoped keys → Phase 3 Components |
+| Skip publishing tokens — "downstream agents will add what they need" | Token completeness IS the contract; missing tokens force downstream agents to invent classes (the failure mode this protocol prevents) |
+| Use default Tailwind colors (`bg-blue-500`, `text-gray-200`) | Use brand `@theme` tokens (`bg-bark`, `text-cream`) — defaults expose that it's AI-generated |
+| Generic unstyled HTML | Brand-first design — every element reflects the aesthetic direction |
+| Fixed-width layouts | Responsive: mobile-first, breakpoints at 320/768/1024px |
+| `ls src/`, `Glob src/**` to discover files | Your prompt lists every file and class contract. Write directly. |
+| Use `<img src="https://...">` for product/content images | Placeholder `<div>` with aspect-ratio; Phase 4 wires real images |
+| Omit `data-decorative-slot` on hero/about/background placeholders | Every decorative image placeholder MUST carry a slot attribute — the orchestrator's Step 4.6 patch depends on it (see common rule #7) |
+| Read `.wix/image-urls.md` during design-system scope | File doesn't exist yet — emit `data-decorative-slot` placeholders instead; the orchestrator injects the URLs after Image Phase 1 returns |
+| ProductCard with flat props (`name`, `price`, `slug` as separate props) | Single `product` object prop: `{ product }` — Phase 4 passes the full Wix product object |
+| Wrap CartBadge in `<a>` or add cart SVG icons in `nav-actions` | Leave `nav-actions` empty — CartBadge renders its own `<a>` link; nesting `<a>` tags produces duplicate icons |
+
+## Coordination with other agents
+
+| Agent | Relationship | Rule |
+|-------|-------------|------|
+| Phase 3 Components (stores/blog/forms) | Writes React islands referencing contract classes | Phase 2 Design System writes global CSS; Phase 3 Components writes scoped CSS. No overlap. |
+| Phase 4 Pages (vertical packs) | Reads your `.astro` files, swaps placeholders for live data (where the designer wrote placeholder-only scopes) | They preserve your layout and styling; they only change data-fetching code and island mounts |
+| Image agent (Image Phase 1) | Writes `.wix/image-urls.md` with decorative image URLs | Designers do NOT read this file. Emit `data-decorative-slot="<key>"` placeholders; the orchestrator's Step 4.6 Edit pass injects the `<img>` once Image Phase 1 finishes. |
+| Image agent (Image Phase 2) | PATCHes entity images onto products/posts via MCP | No direct interaction — images flow through product/post records that Phase 4 queries |
+
+## File ownership
+
+Designer scopes own the **visual structure** of their files. Phase 4 scopes (vertical packs) own the **data wiring** of the same files where that split applies. When Phase 4 rewrites a file, it preserves the designer's markup structure and class usage, replacing only placeholder data sections with SDK queries and island mounts.
+
+This means two agents touch the same file across phases (designer's page scope writes it, Phase 4 vertical-pack scope rewrites it). This is by design — Phase 4 dispatches in Step 7 after the designer's page scopes complete, so there's no race condition.