@salesforce/b2c-dx-mcp 3.2.0 → 3.3.0

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

@@ -1,191 +1,153 @@
 ---
 name: sfnext-components
-description: Build UI components in Storefront Next using createPage HOC, Suspense/Await patterns, shadcn/ui, and Tailwind CSS v4. Use when creating page components, adding Suspense boundaries, integrating shadcn/ui, styling with Tailwind, or organizing component files. Covers server vs client rendering patterns and the cn() utility.
+description: >-
+  Build and modify UI components in a Storefront Next storefront: page components with Suspense and use()/Await, createPage and withSuspense, Tailwind v4 token classes, shape tokens (rounded-ui, shadow-ui, border-ui), shadcn/ui primitives in src/components/ui (sync-shadcn), CVA variants, data-slot, DynamicImage, lazy-loaded overlays, and Storybook stories with snapshot tests. Use when creating or editing a component in src/components, adding a shadcn primitive, fixing styling that ignores the theme, writing a *.stories.tsx file, or running pnpm storybook:test. Do not use for re-branding colors, fonts, or logos (use `storefront-next:sfnext-theming`), route loaders (use `storefront-next:sfnext-data-fetching`), or Page Designer registration (use `storefront-next:sfnext-page-designer`).
 ---
 
-# Components Skill
+# Storefront Next Components
 
-This skill covers component development patterns in Storefront Next — createPage HOC, Suspense boundaries, shadcn/ui integration, and Tailwind CSS styling.
+How to write, style, and verify components in your storefront. Your project already ships the rules in `AGENTS.md`, `docs/README-UI-STYLING.md`, `docs/README-SHAPE-TOKENS.md`, `docs/README-SUSPENSE.md`, and `docs/README-STORYBOOK.md`; this skill is the task-oriented path through them.
 
-## Page Component Pattern
+## Before you create anything
 
-Most routes export a default function component that receives `loaderData` as props:
+1. Search `src/components/` for an existing component (`ls src/components`). Extend or compose it before adding a new one.
+2. Decide the layer:
+   - **Primitive** (Button, Card, Dialog): a shadcn fork in `src/components/ui/`. Only shadcn forks live there.
+   - **Composite / domain component**: everything else, in `src/components/<kebab-name>/`.
+   - **Optional feature**: a folder under `src/extensions/` (see `storefront-next:sfnext-extensions`).
+3. Match the folder shape already used by neighbors:
 
-```typescript
-import { Suspense } from 'react';
-import { Await } from 'react-router';
-import { SeoMeta } from '@/components/seo-meta';
+```
+src/components/my-widget/
+├── index.tsx                   # implementation (default or named export)
+├── index.test.tsx              # Vitest + Testing Library
+└── stories/
+    ├── index.stories.tsx       # Storybook (stories/ subfolder is required)
+    ├── my-widget-snapshot.tsx  # optional snapshot fixture
+    └── __snapshots__/          # generated baselines, commit them
+```
 
-type ProductPageData = {
-    product: Promise<Product>;
-    reviews: Promise<Reviews>;
-};
+Every `.ts`/`.tsx` file needs the Apache header enforced by the `custom/header-format` lint rule. Copy it from any existing file (or `AGENTS.md`).
 
-export default function ProductPage({ loaderData }: { loaderData: ProductPageData }) {
-    return (
-        <>
-            <SeoMeta title="Product" />
-            <Suspense fallback={<ProductHeaderSkeleton />}>
-                <Await resolve={loaderData.product}>
-                    {(product) => <ProductHeader product={product} />}
-                </Await>
-            </Suspense>
-            <Suspense fallback={<ReviewsSkeleton />}>
-                <Await resolve={loaderData.reviews}>
-                    {(reviews) => <ProductReviews reviews={reviews} />}
-                </Await>
-            </Suspense>
-        </>
-    );
-}
-```
+## Styling rules
 
-### createPage HOC (Optional)
+- Tailwind utility classes only; merge with `cn()` from `@/lib/utils`. No CSS modules, no per-component CSS files, no `style={{}}` (a truly dynamic API-driven value is the only exception).
+- Global/theme CSS lives in `src/theme/` only (entry `src/theme/index.css`). There is no `src/app.css`.
+- Use semantic token classes, never hard-coded colors. The `custom/color-linter` rule fails `pnpm lint` on raw palette classes such as `text-white` or `bg-red-500`; use `text-primary-foreground`, `text-destructive-foreground`, `bg-card`, `text-muted-foreground`, `border-border`.
+- Header/footer chrome has its own classes: `bg-header-background`, `text-header-foreground`, `bg-header-menu-background`, `bg-footer-background`. Do not write `bg-[--header-background]`.
+- A new token needs two edits: the value in `src/theme/tokens/*.css` and a `--color-x: var(--x)` line inside `@theme inline` in `src/theme/tailwind.css`. See [TOKEN-SYSTEM.md](references/TOKEN-SYSTEM.md).
+- The shipped theme defines one (light) palette; there is no `.dark` token block. Do not promise dark mode in component work.
+- Breakpoints are mobile-first (`sm`, `md`, `lg`, `xl`, `2xl`).
 
-For pages needing standardized Suspense wrappers and page key management:
+### Shape tokens (read before touching Card, Button, Input, Dialog)
 
-```typescript
-import { createPage } from '@/components/create-page';
+Radius, shadow, and card border width come from three variables in `src/theme/tokens/core.css`: `--ui-radius`, `--ui-shadow`, `--ui-border-width`, consumed through `rounded-ui`, `shadow-ui`, `border-ui`.
 
-export default createPage({
-    component: ProductView,
-    fallback: <ProductSkeleton />,
-});
-```
+- Never add `rounded-xl`, `rounded-none`, `shadow-md`, `shadow-none`, or `border-0` to a primitive or a Card to force a shape. Change the token, or scope it: `<Card className="[--ui-radius:var(--radius-xl)]">`.
+- Always write the source names (`--ui-radius`). Writing the bridge names `--radius-ui` / `--shadow-ui` is a silent no-op.
+- `border-ui` is Card-only. To show a Card border use `[--ui-border-width:1px]`, not `border`.
 
-## Suspense Boundaries and Code Splitting
+Full mechanism and scoped-override recipes: [SHAPE-TOKENS.md](references/SHAPE-TOKENS.md).
 
-Use `<Suspense>` + `<Await>` for streaming loader data, and `lazy()` for code-splitting heavy components:
+## Page components and Suspense
 
-```typescript
-import { lazy, Suspense } from 'react';
+Route components receive `loaderData` with deferred fields as unresolved promises. Rules from `AGENTS.md`: one `<Suspense>` per async operation, stable promise identity (never `Promise.all`/`.then` in render; compose in the loader), skeletons where layout is known.
 
-// Code-split a heavy component
-const CustomerReviewsSection = lazy(() =>
-    import('@/components/customer-reviews-section/customer-reviews-section')
-);
+```tsx
+import { Suspense, use } from 'react';
+import { Await } from 'react-router';
 
-export default function ProductPage({ loaderData }: { loaderData: ProductPageData }) {
+function Reviews({ promise }: { promise: Promise<ReviewsData> }) {
+    const reviews = use(promise);
+    return <ReviewList reviews={reviews} />;
+}
+
+export default function ProductPage({ loaderData }: { loaderData: PageData }) {
     return (
         <>
-            {/* Stream loader data */}
-            <Suspense fallback={<ProductHeaderSkeleton />}>
-                <Await resolve={loaderData.product}>
-                    {(product) => <ProductHeader product={product} />}
-                </Await>
+            {/* use() needs a small child component */}
+            <Suspense fallback={<ReviewsSkeleton />}>
+                <Reviews promise={loaderData.reviews} />
             </Suspense>
 
-            {/* Code-split component */}
-            <Suspense fallback={<ReviewsSkeleton />}>
-                <CustomerReviewsSection productId={loaderData.productId} />
+            {/* Await resolves inline and supports a local errorElement */}
+            <Suspense fallback={<RecsSkeleton />}>
+                <Await resolve={loaderData.recommendations}>{(recs) => <Recommendations items={recs} />}</Await>
             </Suspense>
         </>
     );
 }
 ```
 
-## shadcn/ui Components
+`createPage` (`@/components/create-page`) wraps a component with the standard Suspense fallback and keys the page so navigations remount it:
 
-shadcn/ui provides pre-built accessible components. Add them via CLI:
+```tsx
+import { createPage } from '@/components/create-page';
 
-```bash
-npx shadcn@latest add button
-npx shadcn@latest add card
-npx shadcn@latest add dialog
+export default createPage({
+    component: CategoryView,
+    fallback: <CategorySkeleton />,            // optional; default is a generic skeleton
+    getPageKey: (data) => data?.categoryId,    // optional; default is pathname+search+hash
+});
 ```
 
-**Rules:**
-
-- Add components via CLI only (do not manually create files in `src/components/ui/`)
-- `src/components/ui/` components are copied into your project and can be customized directly
-- Keep app/domain components outside `src/components/ui/`:
-
-```typescript
-// Optional wrapper for app-specific styling
-import { Button } from '@/components/ui/button';
-
-export function PrimaryButton(props: React.ComponentProps<typeof Button>) {
-    return <Button {...props} className={cn('rounded-full', props.className)} />;
-}
-```
+`withSuspense` (`@/components/with-suspense`) is the lower-level HOC for a single async child. Details: `docs/README-SUSPENSE.md`.
 
-## Tailwind CSS Styling
+## Links, navigation, text
 
-Tailwind CSS v4 is the only permitted styling approach:
+- Import `Link`/`NavLink` from `@/components/link` and `useNavigate` from `@/hooks/use-navigate`, never from `react-router`. The wrappers add the site/locale URL prefix; the originals silently drop it. Combine with `href()` for typed params.
+- Strings go through `react-i18next` (`useTranslation`) and prices through `formatCurrency` in `@/lib/currency`. Do not hard-code `'en-US'` or `$`. See `storefront-next:sfnext-i18n`.
 
-```typescript
-import { cn } from '@/lib/utils';
+## Images
 
-export function ProductCard({ featured }: { featured?: boolean }) {
-    return (
-        <div className={cn(
-            'rounded-lg border border-border bg-card p-4',
-            featured && 'ring-2 ring-primary'
-        )}>
-            <h2 className="text-lg font-semibold text-card-foreground">
-                Product Name
-            </h2>
-        </div>
-    );
-}
-```
+Use `<DynamicImage>` (`@/components/dynamic-image`) with `widths` (and `heights` for cropping) for product and content images; add `priority="high"` to the LCP image. Behavior is configured under the `images` key of `config.server.ts` (`quality`, `formats`, `fallbackFormat`, `host`, `enableDis`, `realmHostMappings`); see `docs/README-IMAGES.md`. Wrap grids in `DynamicImageProvider` (`@/providers/dynamic-image`) instead of prop-drilling sizes.
 
-**Rules:**
+## Overlays
 
-- Use Tailwind utility classes as the primary styling approach
-- Use `cn()` for conditional class merging
-- Follow mobile-first responsive design (`md:`, `lg:` breakpoints)
-- Prefer Tailwind over inline styles; inline styles are acceptable for truly dynamic values (e.g., `backgroundColor` from API data)
-- No CSS modules or separate CSS files
-- Custom global CSS only in `src/app.css`
+Modals, drawers, and dialogs hidden on first render must be `React.lazy()` and mounted only after first interaction, gated on `open` with `useDeferredUnmount` from `@/hooks/use-deferred-unmount`. Do not keep a sticky "loaded" latch. Pattern: `docs/README-PERFORMANCE.md` ("Lazy Loading for Overlays").
 
-### Dark Mode
+## shadcn primitives
 
-Theme variables automatically adapt via CSS variables:
+`src/components/ui/` files are forks of shadcn/ui that you own and may edit in place (shape tokens, `data-slot`, extra props). Do not put non-shadcn components there, and do not hand-copy from the shadcn docs. Use the in-project `sync-shadcn` skill (`.claude/skills/sync-shadcn/`):
 
-```typescript
-<div className="bg-background text-foreground border-border">
-    <button className="bg-primary text-primary-foreground">Click me</button>
-</div>
+```bash
+S=.claude/skills/sync-shadcn/sync.mjs
+node $S add slider             # fetch from shadcn, apply shape tokens + import convention, seed baseline
+node $S restyle --all --check  # gate: exit 1 if any fork has drifted off the shape-token rules
+node $S restyle src/components/ui/toggle.tsx   # normalize one file
 ```
 
-### Responsive Design
+Prefer `add` over `npx shadcn@latest add`: `npx` pulls the older `new-york` registry style and leaves raw `rounded-md`/`shadow-sm` classes you then have to restyle. To pull upstream fixes into an existing fork, use `status` / `sync <name>` / `diff <name>` / `advance <name>` (a 3-way merge that keeps your edits); these need a merge baseline in `.shadcn-baseline/`, which `add` and `sync <name> --bootstrap` create. Read `.claude/skills/sync-shadcn/SKILL.md` for conflict handling. If it mentions a path that does not exist in your project, use the `ui` directory configured in `components.json`.
 
-```typescript
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-    {products.map(p => <ProductCard key={p.id} product={p} />)}
-</div>
-```
+## Stories and verification
 
-## File Organization
+Each reusable component needs `stories/*.stories.tsx` using `@storybook/react-vite` and a title from the fixed taxonomy (`Products/Product Tile/Product Tile`). `src/components/ui/` is excluded from story coverage. Details and the snapshot fixture pattern: [STORYBOOK.md](references/STORYBOOK.md).
 
+```bash
+pnpm typecheck
+pnpm lint                                  # oxlint (color-linter, header, a11y rules) + biome format check
+pnpm test                                  # Vitest
+pnpm storybook:test --type=snapshot        # add --update only for intended DOM changes
+pnpm storybook:test --type=a11y            # axe-core; new stories must pass
 ```
-src/components/product-tile/
-├── index.tsx              # Component implementation
-├── index.test.tsx         # Vitest unit tests
-└── stories/
-    ├── index.stories.tsx  # Storybook stories
-    └── __snapshots__/     # Storybook snapshots (optional)
 
-src/components/product-skeleton/
-├── index.tsx              # Skeleton component (separate from main)
-├── index.test.tsx
-└── stories/
-    └── index.stories.tsx
-```
+Interaction and a11y runs need Chromium once (`pnpm exec playwright install chromium`).
 
-## Best Practices
+## More detail
 
-1. **Export default function components** — Receive `loaderData` as props
-2. **Granular Suspense boundaries** — Show content progressively as data resolves
-3. **Use `lazy()` for heavy components** — Code-split below-the-fold or conditional UI
-4. **Reusable skeleton components** — Consistent loading states
-5. **Colocate tests and stories** — Keep test files next to source files
-6. **TypeScript interfaces** — Define proper types for all props
+- [COMPONENT-AUTHORING.md](references/COMPONENT-AUTHORING.md): worked example, CVA variants, accessibility checklist, CSS component classes vs React components, mask icons
+- [TOKEN-SYSTEM.md](references/TOKEN-SYSTEM.md): token files, bridge, class names
+- [SHAPE-TOKENS.md](references/SHAPE-TOKENS.md): shape token mechanism and traps
+- [STORYBOOK.md](references/STORYBOOK.md): story layout, titles, snapshots
+- [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md): symptom to fix
 
 ## Related Skills
 
-- `storefront-next:sfnext-data-fetching` - Loader patterns that feed data to components
-- `storefront-next:sfnext-testing` - Writing Vitest tests and Storybook stories
-- `storefront-next:sfnext-page-designer` - Page Designer component integration
+- `storefront-next:sfnext-theming` - Change palette, fonts, logo, and shape for your brand
+- `storefront-next:sfnext-data-fetching` - Loaders that feed data to components
+- `storefront-next:sfnext-page-designer` - Make a component Page Designer-editable
+- `storefront-next:sfnext-extensions` - Extension folders and UI targets
+- `storefront-next:sfnext-testing` - Vitest, Storybook, and e2e testing
+- `storefront-next:sfnext-accessibility` - Accessibility requirements and scans
 - `storefront-next:sfnext-i18n` - Translating component text
+- `storefront-next:sfnext-performance` - Lazy loading, images, bundle size

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

@@ -0,0 +1,118 @@
+# Component Authoring
+
+## Workflow
+
+1. **Search first.** `ls src/components`, and grep for the behavior you need. Prefer composing or extending.
+2. **Pick the layer.** shadcn fork in `src/components/ui/`, or a composite in `src/components/<name>/`, or an extension under `src/extensions/`.
+3. **Implement** with token classes, `cn()`, project link wrappers, i18n, `formatCurrency`.
+4. **Add a test** (`index.test.tsx`, Vitest + Testing Library) and a **story** (see [STORYBOOK.md](STORYBOOK.md)).
+5. **Verify** with `pnpm typecheck`, `pnpm lint`, `pnpm test`, `pnpm storybook:test --type=snapshot`.
+
+## Composite example
+
+A small presentational component with a variant, token classes, a `data-slot` root, translated text, and a safe price format. Names here are illustrative; check that a component of that name does not already exist.
+
+```tsx
+/* Apache header (copy from any existing file) */
+import { cva, type VariantProps } from 'class-variance-authority';
+import { useTranslation } from 'react-i18next';
+import { cn } from '@/lib/utils';
+import { formatCurrency } from '@/lib/currency';
+
+const promoVariants = cva('inline-flex items-center gap-1 px-2 py-1 text-sm font-medium rounded-ui', {
+    variants: {
+        tone: {
+            default: 'bg-primary text-primary-foreground',
+            muted: 'bg-muted text-muted-foreground',
+            danger: 'bg-destructive text-destructive-foreground',
+        },
+    },
+    defaultVariants: { tone: 'default' },
+});
+
+interface PromoPriceProps extends VariantProps<typeof promoVariants> {
+    amount: number;
+    currency: string;
+    locale: string;
+    className?: string;
+}
+
+export function PromoPrice({ amount, currency, locale, tone, className }: PromoPriceProps) {
+    const { t } = useTranslation();
+    return (
+        <span data-slot="promo-price" className={cn(promoVariants({ tone }), className)}>
+            {t('promoPrice.label', { defaultValue: 'Now' })} {formatCurrency(amount, locale, currency)}
+        </span>
+    );
+}
+```
+
+Add real translation keys to `src/locales/<locale>/translations.json` for every supported locale (see `storefront-next:sfnext-i18n`); do not rely on `defaultValue` in shipped code.
+
+## Rules of thumb
+
+- **Props over globals.** Keep components presentational; data arrives through props or a narrow hook.
+- **`asChild`** (Radix `Slot`) for polymorphism; do not add an `as` prop.
+- **`data-slot`** on the root and named regions. It is the stable hook for theme CSS and shape-token overrides. It is a convention of the shadcn forks, not a lint rule.
+- **Variants** with `cva`; variant classes use semantic tokens (`text-destructive-foreground`, not `text-white`).
+- **Shape**: no raw `rounded-*`/`shadow-*` on primitives or Cards; see [SHAPE-TOKENS.md](SHAPE-TOKENS.md). `rounded-full` on a pill or avatar and `rounded-t-*` style directional radii are fine.
+- **Context**: split React contexts by concern; avoid one large `AppContext` (every change re-renders every consumer).
+- **Client-only data** goes through loaders or `useFetcher`, not `useEffect` fetches for first render.
+- **Links**: `@/components/link`, `@/hooks/use-navigate`.
+- **Icons**: `lucide-react` (and `@icons-pack/react-simple-icons` for brand icons).
+
+## Editing a shadcn primitive
+
+Primitives are your fork. It is fine to edit them in place: add a variant, a prop, or a `data-slot`. Keep shape tokens (`rounded-ui`, `shadow-ui`, `border-ui`) and `@/` imports. After editing or syncing, run `node .claude/skills/sync-shadcn/sync.mjs restyle --all --check`. Do not add app-specific components to `src/components/ui/`; wrap the primitive in `src/components/` instead:
+
+```tsx
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+export function PillButton(props: React.ComponentProps<typeof Button>) {
+    return <Button {...props} className={cn('rounded-full', props.className)} />;
+}
+```
+
+## CSS component class, utility, or React component?
+
+Default to a React component when there is markup, props, or logic. Use a CSS component class only for a pure layout bag of properties applied to many different elements, defined in `@layer components` in `src/theme/base.css` so utilities can still override it. The shipped example is `.section-container` (horizontal padding, max width, centered). Do not use `@utility` for overridable multi-property compositions; the utilities layer has the highest specificity and overrides lose.
+
+```css
+/* src/theme/base.css */
+@layer components {
+    .section-container {
+        @apply px-4 sm:px-8 lg:px-16 max-w-screen-2xl mx-auto;
+    }
+}
+```
+
+## Decorative icons from CSS
+
+To add a purely decorative icon to a component you do not want to fork, define the SVG once as a token (a percent-encoded `data:image/svg+xml` URI, with `stroke="black"` because only alpha matters in a mask) in `src/theme/tokens/core.css`, then paint it with a pseudo-element in `src/theme/base.css`:
+
+```css
+[data-slot="section-title"]::before {
+    content: "";
+    display: inline-block;
+    width: 1rem;
+    height: 1rem;
+    background-color: currentColor;      /* tracks the text color */
+    -webkit-mask: var(--icon-star) center / contain no-repeat;
+    mask: var(--icon-star) center / contain no-repeat;
+}
+```
+
+Use `mask` plus `background-color`, not `content: url()` (which cannot inherit `currentColor`). Keep the hooked structure stable. Full write-up with state swapping: `docs/README-UI-STYLING.md`.
+
+## Accessibility checklist
+
+- Semantic HTML first (`button`, `nav`, `main`, `ul`), ARIA only to fill gaps.
+- Interactive elements are keyboard reachable with a visible focus ring (`focus-visible:ring-ring/50 focus-visible:ring-[3px]`).
+- Text and UI boundaries meet WCAG AA contrast using theme tokens (the token comments in `core.css` record ratios).
+- Images have `alt` (empty string for decorative).
+- Run `pnpm lint:a11y` and `pnpm storybook:test --type=a11y`. See `storefront-next:sfnext-accessibility`.
+
+## Page Designer
+
+To make a component editable in Page Designer, use the decorators and registry described in `storefront-next:sfnext-page-designer`; do not hand-roll metadata.

package/content/guidance/storefront-next/sfnext-components/references/SHAPE-TOKENS.md

@@ -0,0 +1,51 @@
+# Shape Tokens
+
+Radius, shadow, and Card border width are driven by three variables so one edit re-skins every shadcn primitive. The project doc is `docs/README-SHAPE-TOKENS.md`; this is the working summary.
+
+| Variable | Defined in | Utility |
+|---|---|---|
+| `--ui-radius` | `src/theme/tokens/core.css` | `rounded-ui` (about 19 primitives) |
+| `--ui-shadow` | `src/theme/tokens/core.css` | `shadow-ui` |
+| `--ui-border-width` | `src/theme/tokens/core.css` | `border-ui` (Card only) |
+
+Your starter theme's values are the ones in `core.css` (a square, flat, borderless default is `0` / `none` / `0`). For a rounded, raised look set for example `--ui-radius: var(--radius-xl)` and a soft `--ui-shadow`.
+
+## The bridge-variable trap
+
+`src/theme/tailwind.css` contains `--radius-ui: var(--ui-radius)` and `--shadow-ui: var(--ui-shadow)` inside `@theme inline`. Tailwind inlines these at compile time, so `--radius-ui` and `--shadow-ui` do not exist at runtime. Writing them is a silent no-op that passes lint and typecheck. Always write `--ui-radius`, `--ui-shadow`, `--ui-border-width`. `border-ui` is an `@utility` that reads `--ui-border-width` at runtime.
+
+## Overrides
+
+Per instance (Tailwind arbitrary property):
+
+```tsx
+<Card className="[--ui-border-width:2px] border-primary">
+<Card className="[--ui-radius:var(--radius-2xl)]">
+<Card className="[--ui-shadow:none]">
+```
+
+Per component or section, in `src/theme/base.css`. Use `[data-slot="card"]` as the hook, and `:where()` to keep specificity low so className overrides still win:
+
+```css
+.product-card[data-slot="card"] {
+    --ui-radius: var(--radius-2xl);
+    --ui-shadow: 0 4px 16px -4px rgb(0 0 0 / 0.12);
+}
+
+:where([data-section="auth"]) [data-slot="card"] {
+    --ui-border-width: 1px;
+}
+```
+
+The shipped `base.css` already re-enables a 1px Card border for account, auth, checkout, and order-confirmation sections because the default border width is 0. Place later `:where()` blocks after earlier ones that target the same `data-slot`; equal specificity means the later block wins.
+
+## Don't
+
+| Don't | Why | Do |
+|---|---|---|
+| `className="rounded-xl"` or `rounded-none` on a primitive | Fights the token; breaks when the token changes | Set `[--ui-radius:...]` or change `core.css` |
+| `className="border"` / `border-2` on Card | `border-ui` reads the variable, both classes coexist | `[--ui-border-width:1px]` |
+| `!rounded-none`, hard-coded `border-radius` / `box-shadow` in CSS | Not token-driven | Override the variable |
+| Styling via Tailwind class selectors (`.bg-cover`) | Breaks on refactor | Target `data-slot` |
+
+`cn()` in `src/lib/utils.ts` registers `border-ui` as its own tailwind-merge group, so `cn('border-ui border-border', 'border-primary')` keeps width and swaps color.

package/content/guidance/storefront-next/sfnext-components/references/STORYBOOK.md

@@ -0,0 +1,54 @@
+# Stories and Storybook Checks
+
+Project reference: `docs/README-STORYBOOK.md` (taxonomy, decorators, mock routes, play functions) and `docs/README-STORY-COVERAGE.md`.
+
+## Layout
+
+- Stories go in a `stories/` subfolder beside the component: `cart/cart-content.tsx` is matched by `cart/stories/cart-content.stories.tsx`; `cart/index.tsx` by `cart/stories/index.stories.tsx`. Coverage tooling only recognizes stories there.
+- `src/components/ui/` (shadcn forks) is excluded from story coverage and generated story tests.
+- Snapshot baselines use a fixture file `<name>-snapshot.tsx` next to the story and write to `stories/__snapshots__/`. Copy the small wrapper from `src/components/collapsible-section/stories/collapsible-section-snapshot.tsx`; `product-tile/stories/` shows a richer one.
+
+## Minimal story
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { PromoBadge } from '../index';
+
+const meta: Meta<typeof PromoBadge> = {
+    title: 'Products/Promo Badge',
+    component: PromoBadge,
+    tags: ['autodocs'],
+    args: { label: '20% off' },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+```
+
+Import types from `@storybook/react-vite` (not `@storybook/react`). Include the Apache header.
+
+## Titles
+
+`meta.title` is `Domain/Component` or `Domain/Subgroup/Component`, Title Case With Spaces. Use an existing top-level group: Account, Authentication, Cart, Category, Checkout, Content, Core, Design System, Extensions, Home, Layout, Products, Search. Pick by purpose, not folder. Titles are convention, not lint-enforced; you may restructure the sidebar for your brand.
+
+## Writing good stories
+
+- Props first; mock at the route boundary via story parameters (`routeLoaderData`, `scapiMock`, `mockRoutes`), not `vi.mock` of hooks.
+- Reuse fixtures from `@/components/__mocks__` and config from `@/test-utils/config` instead of inventing data shapes.
+- No promises or other non-serializable values in `args`.
+- Hide `className` and ReactNode props from Controls (`control: false, table: { disable: true }`).
+- Interactive components: add a `play` function and the `'interaction'` tag.
+
+## Commands
+
+```bash
+pnpm storybook                               # dev server on :6006
+pnpm storybook:test --type=snapshot          # jsdom snapshot gate
+pnpm storybook:test --type=snapshot --update # refresh baselines after an intended DOM change
+pnpm storybook:test --type=interaction       # real Chromium, runs play()
+pnpm storybook:test --type=a11y              # axe-core
+```
+
+Only run `--update` for changes you meant to make, and check the diff is additive before committing. After a theme change (colors, shape), snapshots of DOM markup normally do not change, but visual review in the `Design System/Theme/*` stories is worthwhile.

package/content/guidance/storefront-next/sfnext-components/references/TOKEN-SYSTEM.md

@@ -0,0 +1,53 @@
+# Token System
+
+Your theme lives in `src/theme/`. `src/theme/index.css` is the entry point (it sets Tailwind `@source` scoping and imports `shared.css`). `shared.css` imports, in order: `tw-animate-css`, `tailwind.css`, `tokens/*.css`, `animations.css`, `base.css`, then `overrides/*.css`. `storybook.css` is a second entry used by Storybook with wider `@source` globs.
+
+## How a token becomes a class
+
+1. A CSS variable is defined in a token file: `--primary: #131315;` (in `:root`).
+2. `src/theme/tailwind.css` bridges it inside an `@theme inline { ... }` block: `--color-primary: var(--primary);`.
+3. Components use the generated utilities: `bg-primary`, `text-primary-foreground`, `border-primary`.
+
+To add a token, do both steps 1 and 2. Then use the class. Never use arbitrary values such as `bg-[#131315]` or `bg-[--primary]`.
+
+## Token files (`src/theme/tokens/`)
+
+| File | Contents |
+|---|---|
+| `core.css` | Surface and text palette (`--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--tertiary`, `--muted`, `--accent`), `--destructive`/`--success`/`--warning`/`--info` pairs, borders/input/ring/separator, rating, and the shape tokens `--ui-radius`, `--ui-shadow`, `--ui-border-width`. WCAG contrast ratios are annotated in comments. |
+| `status.css` | Warning/active backgrounds, account action colors, `--status-*` (positive, warning, critical, info) |
+| `header.css` | Header, header-menu, footer, and newsletter band colors; `--header-logo-filter` |
+| `swatch.css` | Product swatch and color-pill sizing/colors |
+| `brand.css` | `--brand-*` palette primitives and the hero scrims `--hero-overlay-dark`, `--hero-overlay-light`, `--hero-scrim` |
+| `components.css` | Component-scoped tokens (payment brand colors, cart, product badge) |
+| `custom.css` | Focus and input-background helpers |
+| `sidebar.css`, `agentic.css` | Sidebar palette; agentic-shopping UI palette |
+
+Other theme files: `tailwind.css` (font stacks `--font-sans/-serif/-mono`, color bridge, `border-ui` utility), `base.css` (`@font-face`, base layer, `.section-container`, section-scoped shape rules), `animations.css`, and `overrides/*.css` for component-level CSS (navigation, cart sheet, toasts, store locator).
+
+## Class cheat sheet
+
+| Need | Classes |
+|---|---|
+| Page surface | `bg-background text-foreground` |
+| Card / popover | `bg-card text-card-foreground`, `bg-popover text-popover-foreground` |
+| Primary action | `bg-primary text-primary-foreground hover:bg-primary/90` |
+| Secondary / muted | `bg-secondary text-secondary-foreground`, `bg-muted text-muted-foreground` |
+| Borders | `border-border`, `border-border-subtle`, `border-input`; focus `ring-ring` |
+| Destructive / success / warning / info | `bg-destructive text-destructive-foreground`, and the same pairs for `success`, `warning`, `info` |
+| Status text | `text-status-positive`, `text-status-critical`, `bg-status-critical-bg`, `bg-warning-bg`, `bg-active-bg` |
+| Header | `bg-header-background text-header-foreground border-header-border`, `bg-header-menu-background`, `bg-header-menu-hover-background` |
+| Footer / newsletter | `bg-footer-background text-footer-foreground`, `bg-newsletter-background` |
+| Brand primitives | `bg-brand-black`, `text-brand-white`, `bg-brand-gray-100` (prefer semantic tokens when one fits) |
+
+Opacity modifiers work on bridged colors (`bg-primary/90`). Focus ring convention from the shipped Button: `focus-visible:ring-ring/50 focus-visible:ring-[3px]`.
+
+`--border` is the darker tier and `--border-subtle` the lighter one; both are set to meet 3:1 contrast against white. If you change them, re-check contrast.
+
+## Hard-coded colors
+
+`custom/color-linter` (OxLint) rejects raw Tailwind palette utilities in `className` and `cn()` string literals. Fix by picking a semantic token or adding a token as above. Use `pnpm lint` to check.
+
+## Dark mode
+
+The shipped theme defines a single palette in `:root`; there is no `.dark` token block. Some shadcn primitives still carry `dark:` utilities inherited from upstream, which are inert unless you add a dark palette yourself.

package/content/guidance/storefront-next/sfnext-components/references/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| New color class renders nothing | Token defined but not bridged | Add `--color-x: var(--x)` in `@theme inline` in `src/theme/tailwind.css` |
+| `pnpm lint` reports a hard-coded color utility | `custom/color-linter` | Use a semantic token class (`text-primary-foreground` instead of `text-white`) |
+| Header class like `bg-[--header-background]` does nothing | Wrong syntax | Use `bg-header-background` |
+| Setting `--radius-ui` / `--shadow-ui` has no effect | Bridge variables are compile-time only | Set `--ui-radius` / `--ui-shadow` |
+| Card border will not appear | `border` / `border-2` used | `[--ui-border-width:1px]` on the Card |
+| Links lose the site/locale prefix | `Link`/`useNavigate` imported from `react-router` | Import from `@/components/link` and `@/hooks/use-navigate` |
+| Page flickers or re-suspends forever | Several promises in one `<Suspense>`, or promises composed during render | One boundary per promise; compose in the loader |
+| Tailwind class works in dev but not in build or Storybook | File outside the `@source` globs in `src/theme/index.css` / `storybook.css` | Move the file under `src/` or extend the globs; run `pnpm lint:css` |
+| Story not counted or not found | Not in a `stories/` subfolder | Move it to `<component>/stories/` |
+| `pnpm test-storybook:...` not found | Script does not exist | `pnpm storybook:test --type=snapshot` |
+| Snapshot failure after an intended change | Baseline is stale | `pnpm storybook:test --type=snapshot --update`, review the diff |
+| shadcn fork has raw `rounded-md` / `shadow-sm` | Added with `npx shadcn add` | `node .claude/skills/sync-shadcn/sync.mjs restyle <file>` |
+| `sync`/`status` reports no baseline | `.shadcn-baseline/` not seeded | `node .claude/skills/sync-shadcn/sync.mjs sync <name> --bootstrap` |
+| Overlay code appears in the main bundle | Imported synchronously | `React.lazy` + `useDeferredUnmount`; check with `pnpm bundlesize` |
+| Typecheck passes locally, fails after route changes | Stale generated types | `pnpm typecheck` runs `react-router typegen` first; run it, not bare `tsc` |