@salesforce/b2c-cli 2.3.1 → 2.4.0

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

@@ -0,0 +1,151 @@
+---
+name: sfnext-testing
+description: >-
+  Write and run tests for a Storefront Next project: Vitest + React Testing Library unit tests, route loader/action tests (createLoaderArgs, createTestContext), Storybook stories with snapshot, interaction (play) and a11y runs, and a pointer to the CodeceptJS/Playwright e2e suite. Use for "write a test for this component/loader", "add a story", pnpm test, pnpm storybook:test --type=snapshot|interaction|a11y, coverage thresholds, routeLoaderData / scapiMock / mockRoutes story parameters, MSW mocking, fixtures in @/components/__mocks__, failing snapshot updates, or pnpm e2e. Do not use for lint, typecheck, format, bundle-size or Lighthouse gates (use `storefront-next:sfnext-quality-gates`), accessibility rules and fixes (use `storefront-next:sfnext-accessibility`), or translations (use `storefront-next:sfnext-i18n`).
+---
+
+# Testing Storefront Next
+
+Three layers, all shipped in your project (see `docs/README-TESTS.md`, `docs/README-STORYBOOK.md`, `AGENTS.md`):
+
+| Layer | Tool | Files | Command |
+|-------|------|-------|---------|
+| Unit and route tests | Vitest, jsdom, Testing Library, MSW | `*.test.ts(x)` next to source | `pnpm test` |
+| Component stories | Storybook: snapshot (Vitest), interaction and a11y (Playwright/Chromium) | `<component>/stories/*.stories.tsx` | `pnpm storybook:test --type=...` |
+| End to end | CodeceptJS + Playwright | `e2e/` | `pnpm e2e` |
+
+Prefer the cheapest layer that proves the behavior: pure logic and loaders in Vitest, rendered states and interactions in stories, cross-page shopper flows in e2e.
+
+## Commands
+
+```bash
+pnpm test                         # all unit tests (vitest run); does NOT collect coverage
+pnpm test src/components/footer   # one file or directory
+pnpm test:watch                   # watch mode
+pnpm test --coverage              # coverage report (thresholds enforced)
+pnpm test --ui                    # Vitest UI
+
+pnpm storybook                                        # dev server on :6006
+pnpm exec playwright install chromium                 # once, for interaction/a11y runs
+pnpm storybook:test --type=snapshot                   # add --update to rewrite snapshots
+pnpm storybook:test --type=interaction                # play() functions in real Chromium
+pnpm storybook:test --type=a11y                       # axe checks
+pnpm storybook:test --type=snapshot --stories=footer  # narrow to matching story paths
+```
+
+Add `--static` (optionally `--reuse-build` after `pnpm storybook:build`) to run interaction or a11y against a static build. `--coverage` with snapshot generates story tests and reports story coverage.
+
+Coverage thresholds live inline in `vitest.config.ts` (`thresholds`), and `src/components/ui/**`, stories, snapshot fixtures and `__mocks__` are excluded from coverage. Do not chase 100%.
+
+## Unit test
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { AllProvidersWrapper } from '@/test-utils/context-provider';
+import MyThing from './index';
+
+describe('MyThing', () => {
+    it('renders the label', () => {
+        render(<MyThing label="Hello" />, { wrapper: AllProvidersWrapper });
+        expect(screen.getByText('Hello')).toBeInTheDocument();
+    });
+});
+```
+
+`vitest.setup.ts` already provides jest-dom matchers, i18next (`en-GB`), `window.__APP_CONFIG__`, a global mock of `@/hooks/use-analytics`, and a 10s async-util timeout; do not re-add them. Helpers, wrappers and the analytics caveat: [references/UNIT-AND-ROUTE-TESTS.md](references/UNIT-AND-ROUTE-TESTS.md).
+
+## Route loader / action test
+
+```ts
+import { describe, expect, it, vi } from 'vitest';
+import { createLoaderArgs, createTestContext } from '@/lib/test-utils';
+import { loader } from './resource.basket-products';
+
+vi.mock('@/lib/api-clients.server', () => ({ createApiClients: vi.fn() }));
+
+it('returns data', async () => {
+    const context = createTestContext({ authSession: { userType: 'guest' } });
+    const args = createLoaderArgs(new Request('http://localhost/x'), context, {
+        params: {},
+        pattern: '/' as never,
+    });
+    const result = await loader(args);
+    expect(result).toBeDefined();
+});
+```
+
+`createActionArgs` is the action twin and `expectStatus(result, 400)` asserts `data()` statuses. Mock `@/lib/api-clients.server` (SCAPI) at the module boundary, or use MSW for HTTP-level tests. See `storefront-next:sfnext-data-fetching` for the loader patterns under test.
+
+## Stories
+
+Stories live in a `stories/` subfolder next to the component (required; coverage tooling only matches there):
+
+```
+src/components/footer/
+├── index.tsx
+├── index.test.tsx
+└── stories/
+    ├── index.stories.tsx
+    ├── footer-snapshot.tsx      # snapshot fixture, only where a snapshot test exists
+    └── __snapshots__/
+```
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
+import { waitForStorybookReady } from '@storybook/test-utils';
+import { mockProductSearchItem } from '@/components/__mocks__/product-search-hit-data';
+import ProductTile from '../index';
+
+const meta: Meta<typeof ProductTile> = {
+    title: 'Products/Product Tile', // Domain/Component from the fixed sidebar groups
+    component: ProductTile,
+    tags: ['autodocs', 'interaction'],
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    args: { product: mockProductSearchItem },
+    play: async ({ canvasElement }) => {
+        await waitForStorybookReady(canvasElement);
+        await expect(within(canvasElement).getAllByRole('link')[0]).toBeInTheDocument();
+    },
+};
+```
+
+Rules of thumb:
+
+- Every story is already wrapped by a global decorator (memory router + config, site, i18n, auth, basket providers). Do not add your own `ConfigProvider`. If you truly need one, import it from `@salesforce/storefront-next-runtime/config`.
+- Import test helpers from `storybook/test` (not `@storybook/test`).
+- Props first; mock at the route boundary with `parameters` (`routeLoaderData`, `scapiMock`, `miniCartData`, `mockRoutes`), never `vi.mock` of hooks inside a story. Args must be JSON-serializable.
+- Tags: `autodocs` (docs page), `interaction` (included in interaction runs), `skip-a11y` (excluded from a11y runs; use sparingly and comment why).
+- Use Storybook's viewport toolbar instead of separate mobile/desktop stories.
+- Fixtures: `@/components/__mocks__` (barrel of curated fixtures) or `@/components/__mocks__/<file>` for ones not re-exported; shared with unit tests.
+
+Full reference, including parameters, mock routes, taxonomy and argTypes: [references/STORYBOOK-PATTERNS.md](references/STORYBOOK-PATTERNS.md).
+
+## End to end
+
+`e2e/` is a separate CodeceptJS + Playwright project with its own `AGENTS.md`. Run `pnpm e2e` (add `--mode=local` to start the dev server, `--grep "@checkout"`, `--headed`). To author tests, use the skills shipped in your project at `e2e/.claude/skills/generate-storefront-e2e-test` and `e2e/.claude/skills/checkout-test-development`. Setup, env vars and the `pnpm a11y` scan: [references/E2E.md](references/E2E.md).
+
+## Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Story outside `stories/` | Move it; coverage and generated snapshot tests only find `stories/*.stories.tsx`. |
+| Interaction/a11y run fails to launch a browser | `pnpm exec playwright install chromium`. |
+| Snapshot diff after an intentional DOM change | Review it, then `pnpm storybook:test --type=snapshot --update`. |
+| Test passes but analytics never fires | `@/hooks/use-analytics` is mocked globally; `vi.unmock` it in the test to assert on track calls. |
+| Portalled dialog/toast not found in a play function | Query `within(canvasElement.ownerDocument.body)`. |
+| Mocking too deep | If an internal refactor forces story edits, push the mock to the route/fixture layer. |
+
+## Related Skills
+
+- `storefront-next:sfnext-quality-gates` - lint, typecheck, format and the pre-PR checklist
+- `storefront-next:sfnext-accessibility` - a11y assertions in stories and the e2e axe scan
+- `storefront-next:sfnext-components` - component conventions under test
+- `storefront-next:sfnext-data-fetching` - loaders and actions
+- `storefront-next:sfnext-page-designer` - testing Page Designer components
+- `storefront-next:sfnext-i18n` - translations in tests

package/content/guidance/storefront-next/sfnext-testing/references/E2E.md

@@ -0,0 +1,38 @@
+# End-to-end tests
+
+`e2e/` is a standalone CodeceptJS + Playwright project shipped with your storefront, with its own `e2e/AGENTS.md`, `e2e/README.md`, `e2e/docs/`, and in-project skills:
+
+- `e2e/.claude/skills/generate-storefront-e2e-test/SKILL.md`: structured workflow for new specs, page objects, flows and self-healing recipes.
+- `e2e/.claude/skills/checkout-test-development/`: checkout-specific E2E, debugging and performance guidance.
+
+Use those skills when authoring or debugging e2e tests; this page only orients you.
+
+## Setup
+
+```bash
+cp e2e/.env.sample e2e/.env     # BASE_URL, SITE_ID, SITE_ALIAS, LOCALE, HEADLESS, ...
+pnpm install                    # per e2e/README.md this also installs Playwright browsers; if not, pnpm exec playwright install chromium
+```
+
+The storefront itself needs its own `.env` (see `storefront-next:sfnext-configuration`).
+
+## Run
+
+```bash
+pnpm e2e                        # against a running storefront (BASE_URL, default http://localhost:5173)
+pnpm e2e --mode=local           # start the dev server automatically
+pnpm e2e --mode=remote          # BASE_URL must point at the deployed storefront
+pnpm e2e --grep "@checkout"     # filter by tag or name
+pnpm e2e --headed               # show the browser
+pnpm e2e --debug                # Playwright Inspector
+pnpm e2e:turnstile              # Turnstile-specific suite
+pnpm a11y                       # axe scans of key pages, desktop + mobile (see sfnext-accessibility)
+```
+
+The root scripts above delegate to `e2e/`; you do not need to run them from inside it.
+
+## Keep in mind
+
+- E2E runs against real backend data; prefer unit tests and stories for logic and visual states, and keep e2e for shopper journeys (search, PDP to cart, checkout, login).
+- Optional AI healing is off unless you pass `--ai` and set `ANTHROPIC_API_KEY` in `e2e/.env`.
+- `e2e/` is excluded from the root OxLint/Vitest runs and has its own `lint`, `format:check`, `typecheck` and `test` scripts (run from `e2e/`).

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

@@ -0,0 +1,97 @@
+# Storybook patterns
+
+Source of truth in your project: `docs/README-STORYBOOK.md`, `.storybook/`, and the existing `stories/` folders. Copy a neighbor story before inventing structure.
+
+## Principles
+
+1. Props first. Reach for the global provider/router stack only when the component reads global context (auth, basket, site, locale).
+2. Mock at the boundary. Prefer `parameters.routeLoaderData`, `parameters.scapiMock`, `parameters.mockRoutes` over `vi.mock` of hooks.
+3. Args are JSON-serializable. Promises, class instances and functions returning promises break the Controls panel and snapshot serialization; put them in `parameters`.
+4. One reason to update a mock. If an internal refactor forces story edits, the mock is too deep.
+
+## Decorator stack
+
+`.storybook/preview.tsx` applies `decorators: [withRouter(StoryShell)]` to every story:
+
+```
+withRouter(StoryShell)        in-memory React Router with default mock routes
+  StoryShell
+    StorybookWrapper          config + site + i18n + auth + basket + storeLocator + checkoutOneClick
+      UITargetProviders
+        <Story />
+```
+
+Files: `.storybook/decorators/{with-router,with-providers,with-ui-targets,mock-routes}.tsx|ts`. Because of this, a story usually needs no per-story `ConfigProvider` or `SiteProvider`. If you do need to override config for one story, wrap with `ConfigProvider` from `@salesforce/storefront-next-runtime/config` and `SiteProvider` from `@salesforce/storefront-next-runtime/site-context`, using `mockConfig`, `mockLocale`, `mockSiteObject` from `@/test-utils/config` (see `src/components/footer/stories/index.stories.tsx`).
+
+## Story parameters
+
+| Parameter | Use |
+|-----------|-----|
+| `routeLoaderData: Record<string, unknown>` | Wrap the story in ancestor routes so `useRouteLoaderData(routeId)` resolves. Required for components that read a parent route's loader data. |
+| `scapiMock: { data?: unknown }` | Override the default `/resource/api/client/:resource` response, for stories whose `play()` asserts specific product data. |
+| `miniCartData: { basket, productsById }` | Override what `/resource/basket-products` returns (for example an empty cart). |
+| `mockRoutes: RouteObject[]` | Add story-specific `/resource/*` or `/action/*` routes. Must not shadow `/`, `*` or a default mock path; `withRouter` throws on conflicts. |
+
+`buildDefaultMockRoutes` (in `.storybook/decorators/mock-routes.ts`) lists the default routes: basket enrichment, cart mutations, wishlist, OTP, product/bundle/set adds, site-context updates, tracking consent, place-order.
+
+## Titles and sidebar
+
+`meta.title` is `Domain/Component` or `Domain/Subgroup/Component`, Title Case With Spaces. Top-level groups: Account, Authentication, Cart, Category, Checkout, Content, Core, Design System, Extensions, Home, Layout, Products, Search. Pick the closest existing group by purpose, not by folder. This is a convention, not lint-enforced, and you may restructure it for your brand.
+
+## Naming and layout
+
+| Thing | Convention |
+|-------|-----------|
+| Story file | `*.stories.tsx` in `stories/` next to the component (required) |
+| Story export | PascalCase state name: `Default`, `Loading`, `InvalidEmailError` |
+| Snapshot fixture | `<name>-snapshot.tsx` next to the story, with `__snapshots__/` beside it |
+| shadcn primitives in `src/components/ui/` | No stories or coverage requirement |
+
+Default to one component per folder. Snapshot fixtures use `StoryTestWrapper` from `@storybook/test-utils`; copy an existing `*-snapshot.tsx` pair (for example under `src/components/footer/stories/`).
+
+## argTypes
+
+Expose only what visibly drives the canvas:
+
+```tsx
+argTypes: {
+    label: { control: 'text', description: 'Label in the summary row' },
+    className: { control: false, table: { disable: true } },
+    onCancel: { action: 'cancel' },
+}
+```
+
+## play() functions
+
+```tsx
+import { expect, userEvent, within } from 'storybook/test';
+import { waitForStorybookReady } from '@storybook/test-utils';
+
+play: async ({ canvasElement }) => {
+    await waitForStorybookReady(canvasElement);
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole('button', { name: /add to cart/i }));
+    await expect(canvas.getByRole('status')).toHaveTextContent(/added/i);
+},
+```
+
+- Tag the story `interaction` so it runs in `--type=interaction`.
+- Dialogs, popovers and toasts render into `document.body`; use `within(canvasElement.ownerDocument.body)`.
+- Assert outcomes (role, accessible name, focus, text), not CSS classes.
+- To re-render a story when an arg changes (keyed state), key the component on that prop.
+
+## Accessibility in stories
+
+The a11y addon mode is `todo` (reports, does not fail) by default. `pnpm storybook:test --type=a11y` runs with `STORYBOOK_A11Y_TEST_MODE=error`. `STORYBOOK_DISABLE_A11Y=true` turns it off. Tag `skip-a11y` excludes a story from a11y runs. To make one file strict regardless, spread `{ a11y: { test: 'error' } }` into its `parameters` (see `src/components/checkout/storybook/checkout-strict-a11y-parameters.ts`). See `storefront-next:sfnext-accessibility`.
+
+## Story coverage
+
+Stories count toward component coverage when they match the component path (`cart/cart-content.tsx` maps to `cart/stories/cart-content.stories.tsx`; `index.tsx` maps to `stories/index.stories.tsx`). `pnpm storybook:test --type=snapshot --coverage` generates story tests and reports; details in `docs/README-STORY-COVERAGE.md`.
+
+## Anti-patterns
+
+- Recreating the component's data shape as a giant literal instead of passing a fixture.
+- Promises in `args`.
+- `vi.mock` of hooks inside a story.
+- Separate Mobile/Tablet/Desktop stories (use the viewport toolbar).
+- Novel top-level title groups.

package/content/guidance/storefront-next/sfnext-testing/references/UNIT-AND-ROUTE-TESTS.md

@@ -0,0 +1,60 @@
+# Unit and route tests
+
+## Environment (`vitest.config.ts`, `vitest.setup.ts`)
+
+- jsdom, `globals: true`, `@/` alias, `testTimeout` 15s, Testing Library `asyncUtilTimeout` 10s, `pool: 'forks'` on Windows.
+- Setup already: jest-dom matchers, `window.__APP_CONFIG__ = mockConfig`, i18next initialized with all locales (language `en-GB`), `vitest-localstorage-mock`, and a global mock of `@/hooks/use-analytics`.
+- The global analytics mock means a missing `track*` call will not fail an ordinary test. To assert on tracking, call `vi.unmock('@/hooks/use-analytics')` in a `beforeEach` and provide your own spy implementation.
+- Static assets and `virtual:action-hooks` are aliased to mocks.
+
+## Helper inventory
+
+`@/test-utils/*` (src/test-utils):
+
+| Import | Provides |
+|--------|----------|
+| `@/test-utils/config` | `mockConfig`, `mockBuildConfig`, `mockSiteObject`, `mockAltSiteObject`, `mockLocale`, `getSitePrefix`, `ConfigWrapper`, `createConfigWrapper(overrides)` |
+| `@/test-utils/context-provider` | `ConfigWrapper`, `AllProvidersWrapper` (config + site + store locator + UI targets; props `config`, `currency`) |
+| `@/test-utils/auth` | `buildMockAccessToken`, `buildMockTokenResponse` |
+| `@/test-utils/request-helpers` | `createFormDataRequest(url, method, data)` |
+| `@/test-utils/wishlist` | `resetWishlistStore`, `seedWishlistStore` |
+| `@/test-utils/page-designer-host-provider` | `PageDesignerHostProvider` |
+
+`@/lib/test-utils` (src/lib/test-utils):
+
+| Export | Use |
+|--------|-----|
+| `createTestContext(opts)` | A `RouterContextProvider` with auth, app config, i18n, site (locale/currency), maintenance and performance-timer contexts. Options: `authSession` (`null` for no session), `rejectAuth`/`authError`, `appConfig`, `locale` (default `en-GB`), `currency` (default `GBP`), `skipI18next`. |
+| `createLoaderArgs(request, context, { params, pattern })` | Full `LoaderFunctionArgs`; pass `<Route.LoaderArgs>` as type parameter for typed loaders. |
+| `createActionArgs(...)` | Same for actions. |
+| `ROUTE_PATTERN` | Safe placeholder for `pattern`. |
+| `expectStatus(result, 400)` | Assert status of a `data()` response (missing status counts as 200). |
+
+Fixtures: `@/components/__mocks__` (and `@/components/__mocks__/<file>`), for example `basketWithOneItem`, `emptyBasket`, `masterProduct`, `mockStandardProductOrderable`, `mockCategories`.
+
+## Loader/action pattern
+
+Model new tests on `src/routes/resource.basket-products.test.ts` and the `_app.p.$.loader.test.ts` / `_app.cart.test.tsx` route tests:
+
+1. `vi.mock('@/lib/api-clients.server', () => ({ createApiClients: vi.fn() }))` and return fake SCAPI clients per test.
+2. Mock `@/middlewares/basket.server` (`getBasket`) or auth helpers if the route reads them.
+3. Build context with `createTestContext`, args with `createLoaderArgs`/`createActionArgs`, call the exported `loader`/`action`.
+4. Assert the returned object, thrown `Response`, or `expectStatus`.
+5. For routes exporting `shouldRevalidate`, call it directly (see `docs/README-REVALIDATION.md`).
+
+Use `createFormDataRequest` for action input.
+
+## MSW
+
+`msw` is a dev dependency. For HTTP-level tests use `setupServer` from `msw/node` and `http`/`HttpResponse` from `msw` (example: `src/components/checkout/checkout-flow.test.tsx`). Start the server in `beforeAll`, `resetHandlers` in `afterEach`, `close` in `afterAll`.
+
+## Hooks and components
+
+- Hooks: `renderHook(() => useX(), { wrapper: ConfigWrapper })` with the wrapper from `@/test-utils/config`.
+- Components needing site/config/UI targets: `render(ui, { wrapper: AllProvidersWrapper })`.
+- Component tests that mock `react-router` must provide every export the component tree uses.
+- Prefer `userEvent` from `@testing-library/user-event` over `fireEvent`, and role-based queries.
+
+## i18n in tests
+
+See `storefront-next:sfnext-i18n`: i18next is initialized globally; use `createTestContext({ locale })` for loaders.

package/content/guidance/storefront-next/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/content/guidance/storefront-next/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/dist/commands/cap/install.d.ts

@@ -44,6 +44,7 @@ export default class CapInstall extends JobCommand<typeof CapInstall> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cap/list.d.ts

@@ -39,6 +39,7 @@ export default class CapList extends JobCommand<typeof CapList> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cap/pull.d.ts

@@ -40,6 +40,7 @@ export default class CapPull extends JobCommand<typeof CapPull> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cap/tasks.d.ts

@@ -45,6 +45,7 @@ export default class CapTasks extends JobCommand<typeof CapTasks> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cap/uninstall.d.ts

@@ -39,6 +39,7 @@ export default class CapUninstall extends JobCommand<typeof CapUninstall> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/describe.d.ts

@@ -41,6 +41,7 @@ export default class CipDescribe extends CipCommand<typeof CipDescribe> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/query.d.ts

@@ -38,6 +38,7 @@ export default class CipQuery extends CipCommand<typeof CipQuery> {
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/report/bot-traffic-share.d.ts

@@ -34,6 +34,7 @@ export default class CipReportBotTrafficShare extends CipReportCommand<typeof Ci
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/report/checkout-funnel-dropoff.d.ts

@@ -34,6 +34,7 @@ export default class CipReportCheckoutFunnelDropoff extends CipReportCommand<typ
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/report/controller-error-rate-trend.d.ts

@@ -34,6 +34,7 @@ export default class CipReportControllerErrorRateTrend extends CipReportCommand<
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/report/controller-health-scorecard.d.ts

@@ -34,6 +34,7 @@ export default class CipReportControllerHealthScorecard extends CipReportCommand
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/report/customer-registration-trends.d.ts

@@ -34,6 +34,7 @@ export default class CipReportCustomerRegistrationTrends extends CipReportComman
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/cip/report/discount-depth-breakdown.d.ts

@@ -34,6 +34,7 @@ export default class CipReportDiscountDepthBreakdown extends CipReportCommand<ty
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;