@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-create-component/evals/trigger-evals.json

@@ -0,0 +1,12 @@
+[
+  {"query": "I need to build a new ProductTile component for our Storefront Next storefront. It should have comfortable and compact density variants and follow the design-system rules — semantic tokens, data-slot attributes, and a Storybook story.", "should_trigger": true},
+  {"query": "Add a new badge component with primary, secondary, and destructive variants using CVA. How do I make sure the variant classes use semantic tokens and not raw colors?", "should_trigger": true},
+  {"query": "I want to create a reusable card component in the design system. Which layer does it belong in, primitive or composite, and what accessibility checks must it pass before I'm done?", "should_trigger": true},
+  {"query": "Before I build a new button, how do I check whether I should reuse an existing one, add a CVA variant, or create a brand-new component?", "should_trigger": true},
+  {"query": "Build a new swatch-group UI element with proper data-slot attributes, a focus ring, and one Storybook story per variant.", "should_trigger": true},
+  {"query": "How do I wire up a route loader that streams product data into my page using Suspense and Await?", "should_trigger": false},
+  {"query": "I need to create a new brand vertical with its own color palette and dark header. Where do the brand tokens live?", "should_trigger": false},
+  {"query": "How do I register a Page Designer component in the component registry and add its meta definition?", "should_trigger": false},
+  {"query": "Set up authentication middleware with the split-cookie SLAS architecture for my storefront.", "should_trigger": false},
+  {"query": "How do I add an extension that injects a promo banner at the header.before.nav target point?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-create-component/references/TOKEN-SYSTEM.md

@@ -0,0 +1,130 @@
+# Token System Reference
+
+## The one rule that overrides everything else
+
+**Never use a raw hex value, RGB value, or hardcoded color in any component or CSS file.**
+Always use a semantic Tailwind utility that maps to a CSS variable. The variables are defined in
+`src/theme/tokens/` and bridged to Tailwind utilities in `src/theme/tailwind.css`.
+
+```tsx
+// ✅ correct
+<div className="bg-primary text-primary-foreground" />
+
+// ❌ wrong — breaks dark mode, breaks vertical theming, breaks Figma sync
+<div style={{ background: '#000000', color: '#ffffff' }} />
+<div className="bg-black text-white" />
+```
+
+## Token files and what they own
+
+| File | Owns |
+|------|------|
+| `src/theme/tokens/core.css` | Background, foreground, card, popover, primary, secondary, muted, accent, border, input, ring, separator, rating, charts, sidebar, focus helpers |
+| `src/theme/tokens/brand.css` | Brand palette (`--brand-black`, `--brand-white`, `--brand-gray-*`, `--brand-primary`). **This is the only file that changes per vertical.** |
+| `src/theme/tokens/header.css` | Header background/foreground, header menu surfaces, footer. Dark header = black bg / white text. |
+| `src/theme/tokens/status.css` | Destructive, warning, success, info, status-positive/warning/critical, active-bg |
+| `src/theme/tokens/swatch.css` | Swatch color, labeled, pill — variant selector UI only |
+| `src/theme/tokens/components.css` | Payment provider colors, cart-specific tokens |
+
+## Semantic token meanings — use the right one
+
+### Text colors
+| Token class | When to use |
+|-------------|-------------|
+| `text-foreground` | Default body text, headings |
+| `text-muted-foreground` | Secondary labels, helper text, placeholder, metadata |
+| `text-primary-foreground` | Text on a `bg-primary` surface (e.g. button label) |
+| `text-secondary-foreground` | Text on a `bg-secondary` surface |
+| `text-accent-foreground` | Text on a `bg-accent` surface (hover chips, tags) |
+| `text-destructive` | Error text, destructive action labels |
+| `text-card-foreground` | Text inside card surfaces |
+
+### Background colors
+| Token class | When to use |
+|-------------|-------------|
+| `bg-background` | Page/app background |
+| `bg-primary` | CTAs, filled buttons, strong actions |
+| `bg-secondary` | Secondary button fill, subtle section bg |
+| `bg-muted` | Skeleton, disabled surfaces, subtle fills |
+| `bg-accent` | Hover state, selected chip, tag bg |
+| `bg-card` | Card and tile surfaces |
+| `bg-popover` | Dropdown, tooltip, modal backgrounds |
+
+### Borders
+| Token class | When to use |
+|-------------|-------------|
+| `border-border` | Standard dividers, list separators — uses alpha so it renders correctly on ANY surface color |
+| `border-border-subtle` | Form inputs, card edges — slightly more visible |
+| `border-input` | Input field border specifically |
+| `ring-ring` | Focus ring on interactive elements |
+
+**Never use `border-black`, `border-gray-*`, or `divide-gray-*`.** Use `border-border` or `border-border-subtle`.
+
+### Header/navigation surfaces
+| Token class | When to use |
+|-------------|-------------|
+| `bg-[--header-background]` | Header band background |
+| `text-[--header-foreground]` | Header text and icons |
+| `bg-[--header-menu-background]` | Mega/dropdown menu panel |
+| `bg-[--footer-background]` | Footer background |
+
+### Status and feedback
+| Token class | When to use |
+|-------------|-------------|
+| `text-destructive` / `bg-destructive` | Delete, remove, error state |
+| `bg-warning-bg` / `text-warning-foreground` | Caution messages |
+| `text-status-positive` | In-stock, success indicator |
+| `text-status-critical` | Out of stock, error badge |
+| `bg-active-bg` / `text-active-foreground` | Active/authorized badge |
+
+## Dark mode rules
+
+**Do not write `dark:bg-black` or any dark: hardcoded color.**
+Dark mode is fully handled by `.dark` overrides in `src/theme/tokens/core.css` and other token files.
+Using semantic classes automatically gets the correct dark value.
+
+```tsx
+// ✅ correct — dark mode is automatic
+<div className="bg-card text-card-foreground" />
+
+// ❌ wrong
+<div className="bg-white dark:bg-gray-900 text-black dark:text-white" />
+```
+
+The only valid `dark:` usage is for classes that reference another semantic token:
+
+```tsx
+// ✅ valid dark: override pattern
+className="dark:bg-input/30 dark:border-input"
+```
+
+## What changes per vertical — and what does not
+
+### Changes (vertical-specific, lives in `src/theme/tokens/brand.css`)
+- Brand palette values (`--brand-black`, `--brand-primary`, `--brand-gray-*`)
+- Logo treatment (`--header-logo-filter`)
+- Brand-specific component tokens
+
+### Does NOT change (shared, lives in core/header/status/swatch/components)
+- Semantic token names and their Tailwind utility names
+- Dark mode pairing rules
+- Component variant logic (CVA)
+- Border alpha values
+- Status and feedback colors
+
+**Never override core.css, header.css, status.css, swatch.css, or components.css to create a vertical.**
+Only `brand.css` changes between verticals.
+
+## Tailwind utility bridge
+
+All token → Tailwind utility mappings are defined in `src/theme/tailwind.css`.
+If a CSS variable exists in a token file but has no Tailwind utility in `tailwind.css`, add it there
+before using it in a component. Do not use arbitrary `[--variable-name]` syntax for variables that
+should be in the bridge.
+
+```css
+/* src/theme/tailwind.css — add new token bridge entries here */
+--color-my-new-token: var(--my-new-token);
+```
+
+Then use `bg-my-new-token` in components.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-create-component/references/TROUBLESHOOTING.md

@@ -0,0 +1,34 @@
+# Troubleshooting Reference
+
+## Token not found in Tailwind utilities
+If a CSS variable exists in a token file but has no Tailwind utility in `tailwind.css`:
+- Open `src/theme/tailwind.css`.
+- Add a bridge entry: `--color-my-new-token: var(--my-new-token);`.
+- Then use `bg-my-new-token` in components — never the `bg-[--my-new-token]` arbitrary syntax.
+
+## Colors look wrong in dark mode
+- You probably hardcoded a color (`bg-white`, `text-black`, raw hex) instead of using a semantic token.
+- Replace with the semantic utility (`bg-background`, `text-foreground`, etc.). Dark mode is handled by `.dark` overrides in the token files automatically.
+
+## Vertical changes leak into other verticals
+- You edited a shared token file (`core.css`, `header.css`, `status.css`, `swatch.css`, `components.css`). Move the change into `brand.css`.
+- Or you added `if (vertical)` logic to a shared component. Replace it with a CVA variant, a slot/render-prop on the base, or an extension.
+
+## Component already exists
+If a scan finds an existing component that covers the need:
+- Add a new CVA variant instead of creating a new component.
+- Wrap in a thin composite if behaviour differs.
+- Never duplicate.
+
+## Local pages won't render without SCAPI
+- Use fixtures: create `src/config/<vertical>-fixtures.ts` and short-circuit the `_app.tsx` and `_app.product.$productId.tsx` loaders during vertical development.
+- Restore the real SCAPI calls once credentials are available.
+
+## Linter errors after changes
+Run `pnpm lint:fix` first. If errors remain, check:
+- Missing copyright header (required on every `.ts`/`.tsx` file).
+- Raw hex value or hardcoded Tailwind color — replace with a semantic token class.
+- Missing `data-slot` attribute on a component root.
+
+## Snapshot tests fail after visual changes
+Run `pnpm test-storybook:snapshot:agent -- --updateSnapshot` to update baselines after intentional visual changes.