@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/content/guidance/storefront-next/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/content/guidance/storefront-next/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.

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

@@ -0,0 +1,135 @@
+---
+name: sfnext-create-vertical
+description: Create a new Storefront Next vertical (brand theme / storefront variant) by editing brand design tokens, typography, dark mode, and the Figma kit. Use when asked to create a new vertical, brand, theme, or storefront variant, re-skin the storefront, or change the brand palette. Covers the brand.css token layer, semantic token rules, fixture-based local development, and the extension-vs-base decision. NOT for engineering component patterns — see sfnext-components.
+---
+
+# Create a Vertical Skill
+
+This skill is the entrypoint for creating a new Storefront Next **vertical** — a brand theme or storefront variant (e.g. Beauty, Furniture, Grocery) layered on top of the shared template without forking shared code.
+
+A vertical is built almost entirely from **design tokens**. The golden rule of the token system makes the whole approach possible:
+
+> **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.
+
+See [Token System Reference](references/TOKEN-SYSTEM.md) for the full token map and semantic class meanings.
+
+## What a vertical is — and is not
+
+| A vertical **is** | A vertical **is not** |
+|-------------------|-----------------------|
+| Token value changes in `src/theme/tokens/brand.css` | Forking `src/components/ui/` primitives |
+| Optional vertical composition in `src/components/` and `src/extensions/<vertical>/` | Editing `core.css`, `header.css`, `status.css`, `swatch.css`, or `components.css` |
+| Optional typography and i18n content | Adding `if (vertical)` branches to shared components |
+
+**Only `src/theme/tokens/brand.css` changes between verticals.** Everything else is shared infrastructure.
+
+## Before you start — read the token layer first
+
+1. Read `src/theme/tokens/brand.css` — understand the current palette structure before defining new values.
+2. Read `src/theme/tokens/core.css` — understand how brand values map to semantic roles.
+3. Read `src/theme/tailwind.css` — understand the CSS variable → Tailwind utility bridge.
+
+Do not define any new token values until you have read these three files.
+
+## Workflow
+
+### 1. Establish the brand palette
+
+Capture from the brand:
+
+- Brand name
+- Light/dark foreground + background pairs
+- Signature accent / primary color
+- Header surface treatment (dark vs light header)
+- Logo treatment and typography
+
+Update **only** values in `src/theme/tokens/brand.css` — do not rename variables.
+
+**WCAG contrast check.** After defining the palette, verify AA contrast (4.5:1 for normal text):
+
+- Primary button: `bg-primary` / `text-primary-foreground`
+- Body text: `text-foreground` on `bg-background`
+
+Use the [WebAIM contrast checker](https://webaim.org/resources/contrastchecker/) or equivalent.
+
+### 2. Add optional typography overrides
+
+If the vertical uses custom fonts:
+
+- Add font loading/import in the app entry.
+- Update `--font-sans` / `--font-serif` values in `brand.css`.
+
+### 3. Keep local development stable with fixtures
+
+Vertical work usually happens before real SCAPI credentials are wired up. Use static fixtures so home and PDP render reliably:
+
+- Create `src/config/<vertical>-fixtures.ts` with `VERTICAL_NAV_CATEGORIES` and `VERTICAL_PRODUCT` (typed as `ShopperProducts.schemas['Product']`).
+- Short-circuit the `_app.tsx` loader to return fixture categories.
+- Short-circuit the `_app.product.$productId.tsx` loader to resolve the fixture product.
+
+Restore the normal SCAPI calls once real credentials are available.
+
+### 4. Run the component extension audit before coding
+
+For each area you intend to change, decide one of three outcomes **before** writing code:
+
+```
+Does the change only affect visual tokens (color, font, spacing)?
+  └─ YES → Token / CVA-only change. brand.css handles most of it.
+  └─ NO  → Is the structural change needed by only one vertical?
+              └─ YES → src/extensions/<vertical>/ via UITarget injection. Never touch core.
+              └─ NO  → Add a slot / render-prop to the BASE component, each vertical fills it.
+              └─ UNSURE → Build vertical-specific first; promote to base on the second consumer.
+```
+
+See [Component Authoring Reference](references/COMPONENT-AUTHORING.md) for the layer model and the extend-before-create rule.
+
+### 5. Validate
+
+- Run `pnpm dev` and verify home + PDP rendering in light and dark mode.
+- Confirm there are no hardcoded color classes (no `bg-black`, `text-white`, raw hex).
+- Run Storybook snapshot checks for changed components.
+
+### 6. Sync the Figma kit
+
+After code-side token decisions are stable, duplicate and sync the Figma kit. Use the `sfnext-create-figma-kit` skill (in the `storefront-next-figma` plugin). Always sync tokens **first**, then logo, then shared-component overrides, then new page-level frames.
+
+## Execution modes
+
+The same workflow runs in two modes:
+
+- **Assisted (IDE automation):** follow the phase order strictly; use automation for repeatable edits and audits; keep human approval points for architecture decisions (extension vs base).
+- **Manual:** use the workflow as a checklist; record each decision in a lightweight table (component area · decision type · target path · rationale); apply edits by hand.
+
+## Required outcomes
+
+- Brand token updates isolated to `brand.css` (and optional vertical override files).
+- No primitive forks under `src/components/ui/`.
+- Fixture short-circuit works locally without SCAPI dependency.
+- Extension-vs-base decisions documented and approved.
+- Figma sync executed after code decisions are finalized.
+
+## 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.
+
+## Related Skills
+
+- `storefront-next:sfnext-components` - Engineering component patterns (createPage, Suspense, shadcn)
+- `storefront-next:sfnext-extensions` - Extension system and UITarget injection
+- `storefront-next-figma:sfnext-create-figma-kit` - Syncing the brand tokens into the Figma kit
+
+## Reference Documentation
+
+- [Token System Reference](references/TOKEN-SYSTEM.md) - Full token map, semantic class meanings, dark mode rules
+- [Component Authoring Reference](references/COMPONENT-AUTHORING.md) - Layer model, CVA, extend-before-create
+- [Project Structure Reference](references/PROJECT-STRUCTURE.md) - Monorepo and theme file layout
+- [Troubleshooting Reference](references/TROUBLESHOOTING.md) - Token, snapshot, and lint pitfalls

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

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

package/content/guidance/storefront-next/sfnext-create-vertical/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/content/guidance/storefront-next/sfnext-create-vertical/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.