@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-theming/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sfnext-theming
+description: >-
+  Re-brand and re-skin a Storefront Next storefront: change the color palette, corner radius and shadows (shape tokens), header and footer colors, typography and web fonts, logo, favicon, hero scrims, and brand copy, with WCAG contrast checks. Use when asked to rebrand or restyle the storefront, change the primary color, swap the font, make the header dark, make cards rounded or flat, replace the logo, edit src/theme, core.css, header.css, brand.css, tailwind.css, base.css, or src/lib/fonts.ts, or verify a theme change in the Design System Storybook stories. Do not use for building or styling an individual component (use `storefront-next:sfnext-components`), Figma kit sync (use `storefront-next-figma:sfnext-create-figma-kit`), or site configuration (use `storefront-next:sfnext-configuration`).
+---
+
+# Theming a Storefront Next Storefront
+
+Your storefront has exactly one theme, in `src/theme/`, and it is yours to edit. Rebranding is mostly value changes in a few CSS files; components pick the new look up through token classes. Choose a starting look with `sfnext create-storefront --vertical <id>` (a starter theme) and then customize it as below.
+
+## Where things live
+
+| Concern | File |
+|---|---|
+| Entry point and Tailwind `@source` scoping | `src/theme/index.css` (imports `shared.css`, which sets import order) |
+| Palette: background, foreground, primary, secondary, accent, muted, border, ring, destructive/success/warning/info | `src/theme/tokens/core.css` |
+| Shape: `--ui-radius`, `--ui-shadow`, `--ui-border-width` | `src/theme/tokens/core.css` |
+| Header, menu, footer, newsletter band, `--header-logo-filter` | `src/theme/tokens/header.css` |
+| Status and feedback colors | `src/theme/tokens/status.css` |
+| Swatches, sidebar, agentic UI, payment and cart extras, focus helpers | `tokens/swatch.css`, `sidebar.css`, `agentic.css`, `components.css`, `custom.css` |
+| `--brand-*` color primitives and hero scrims (`--hero-overlay-*`, `--hero-scrim`) | `src/theme/tokens/brand.css` |
+| Font stacks `--font-sans/-serif/-mono`; token-to-utility bridge | `src/theme/tailwind.css` (`@theme inline`) |
+| `@font-face`, base layer, `.section-container`, section-scoped shape rules | `src/theme/base.css` |
+| Component-level CSS (navigation, cart sheet, toasts, store locator) | `src/theme/overrides/*.css` |
+| Font binding and preload | `public/fonts/*.woff2`, `src/lib/fonts.ts` (used by `src/root.tsx`) |
+| Logo, favicon, hero and payment images | `public/images/`, `public/favicon.ico` |
+| Site name and brand strings | `src/locales/<locale>/translations.json` (`common.defaultSiteName`) |
+
+Palette values are not all derived from `brand.css`: `core.css` sets `--primary` and friends directly, so change them there. Token-to-class wiring and the full token file list are covered in `storefront-next:sfnext-components` (token system reference).
+
+## Workflow
+
+### 1. Read the current theme
+
+Open `src/theme/index.css`, `tokens/core.css`, `tokens/header.css`, and `tailwind.css` before editing. Keep variable names; change values.
+
+### 2. Palette
+
+Edit `:root` in `tokens/core.css`: `--primary`/`--primary-foreground`, `--background`/`--foreground`, `--secondary`, `--accent`, `--muted`, borders, `--ring`. Comments in the file record WCAG contrast ratios for the current values; recompute for yours. Minimums: 4.5:1 for text (`--primary` on `--primary-foreground`, `--foreground` on `--background`, each status color on its `-foreground`), 3:1 for borders and focus rings against the surface.
+
+Update `tokens/status.css` if semantic colors clash with the new palette, and `tokens/swatch.css`, `tokens/components.css` where defaults look off.
+
+### 3. Header, footer, and newsletter chrome
+
+`tokens/header.css` is deliberately decoupled from `--primary`, so changing the primary color does not recolor the header. Set `--header-background`/`--header-foreground`, menu hover/active colors, and `--footer-*` yourself. The logo is an image: for a dark header with a dark logo, set `--header-logo-filter` (for example `brightness(0) invert(1)` turns a black logo white; `none` leaves it alone). `--newsletter-background` defaults to `var(--primary)`.
+
+### 4. Shape
+
+Set `--ui-radius`, `--ui-shadow`, `--ui-border-width` in `core.css` to re-skin every shadcn primitive at once. Flat and square: `0`, `none`, `0`. Soft and raised: `var(--radius-xl)`, a light shadow, `0`. Do not edit primitives or add `rounded-*`/`shadow-*` classes, and never write `--radius-ui` / `--shadow-ui` (compile-time bridges, silent no-op). Scoped overrides, section rules, and the Card border exception are covered in `storefront-next:sfnext-components` (shape tokens reference). If your default border width is 0, the section rules at the bottom of `base.css` re-enable 1px Card borders on account, auth, and checkout pages; adjust those to taste.
+
+### 5. Typography
+
+Four touch points, all must agree:
+
+1. Put the variable `.woff2` in `public/fonts/`.
+2. `src/lib/fonts.ts`: `import font from '/fonts/<file>.woff2'; export const primaryFont = font;` (`root.tsx` preloads it).
+3. `@font-face` in `src/theme/base.css` (same URL, weight range, `font-display: swap`).
+4. `--font-sans` / `--font-serif` / `--font-mono` in `src/theme/tailwind.css`, with a fallback stack of similar metrics.
+
+Self-host fonts (WOFF2, preloaded, no third-party CDN). Remove the old font file if unused.
+
+### 6. Assets and copy
+
+- Logo: replace `public/images/logo.svg` (the `Logo` component in `src/components/logo` renders it; you can replace that component for an inline-SVG logo).
+- Favicon: `public/favicon.ico`.
+- Hero and promo images: `public/images/` (and the Page Designer content that references them).
+- Brand name: `common.defaultSiteName` in each `src/locales/<locale>/translations.json` you ship (used in page titles).
+- Hero text scrims: `--brand-black`/`--brand-white` in `brand.css` feed `--hero-overlay-dark/-light` and `--hero-scrim`; update them with the brand so hero text stays legible.
+
+### 7. Dark mode
+
+The shipped theme has one palette and no `.dark` token block. Do not promise dark mode; it would be new work (a `.dark` scope for every token file).
+
+### 8. Verify
+
+```bash
+pnpm dev                                   # look at home, PLP, PDP, cart, checkout, account
+pnpm storybook                             # Design System/Theme/Colors, Typography, Radius, Shadows
+pnpm lint                                  # color-linter flags hard-coded colors
+pnpm typecheck
+pnpm storybook:test --type=snapshot        # add --update only after reviewing intended changes
+pnpm storybook:test --type=a11y            # contrast and ARIA via axe-core
+```
+
+The `Design System/Theme/*` stories (`src/design-system/stories/`) render the live tokens and are the quickest visual check.
+
+## Guardrails
+
+- Change values in token files; do not sprinkle hex codes or `bg-[#...]` in components.
+- Need a new token? Define it in a `tokens/*.css` file and bridge it in `@theme inline` in `tailwind.css` (see TOKEN-SYSTEM).
+- Component-level CSS goes in `src/theme/overrides/*.css` (import it from `shared.css`) or `base.css`; prefer `[data-slot="..."]` selectors over utility-class selectors.
+
+## Design handoff
+
+If your designers work in Figma, keep the Figma variables and code tokens aligned with `storefront-next-figma:sfnext-create-figma-kit` (requires the Figma MCP server). Change the tokens in code first, then sync the kit.
+
+## Related Skills
+
+- `storefront-next:sfnext-components` - Build and style components with token classes and shape tokens
+- `storefront-next:sfnext-accessibility` - Contrast, focus, and accessibility scans
+- `storefront-next:sfnext-i18n` - Locale files that hold brand copy
+- `storefront-next:sfnext-performance` - Font and image loading guidance
+- `storefront-next:sfnext-page-designer` - Content and hero components authored in Page Designer
+- `storefront-next-figma:sfnext-create-figma-kit` - Sync the Figma design kit with your tokens

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-theming/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Re-skin my Storefront Next storefront: change the primary color to a deep green, swap the font to Inter, and make the header dark.", "should_trigger": true},
+  {"query": "Make the cards and buttons rounded with a soft shadow across the whole site. Where do I change that?", "should_trigger": true},
+  {"query": "Create a new ProductBadge component with CVA variants and a Storybook story that passes the snapshot tests.", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-theming/references/REBRAND-CHECKLIST.md

@@ -0,0 +1,29 @@
+# Rebrand Checklist
+
+Work top to bottom; each item names the file to touch.
+
+- [ ] `src/theme/tokens/core.css`: `--primary`, `--primary-foreground`, `--background`, `--foreground`, `--secondary`, `--accent`, `--muted`, `--border`, `--input`, `--ring`
+- [ ] `src/theme/tokens/core.css`: contrast re-checked (text 4.5:1, borders and focus rings 3:1); update the ratio comments
+- [ ] `src/theme/tokens/core.css`: `--ui-radius`, `--ui-shadow`, `--ui-border-width`
+- [ ] `src/theme/base.css`: section-scoped Card border rules still match the chosen border width
+- [ ] `src/theme/tokens/header.css`: header, menu, footer, newsletter colors; `--header-logo-filter`
+- [ ] `src/theme/tokens/status.css`: status colors still readable against the new surfaces
+- [ ] `src/theme/tokens/brand.css`: `--brand-*` primitives and hero scrims
+- [ ] `src/theme/tokens/swatch.css`, `components.css`: swatch and badge defaults
+- [ ] Font: `public/fonts/`, `src/lib/fonts.ts`, `@font-face` in `src/theme/base.css`, `--font-*` in `src/theme/tailwind.css`
+- [ ] `public/images/logo.svg`, `public/favicon.ico`, hero images
+- [ ] `common.defaultSiteName` in `src/locales/*/translations.json`
+- [ ] Page Designer content referencing old imagery or colors
+- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm storybook:test --type=snapshot`, `--type=a11y`
+- [ ] Visual pass: home, PLP, PDP, cart, checkout, account, error pages
+
+## Common mistakes
+
+| Mistake | Result |
+|---|---|
+| Editing only `brand.css` | Little changes; the palette is in `core.css` |
+| Writing `--radius-ui` or `--shadow-ui` | Silent no-op; use `--ui-radius` / `--ui-shadow` |
+| Changing the font file but not `base.css` `@font-face` | Old font still loads or fallback shows |
+| Forgetting `--header-logo-filter` after a header color change | Logo unreadable |
+| Hard-coding hex in components | `pnpm lint` fails (`custom/color-linter`) and the theme no longer controls it |
+| Changing `--primary` and expecting the header to follow | Header tokens are independent; edit `header.css` |

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/SKILL.md

@@ -7,7 +7,7 @@ description: Build or sync a Storefront Next vertical's Figma design kit — dup
 
 This skill is the entrypoint for setting up or syncing the **Figma design kit** for a Storefront Next vertical, so the kit stays aligned with the brand tokens defined in code.
 
-It is the design-kit companion to `sfnext-create-vertical` (in the `storefront-next` plugin): create or change the brand tokens in code first, then run this skill to mirror them in Figma.
+It is the design-kit companion to `sfnext-theming` (in the `storefront-next` plugin): create or change the brand tokens in code first, then run this skill to mirror them in Figma.
 
 ## Step 0 — Verify prerequisites (required)
 
@@ -121,8 +121,8 @@ All three must pass with zero errors and zero warnings.
 
 ## Related Skills
 
-- `storefront-next:sfnext-create-vertical` - Define the brand tokens in code (run this first)
-- `storefront-next:sfnext-create-component` - Author the React component a Code Connect mapping points to
+- `storefront-next:sfnext-theming` - Define the brand tokens in code (run this first)
+- `storefront-next:sfnext-components` - Author the React component a Code Connect mapping points to
 
 ## Reference Documentation
 

package/oclif.manifest.json

@@ -81,7 +81,7 @@
           "type": "option"
         },
         "config": {
-          "description": "Path to config file (in dw.json format; defaults to ./dw.json)",
+          "description": "Path to config file (in dw.json format; defaults to ./dw.json; empty for none)",
           "env": "SFCC_CONFIG",
           "helpGroup": "GLOBAL",
           "name": "config",
@@ -99,6 +99,15 @@
           "multiple": false,
           "type": "option"
         },
+        "dotenv-file": {
+          "description": "Path to .env file used instead of ./.env (empty for none)",
+          "env": "SFCC_DOTENV_FILE",
+          "helpGroup": "GLOBAL",
+          "name": "dotenv-file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "project-directory": {
           "aliases": [
             "working-directory"
@@ -326,7 +335,7 @@
           "type": "option"
         },
         "mrt-backend": {
-          "description": "MRT backend: auto (prefer SCAPI MRT when configured, else legacy), legacy, or scapi",
+          "description": "MRT backend: legacy (default), auto (prefer SCAPI MRT when configured, else legacy), or scapi",
           "env": "MRT_BACKEND",
           "name": "mrt-backend",
           "hasDynamicHelp": false,
@@ -458,12 +467,20 @@
           "type": "option"
         },
         "docs-topics": {
-          "description": "Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, ocapi, tooling, help-admin, help-merchant, help-kb. Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.",
+          "description": "Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, commerce-solutions, ocapi, tooling, help-admin, help-merchant, help-kb. Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.",
           "env": "SFCC_DOCS_TOPICS",
           "name": "docs-topics",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "scapi-schemas": {
+          "description": "Local SCAPI OpenAPI contracts for scapi_search and scapi_execute (comma-separated JSON files or directories). Each replaces the bundled or live contract with the same family/name/version from servers[0].url, or adds an API. Developer option for beta and pre-release APIs.",
+          "env": "SFCC_SCAPI_SCHEMAS",
+          "name": "scapi-schemas",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -476,5 +493,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "3.2.1"
+  "version": "3.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,8 +80,8 @@
     "ts-morph": "27.0.2",
     "yaml": "2.9.0",
     "zod": "4.5.4",
-    "@salesforce/b2c-agent-plugins": "1.10.3",
-    "@salesforce/b2c-tooling-sdk": "2.3.0"
+    "@salesforce/b2c-agent-plugins": "1.11.0",
+    "@salesforce/b2c-tooling-sdk": "2.4.0"
   },
   "bundledDependencies": [
     "@modelcontextprotocol/server",

package/content/guidance/storefront-next/sfnext-create-component/SKILL.md

@@ -1,195 +0,0 @@
----
-name: sfnext-create-component
-description: Author a new Storefront Next design-system component the right way — pick the correct layer (primitive vs composite), reuse-or-extend before creating, define CVA variants bound to semantic tokens, add data-slot attributes, satisfy the accessibility checklist, and ship a Storybook story. Use when asked to create, add, or build a new UI component, button/badge/tile/card variant, or design-system primitive. This is the design-system authoring discipline; for createPage/Suspense/shadcn page-rendering patterns see sfnext-components.
----
-
-# Create a Component Skill
-
-This skill is the authoring discipline for adding a new component to a Storefront Next storefront: choosing the right layer, reusing before creating, and meeting the token / a11y / Storybook requirements that keep the design system consistent.
-
-> **It complements `sfnext-components`.** That skill covers engineering patterns — `createPage`, Suspense/`Await` streaming, shadcn/ui setup, the `cn()` utility. **This** skill covers design-system authoring — the layer model, the extend-before-create gate, CVA variants bound to semantic tokens, `data-slot`, accessibility, and story coverage. Use both together when building UI.
-
-## Before you start — scan first (extend before create)
-
-Do not create a new component file until you have run this scan:
-
-1. Search `src/components/` for components with a similar name or behaviour.
-2. Search `src/components/ui/` for Shadcn primitives — run `npx shadcn@latest add <name>` to check whether it exists before hand-rolling one.
-3. Apply the REUSE / EXTEND / CREATE decision:
-   - **REUSE** — an existing component already does this → use it as-is.
-   - **EXTEND** — an existing component is close → add a new CVA variant (cheaper than a new file).
-   - **CREATE** — nothing exists → proceed with this skill.
-
-See [Component Authoring Reference](references/COMPONENT-AUTHORING.md) for the full layer model and the extend-before-create rule.
-
-## Step 1 — Decide the layer
-
-| Question | Layer | Location |
-|----------|-------|----------|
-| Pure UI element, no data or business logic? | **Primitive** | `src/components/ui/` (check shadcn first) |
-| Assembles primitives or takes data props? | **Composite** | `src/components/` |
-
-For primitives, always check shadcn before hand-rolling:
-
-```bash
-# from packages/template-retail-rsc-app
-npx shadcn@latest add <component-name>
-```
-
-Shadcn components land in `src/components/ui/` already wired to the token system. If it exists in shadcn, use it — do not hand-roll a replacement.
-
-## Step 2 — Create the file with the copyright header
-
-```
-src/components/<feature>/<component-name>.tsx    ← preferred (feature-grouped)
-src/components/<component-name>.tsx              ← acceptable for standalone components
-```
-
-Start every `.ts`/`.tsx` file with the Apache 2.0 copyright header (ESLint enforces it), then imports:
-
-```tsx
-import * as React from 'react'
-import { cva, type VariantProps } from 'class-variance-authority'
-import { cn } from '@/lib/utils'
-// Import primitives from src/components/ui/ — not from @radix-ui directly
-import { Button } from '@/components/ui/button'
-```
-
-## Step 3 — Type the props explicitly
-
-```tsx
-interface ProductTileProps {
-  productId: string
-  name: string
-  price: number
-  imageUrl: string
-  currency?: string
-  className?: string
-}
-```
-
-No `any`. Extend `React.ComponentProps<'element'>` for native passthrough. Use discriminated unions for mutually exclusive prop shapes.
-
-## Step 4 — Define CVA variants (if the component has visual states)
-
-```tsx
-const productTileVariants = cva(
-  'relative flex flex-col overflow-hidden rounded-md bg-card text-card-foreground',
-  {
-    variants: {
-      density: {
-        comfortable: 'gap-4 p-4',
-        compact: 'gap-2 p-2',
-      },
-    },
-    defaultVariants: { density: 'comfortable' },
-  }
-)
-```
-
-**Token rules:** every class that affects color MUST use a semantic token utility (`bg-primary`, `text-foreground`, `border-border`, …). No raw hex, no `bg-black`, no `text-gray-500`. See [Token System Reference](references/TOKEN-SYSTEM.md).
-
-## Step 5 — Write the component
-
-```tsx
-export function ProductTile({
-  productId,
-  name,
-  price,
-  imageUrl,
-  currency = 'USD',
-  className,
-  density,
-  ...props
-}: ProductTileProps & VariantProps<typeof productTileVariants>) {
-  return (
-    <article
-      data-slot="product-tile"
-      data-product-id={productId}
-      className={cn(productTileVariants({ density }), className)}
-      {...props}
-    >
-      <div data-slot="product-tile-image">{/* image */}</div>
-      <div data-slot="product-tile-body" className="flex flex-col gap-1">
-        <span data-slot="product-tile-name" className="text-sm font-medium text-foreground">
-          {name}
-        </span>
-        <span data-slot="product-tile-price" className="text-sm text-muted-foreground">
-          {new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(price)}
-        </span>
-      </div>
-    </article>
-  )
-}
-```
-
-Required on every component:
-- `data-slot` on the root and each named region.
-- `className` accepted and merged via `cn()` **last** so callers can override.
-- Native props spread via `{...props}`.
-
-## Step 6 — Create the Storybook story
-
-Every new component in `src/components/` needs a `.stories.tsx` — one story per CVA variant plus a `Snapshot` story for CI diffing.
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react'
-import { ProductTile } from './product-tile'
-
-const meta: Meta<typeof ProductTile> = {
-  title: 'Components/Product/ProductTile',
-  component: ProductTile,
-}
-export default meta
-
-type Story = StoryObj<typeof ProductTile>
-
-const defaultProps = { productId: 'P001', name: 'Classic Shirt', price: 89.99, imageUrl: '/placeholder.jpg' }
-
-export const Default: Story = { args: defaultProps }
-export const Compact: Story = { args: { ...defaultProps, density: 'compact' } }
-
-export const Snapshot: Story = {
-  name: 'Snapshot',
-  render: () => (
-    <div className="grid grid-cols-2 gap-4">
-      <ProductTile {...defaultProps} density="comfortable" />
-      <ProductTile {...defaultProps} density="compact" />
-    </div>
-  ),
-}
-```
-
-## Step 7 — Accessibility check
-
-- [ ] Interactive elements are `<button>` or `<a>`, never `<div onClick>`.
-- [ ] All form inputs have `<Label htmlFor>`.
-- [ ] Focus ring: `focus-visible:ring-ring focus-visible:ring-[3px]`.
-- [ ] No color-only information (pair with icon or text).
-- [ ] `aria-label` on icon-only buttons.
-
-## Verification
-
-Before marking the task complete, run from the monorepo root:
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm test-storybook:snapshot:agent
-```
-
-All three must pass with zero errors and zero warnings. Lint runs with `--max-warnings 0`.
-
-## Related Skills
-
-- `storefront-next:sfnext-components` - createPage HOC, Suspense/Await, shadcn/ui, Tailwind page-rendering patterns
-- `storefront-next:sfnext-testing` - Vitest unit tests and Storybook interaction/a11y tests
-- `storefront-next:sfnext-create-vertical` - Brand theming via the token layer
-- `storefront-next:sfnext-extensions` - Injecting a component into a page via UITarget
-
-## Reference Documentation
-
-- [Component Authoring Reference](references/COMPONENT-AUTHORING.md) - Layer model, CVA, data-slot, extend-before-create
-- [Token System Reference](references/TOKEN-SYSTEM.md) - Semantic token classes and dark mode rules
-- [Project Structure Reference](references/PROJECT-STRUCTURE.md) - Where components live in the monorepo
-- [Troubleshooting Reference](references/TROUBLESHOOTING.md) - Token, lint, and snapshot pitfalls

package/content/guidance/storefront-next/sfnext-create-component/references/COMPONENT-AUTHORING.md

@@ -1,206 +0,0 @@
-# Component authoring standards
-
-## Vertical extensions — existing components always have priority
-
-When building a vertical extension (`src/extensions/<vertical>/`), check what the **base template already renders** before creating anything new.
-
-**The rule**: if a base component already renders equivalent content at the same location, do NOT create an extension component that duplicates it. Extensions add what is missing — they never recreate what already exists.
-
-### Decision gate (run this before creating any extension component)
-
-1. **Find the base component** — read the relevant route and trace what components it renders.
-2. **Check every rendered section** — does the base already render this content (description, accordion, badge, banner, etc.)?
-3. **If yes** — use a UITarget slot on the existing content, or customise it via token/variant. Do not create a parallel extension component that renders the same thing.
-4. **If no** — the extension is justified. Register it at the correct UITarget.
-
-### Concrete examples
-
-```
-❌ WRONG — base ProductView already renders a description accordion ("Overview").
-           ProductDetailsExtension adds its own "Overview" section → duplicate.
-
-✅ CORRECT — base already renders description + adapter sections (Specifications, Care Instructions…).
-             ProductDetailsExtension only adds the two sections the base does NOT have:
-             Shipping & Returns, Warranty Info.
-```
-
-```
-❌ WRONG — base renders product title in ProductInfo.
-           The vertical extension renders product title again in a brand stamp.
-
-✅ CORRECT — brand stamp adds ONLY the brand line ("<BRAND> · <tagline>")
-             above the existing ProductInfo, not the title.
-```
-
-**Do not create duplicates unless the user explicitly asks for them.**
-The cost of a duplicate is paid on every page load, in every test, in every Figma sync. The correct
-approach is almost always a UITarget slot or a CSS token override.
-
----
-
-## Extend before create — mandatory check before any new component
-
-Before writing a single line of a new component, answer these questions in order:
-
-1. **Does an existing component already do this?** Search `src/components/` and `src/components/ui/` by name and by behaviour.
-2. **Can an existing component cover this with a new CVA variant?** A new `variant` or `size` value is always cheaper than a new file.
-3. **Can composition cover this?** Wrap an existing component in a thin composite rather than duplicating it.
-4. **Only if all three answers are no** — create a new component.
-
-```tsx
-// ❌ WRONG — creating BrandPrimaryButton when Button already exists
-export function BrandPrimaryButton({ children }: Props) {
-  return <button className="bg-[#1e6f3a] text-white ...">{children}</button>
-}
-
-// ✅ CORRECT — new CVA variant on the existing Button primitive
-// In src/components/ui/button.tsx, add to buttonVariants:
-brand: 'bg-primary text-primary-foreground hover:bg-primary/90',
-
-// ✅ CORRECT — thin composite when behaviour differs
-export function AddToCartButton(props: AddToCartButtonProps) {
-  return <Button variant="default" {...props}>Add to Cart</Button>
-}
-```
-
----
-
-## Multi-vertical extension governance
-
-When a vertical needs to extend a component, choose the right maintenance model upfront:
-
-```
-Does the change only affect visual tokens (color, font, spacing)?
-  └─ YES → CVA variant on the existing component. Token system handles most of this via brand.css.
-  └─ NO  → Is this structural change needed by only one vertical?
-              └─ YES → src/extensions/<vertical-name>/ via UITarget injection. Never touch core.
-              └─ NO  → Will another vertical need the same structural pattern?
-                          └─ YES → Add a slot/renderProp to the BASE component.
-                                   Each vertical provides its own implementation of that slot.
-                          └─ UNSURE → Build vertical-specific first (extensions/).
-                                      Promote to base when a second vertical needs the same pattern.
-```
-
-**Never add vertical-specific logic (if brandA / if brandB) to a shared component.** If you find yourself writing that, the slot/render-prop pattern is missing from the base component.
-
----
-
-## Layer model — know which layer you are in before writing a line
-
-| Layer | Where | What lives here |
-|-------|-------|----------------|
-| **Primitive** | `src/components/ui/` | Shadcn-sourced, Radix-backed primitives. Pure rendering, no business logic, no SCAPI. |
-| **Composite** | `src/components/` | Assembled from primitives. May accept loaders/data props. No direct SCAPI calls. |
-| **Page / Route** | `src/routes/` | Loader, action, error boundary, page layout. Fetches data, passes to composites. |
-| **Extension** | `src/extensions/<name>/` | Opt-in additions via UITarget. Self-contained. Never modify core from inside an extension. |
-
-Do not skip layers. A page component should not build raw `<button>` elements. A primitive should not call `useFetcher`.
-
----
-
-## Primitives (`src/components/ui/`)
-
-These files come from Shadcn and must be treated as infrastructure, not business components.
-
-**When extending a primitive:**
-- Do not edit the primitive file directly (it may be refreshed from Shadcn upstream).
-- Create a wrapper component in `src/components/` instead.
-- Re-export from the wrapper so imports stay consistent.
-
-**Allowed changes to primitive files:**
-- Adding a new CVA variant that maps to an existing semantic token — that's it.
-
----
-
-## CVA — class-variance-authority
-
-All styled components with more than one visual state use CVA.
-
-```tsx
-import { cva, type VariantProps } from 'class-variance-authority'
-import { cn } from '@/lib/utils'
-
-const badgeVariants = cva(
-  'inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors',
-  {
-    variants: {
-      variant: {
-        default: 'border-transparent bg-primary text-primary-foreground',
-        secondary: 'border-transparent bg-secondary text-secondary-foreground',
-        destructive: 'border-transparent bg-destructive text-white',
-        outline: 'text-foreground',
-      },
-    },
-    defaultVariants: { variant: 'default' },
-  }
-)
-```
-
-Rules:
-- Every variant value must use semantic token classes only. No raw hex.
-- `cn()` from `@/lib/utils` is always the last call — enables external className overrides.
-- Export the `*Variants` function alongside the component so it can be reused in related components.
-
----
-
-## data-slot attributes
-
-Every presentational element in a component tree must carry a `data-slot` attribute for testing and Figma tracing.
-
-```tsx
-// ✅
-<div data-slot="product-tile">
-  <div data-slot="product-tile-image">…</div>
-  <div data-slot="product-tile-body">…</div>
-</div>
-```
-
-The slot name should be kebab-case and match the component name.
-
----
-
-## TypeScript requirements
-
-- All props are explicitly typed. No `any`.
-- Use `React.ComponentProps<'element'>` to extend native element props.
-- Discriminated unions for components with mutually exclusive prop shapes.
-- `asChild` pattern (via Radix `Slot`) for polymorphic rendering — never accept an `as` prop.
-
----
-
-## Copyright header
-
-Every `.ts` / `.tsx` file must begin with the Apache 2.0 header. ESLint enforces this.
-
----
-
-## Naming conventions
-
-| Thing | Convention | Example |
-|-------|-----------|---------|
-| Component files | kebab-case | `product-tile.tsx` |
-| Component exports | PascalCase | `ProductTile` |
-| Variant objects (CVA) | camelCase + "Variants" suffix | `productTileVariants` |
-| data-slot values | kebab-case matching component | `product-tile` |
-| Hook files | kebab-case prefixed with "use-" | `use-cart.ts` |
-
----
-
-## Storybook requirement
-
-Every new component in `src/components/` must have a `.stories.tsx` file.
-- One story per CVA variant.
-- Default export: `{ title: 'Components/ComponentName', component: ComponentName }`.
-- Include a snapshot story (`name: 'Snapshot'`) so CI can diff it.
-
----
-
-## Accessibility checklist
-
-Before marking a component complete, verify:
-
-- [ ] Interactive elements are native `<button>` or `<a>`, not `<div onClick>`.
-- [ ] All inputs have an associated `<Label>` using `htmlFor` (or Radix `Label` with `asChild`).
-- [ ] Focus ring uses `focus-visible:ring-ring focus-visible:ring-[3px]` — matches the button primitive.
-- [ ] Color information is not communicated by color alone (pair with icon or text).
-- [ ] Motion: wrap animations in `prefers-reduced-motion` if not handled by Tailwind's `motion-safe:` prefix.