@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/content/guidance/storefront-next/sfnext-configuration/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: sfnext-configuration
+description: Manage Storefront Next application configuration using config.server.ts, schema types, environment variables, and multi-site setup. Use when editing config.server.ts, adding PUBLIC__ environment variables, using useConfig or getConfig, or configuring multiple sites. NOT for initial project creation — see sfnext-project-setup.
+---
+
+# Configuration Skill
+
+This skill covers the Storefront Next configuration system — centralized in `config.server.ts` with environment variable overrides.
+
+## Overview
+
+All configuration is centralized in `config.server.ts` with typed defaults. Environment variables (via `.env` files or MRT settings) override these defaults. The system provides type-safe access with automatic parsing and validation.
+
+## Adding Configuration
+
+### 1. Define the type in `src/types/config.ts`
+
+```typescript
+export type Config = {
+  app: {
+    myFeature: {
+      enabled: boolean;
+      maxItems: number;
+    };
+  };
+};
+```
+
+### 2. Set defaults in `config.server.ts`
+
+```typescript
+export default defineConfig({
+  app: {
+    myFeature: {
+      enabled: false,
+      maxItems: 10,
+    },
+  },
+});
+```
+
+### 3. Override via environment variables
+
+```bash
+PUBLIC__app__myFeature__enabled=true
+PUBLIC__app__myFeature__maxItems=20
+```
+
+## Accessing Configuration
+
+### In React Components
+
+```typescript
+import { useConfig } from '@salesforce/storefront-next-runtime/config';
+
+export function MyComponent() {
+  const config = useConfig();
+
+  if (config.myFeature.enabled) {
+    const maxItems = config.myFeature.maxItems;
+    // Feature code
+  }
+}
+```
+
+### In Server Loaders/Actions
+
+```typescript
+import { getConfig } from '@salesforce/storefront-next-runtime/config';
+
+export function loader({context}: LoaderFunctionArgs) {
+  const config = getConfig(context); // context is required on server
+
+  if (config.myFeature.enabled) {
+    // Loader code
+  }
+}
+```
+
+### In Browser Code (Non-Route Modules)
+
+```typescript
+import { getConfig } from '@salesforce/storefront-next-runtime/config';
+
+export function getFeatureFlag() {
+  const config = getConfig(); // No context needed in browser (uses window.__APP_CONFIG__)
+  return config.myFeature.enabled;
+}
+```
+
+**Note:** `getConfig()` and `useConfig()` return `AppConfig` — the `app` section of the full config. Access properties directly (e.g., `config.myFeature.enabled`) without the `app` prefix.
+
+## Environment Variable Rules
+
+```bash
+# Pattern: PUBLIC__app__{path}__{to}__{property}=value
+PUBLIC__app__commerce__api__clientId=abc123
+# Maps to config.app.commerce.api.clientId
+# Accessed as config.commerce.api.clientId
+```
+
+| Rule              | Detail                                         |
+| ----------------- | ---------------------------------------------- |
+| `PUBLIC__` prefix | Exposed to browser (client-safe)               |
+| No prefix         | Server-only (secrets)                          |
+| `__` separator    | Navigate nested paths                          |
+| Auto-parsing      | Numbers, booleans, JSON parsed automatically   |
+| Validation        | Paths must exist in `config.server.ts`         |
+| Depth limit       | Maximum 10 levels                              |
+| MRT limits        | Names max 512 chars; total `PUBLIC__` max 32KB |
+
+## Multi-Site Configuration
+
+```bash
+PUBLIC__app__commerce__sites='[
+  {
+    "id": "RefArchGlobal",
+    "defaultLocale": "en-US",
+    "defaultCurrency": "USD",
+    "supportedLocales": [
+      {"id": "en-US", "preferredCurrency": "USD"},
+      {"id": "de-DE", "preferredCurrency": "EUR"}
+    ],
+    "supportedCurrencies": ["USD", "EUR"]
+  }
+]'
+```
+
+```typescript
+const config = getConfig(context);
+const currentSite = config.commerce.sites[0];
+const locale = currentSite.defaultLocale; // "en-US"
+const currency = currentSite.defaultCurrency; // "USD"
+```
+
+## Security
+
+```bash
+# Client-safe (PUBLIC__ prefix)
+PUBLIC__app__commerce__api__clientId=abc123
+
+# Server-only (no prefix — never sent to client)
+COMMERCE_API_SLAS_SECRET=your-secret
+```
+
+Read server-only secrets directly from `process.env` — never add them to the config system.
+
+## Common Pitfalls
+
+| Pitfall           | Problem                                    | Solution                                           |
+| ----------------- | ------------------------------------------ | -------------------------------------------------- |
+| Missing `context` | `getConfig()` returns undefined in loaders | Use `getConfig(context)` on server                 |
+| Typo in env var   | Variable silently ignored                  | Validation catches paths not in `config.server.ts` |
+| Exposing secrets  | Sensitive data in browser                  | Use no-prefix variables; access via `process.env`  |
+
+## Related Skills
+
+- `storefront-next:sfnext-project-setup` - Initial environment setup and `.env` configuration
+- `storefront-next:sfnext-data-fetching` - Using config in loader functions
+- `storefront-next:sfnext-deployment` - MRT environment variable configuration

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

@@ -0,0 +1,195 @@
+---
+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

@@ -0,0 +1,206 @@
+# 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.

package/content/guidance/storefront-next/sfnext-create-component/references/PROJECT-STRUCTURE.md

@@ -0,0 +1,43 @@
+# Project Structure Reference
+
+Storefront Next is a pnpm monorepo with a React Router v7 retail application.
+
+## Key architecture
+
+- **Monorepo:** pnpm workspaces, packages under `packages/`
+- **Main app:** `packages/template-retail-rsc-app/` — React Router v7 retail application
+- **Build tool:** Vite with SSR
+- **Routing:** React Router v7 file-based routing
+- **Styling:** Tailwind CSS v4, utility-first, token-driven
+- **Commerce:** Salesforce Commerce Cloud (SCAPI) integration
+
+## Theme file layout (the vertical surface)
+
+```
+src/theme/
+├── tailwind.css            # CSS variable → Tailwind utility bridge
+└── tokens/
+    ├── brand.css           # ← the ONLY file that changes per vertical
+    ├── core.css            # semantic roles (bg, fg, card, primary, …)
+    ├── header.css          # header / footer surfaces
+    ├── status.css          # destructive / warning / success / info
+    ├── swatch.css          # variant-selector swatch UI
+    └── components.css       # payment + cart-specific tokens
+```
+
+## App file organization
+
+- **Routes:** `src/routes/` (file-based, mapped in `src/routes.ts`)
+- **Components (composite):** `src/components/`
+- **Components (Shadcn primitives):** `src/components/ui/`
+- **Extensions:** `src/extensions/<name>/`
+- **Providers:** `src/providers/`
+- **Config / fixtures:** `src/config/`
+
+## Common commands
+
+- `pnpm dev` — start the dev server
+- `pnpm build` — production build
+- `pnpm typecheck` — TypeScript checking
+- `pnpm lint` — ESLint (runs with `--max-warnings 0`)
+- `pnpm test-storybook:snapshot:agent` — Storybook snapshot diff