# AI-GUIDE — designing this store safely

You (an AI coding assistant, or a human designer) have been asked to redesign
this storefront. This guide is the contract that lets you go as bold as you
want without breaking commerce. It was distilled from real agency builds.

## The one rule

**`src/core/` is the platform's. `src/ui/` is yours.**

Everything under `src/ui/` may be rewritten from scratch — layouts, markup,
classes, animations, entire visual languages. (Canvas-mode stores —
scaffolded with `--canvas` — ship `src/ui/` as bare unstyled skeletons with
`DESIGN ME` markers; same rules apply, you're just starting from zero.) Everything under `src/core/`
(and `src/app/api/`) keeps the store working: cart, checkout, variants,
inventory, auth, SEO, i18n. Never modify it. If a redesign seems to require a
core change, stop and say so instead.

## File map

| Path | Owner | Notes |
|------|-------|-------|
| `src/ui/layout/` | you | header, footer, announcement bar |
| `src/ui/home/` | you | homepage sections |
| `src/ui/product/` | you | card, grid, listing, product page, price, badges, selectors |
| `src/ui/cart/` | you | cart page pieces |
| `src/ui/wishlist/` | you | the wishlist page (the heart button is in `src/ui/product/`, the header link in `src/ui/layout/`) |
| `src/ui/shared/` | you | loader, image wrapper |
| `src/app/globals.css` | you | tokens + global styles |
| `src/components/ui/` | shared | shadcn/ui primitives — compose them, extend via variants |
| `src/core/**` | platform | hooks, lib, providers — read, never edit |
| `src/components/{checkout,auth,account,seo}` | platform | core-styled in v1; they inherit your tokens |
| `src/app/**` | platform | thin routes; edit only to wire new ui components |

## The dialect (shadcn/ui + lucide + cn)

This store speaks the same component dialect as Lovable / v0 / Bolt output:

- **`src/components/ui/` holds official shadcn/ui primitives** (button, card,
  badge, input, label, textarea, select, checkbox, radio-group, separator,
  accordion, dialog, sheet, skeleton, tabs, tooltip). Compose them in `src/ui/`
  instead of hand-rolling controls. Need a new look? **Extend via CVA
  variants** (add a variant to `buttonVariants`/`badgeVariants`), never by
  inline-overriding the same styles in twenty call sites.
- **Icons: lucide-react only.** No inline `<svg>` paths, no emoji-as-icons,
  no second icon set. Consistent 16/20/24px sizes.
- **Class merging: `cn()`** from `@/core/lib/utils` (clsx + tailwind-merge) —
  it's the same helper shadcn expects, already wired into every primitive.
- **Tokens drive everything**: primitives read `--primary`, `--card`,
  `--input`, `--ring`, `--radius`, etc. from `globals.css`. Restyle the store
  by changing tokens (and variants), not by scattering literal colors.
- `rounded`, `rounded-md`, `rounded-lg` all derive from `--radius`
  (shadcn convention), so corner radius follows the theme automatically.

## The hook contract (your data supply)

UI components get *everything* from `@/core/hooks/*` and
`@/core/providers/store-provider` — never from `@/core/lib` directly, except
the approved presentation helpers listed (as `!@/core/lib/...`) in the `src/ui`
`no-restricted-imports` rule in `.eslintrc.json`. `next build` runs that lint,
so importing any other `@/core/lib` module from `src/ui` fails the build:

- `useHomeData()` → `{ products, banners, loading }`
- `useProductListing()` → products + filters/sort/facets/pagination + handlers
- `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, `addToCartError`,
  customization + modifier state and errors
  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
    distinct products and the 51st add is refused, so a design that drops this
    leaves the shopper tapping a button that resets and adds nothing. Copy lives
    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
  - Five more components hold the same message in their OWN local state, because
    they add to the cart without this hook: `ui/product/product-card.tsx`,
    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
    you kept them** — the template's publish checks compare `@/ui/...` imports and SDK
    calls only, so dropping one of these leaves a green build and a silent button.
  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
    in its own `lineError` state: a failed quantity change or a failed Remove
    used to log to the console and leave the row looking untouched. It uses
    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
    cap cannot refuse a quantity change, and "we could not add this" would be a
    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
    The first two are for refusals a retry can never clear, so do not collapse
    them into the generic one. Nothing checks that you kept any of this either.
  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
    another, and the ORDER of its two cart writes (`add`, then `remove`) is a correctness property, not a
    style choice: it **adds the upgrade first and removes the original second**,
    so a failed add leaves the cart untouched instead of losing the shopper's
    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
    where the add landed and the removal did not. If you rebuild that component,
    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
- `useCart()` → the cart store (it needs `brainerce` 3.11.0 or newer, which this
  template depends on). The original fields keep their meaning:
  `{ cart, cartLoading, itemCount, totals, refreshCart }`. It adds:
  - state: `status` (`'loading' | 'empty' | 'ready' | 'error'`), `hintCount`,
    `isSyncing`, `totalsStale`, `canCheckout`, `loadError`, `mutationError`
  - actions: `add`, `setQuantity(itemId, quantity)`, `remove(itemId)`,
    `applyCoupon`, `removeCoupon`, `clear`, `retry`, `flush`,
    `dismissMutationError`, `loadEnrichment`. Every action resolves
    `{ ok, error }` and never throws.
- `useCartPage()` → what the cart page needs on top of that: `cart`, `status`,
  `hintCount`, `retry`, `mutationError`, `dismissMutationError`, `isSyncing`,
  `canCheckout`, `refreshCart`, `itemCount`, plus the cart-page extras
  (recommendations, upgrades, bundles, reservation expiry, line selection) and
  the checkout hand-off `canProceedToCheckout` / `proceedToCheckout()` /
  `proceedingToCheckout`. Gate the checkout button on `canProceedToCheckout`
  (scoped to the ticked lines), not on `canCheckout` (the whole cart).
- **Recommendations are TWO different things, never mixed (it needs `brainerce` 3.17.0 or
  newer; `customersAlsoBought` needs the release that added it, see the SDK changelog).** `useProductPage().recommendations` and `useCartPage().cartRecs` carry:
  the merchant's MANUAL lists (`crossSells`, `upsells`, `related`; in the cart
  `cartRecs.recommendations`), and ONE automatic group computed from real purchase history
  (`recommendations.automatic`, in the cart `cartRecs.automaticRecommendations`):
  `{ kind: 'bought_together' | 'similar', items }`. On the product page there is a THIRD,
  separate group, `recommendations.customersAlsoBought` (`kind: 'customers_also_bought'`):
  what customers who bought this product went on to buy in SEPARATE orders. It is a different
  claim from `bought_together` (products that shared ONE order). Rules a redesign must keep:
  - `crossSells` is NOT "frequently bought together". It is the merchant's own list and
    gets a neutral title (`productDetail.recommendedForYou`). Only the automatic group of
    kind `bought_together` is titled `productDetail.frequentlyBoughtTogether`; kind
    `similar` is `productDetail.productsYouMayLike`. Render the automatic group as its OWN
    section after the manual ones, and never merge two groups into one list. Hide a
    section with no items.
  - `customersAlsoBought` is its own section after `automatic`, titled
    `productDetail.customersAlsoBought` ("Customers also bought"). Never merge it into
    `automatic` or a manual list, and never fill it with similar products when it is absent:
    the server sends it only when the store has enough repeat customers and the merchant left
    it on, so render nothing when it is missing. It is not added to the cart rail.
  - `ui/product/frequently-bought-together.tsx` takes a `title` prop for that reason. By
    default it is gated by `storeInfo.upsell.frequentlyBoughtTogetherEnabled` (the server
    also withholds the `bought_together` group when that switch is off). The manual
    cross-sell block passes `respectSwitch={false}`: that switch belongs to the automatic
    feature and must never hide the merchant's own list.
  - A card with `requiresVariantSelection` (or a VARIABLE product with no
    `targetVariantId`) must NEVER be added with a bare `productId`: it is a link to its
    product page ("Choose options"). A card with `targetVariantId` is added WITH that
    `variantId`.
  - Every add that starts on a recommendation card passes the card's `recToken` as
    `recommendationToken` (`add({ productId, variantId?, quantity, recommendationToken })`),
    so the purchase can be attributed. Omit it for every other add.
  - Measurement lives in ONE hook, `useRecommendationCard(card)` from
    `@/core/hooks/use-recommendation-tracking` (`ref` on the card's outer element for the
    impression, `onClick` on its link for the click). Keep it on every recommendation
    card in a redesign. The SDK never sends an event just because recommendations were
    fetched, and a card without a `recToken` is simply not measured.
- `useWishlist()` → the shopper's saved items (the wishlist; it needs `brainerce`
  3.16.0 or newer). `{ status, keys, count, isSaved(key), toggle(key, { product }),
  add, remove, retry, isMember }`. `status` is `'loading' | 'ready' | 'error'`:
  render IT, never `keys.length === 0` (an `error` is not an empty list, and while
  it lasts `count` is 0, so show no number). `toggle`/`add`/`remove` show the
  change at once, put it back by themselves when the write fails, never throw, and
  resolve `{ ok: true }` or `{ ok: false, reason: 'full' | 'failed', error }`.
  A guest's list lives in the browser, a signed-in customer's on the server, and the
  guest list joins the account on login; `ui/` never needs to know which.
- `useWishlistPage()` → what the wishlist page needs on top of that: `status`
  (`'loading' | 'empty' | 'ready' | 'error'`), `products` (live price and stock),
  `isMember`, `retry`, `canAddToCart(product)`, `addAllToCart()` (resolves
  `{ added, skipped }`; it skips what is sold out or needs an option),
  `addingAll`, `addAllResult`, `dismissAddAllResult`.

Hooks return data and handlers, never JSX. All catalog content (names, prices,
images, stock) comes from them — **never hardcode products**. How the cart
store must be used is in "Cart and checkout (R1 to R6)" below.

## Verification loop (before you declare anything done)

1. **Feature coverage.** Call `get-required-features` on the `brainerce-docs`
   MCP server (wired by the scaffolder in `.mcp.json`, no setup) and confirm
   every mandatory entry is still reachable. First step, not last: you were
   invited to rewrite `src/ui/` from scratch, and a feature that lived only in
   the shipped reference is gone now with nothing to notice it by. `tsc`
   cannot see a missing feature, and these components render nothing while the
   merchant has the feature off, so a deleted one and an idle one look the
   same. `CLAUDE.md` lists the files people usually lose; the MCP tool is the
   actual specification.
2. `pnpm exec tsc --noEmit` → must be 0.
3. `pnpm dev` → drive the real flow you changed: home → listing → product →
   add to cart → cart → checkout page renders. Move between pages by CLICKING
   the header, footer and cart links, never by typing a URL, and confirm the page
   does not reload (a reload is a raw `<a href>`). On the cart page tap `+` five
   times fast: the quantity must land on the right number and never jump back.
4. Screenshot desktop (1440) AND mobile (390), in the store's language.
5. If the store is RTL: check nothing is left-anchored that should be
   right-anchored, and directional arrows point with the reading direction.
6. **Run the behaviour check** against the running dev server, on a phone
   viewport and on a slow network:
   `npm run verify:storefront -- --url http://localhost:3000 --viewport 390x844 --slow`
   (add `--locale he-IL` for a Hebrew store), then once more without
   `--viewport` and `--slow` for desktop. It is a Playwright script, so the
   first time run `npm i -D playwright && npx playwright install chromium`.
   It drives a real browser through an anonymous cart (header navigation without
   a reload, no empty-cart flash, one request per add, a burst of taps, a failed
   write, checkout waiting for a pending update, no floating widget over the
   controls, autofill tokens, no horizontal overflow) and never submits an
   order. A FAIL exits with code 1: fix the cause, do not edit the script or
   skip the check. A WARN is worth fixing and does not fail the run.
   `--only nav-no-reload,burst-taps` runs just those checks while you iterate.
   A redesign that keeps the hooks and the rules below passes it; one that draws
   "empty" before the cart has answered, or swaps `SmartLink` for a raw `<a>`,
   fails it.

## The quality bar (distilled from Lovable / v0 / Bolt system prompts)

Beautiful is the top priority — the first render must wow. Hard rules:

1. **Design system first**: define all HSL semantic tokens in globals.css
   BEFORE styling any component. Never direct colors (`text-white`,
   `bg-black`) in classNames — tokens only.
2. **Color budget: exactly 3-5 colors.** 1 brand color, 2-3 neutrals, 1-2
   accents. Never purple/violet unless the merchant asked. No gradients by
   default — solid colors; gradients only as subtle accents if requested.
3. **Max 2 font families** (1 display + 1 body, both with the store's
   script). Body line-height 1.4-1.6. Nothing below 14px.
4. **Mobile-first**; flexbox by default, grid for true 2D; no absolute
   positioning unless necessary.
5. **Tailwind discipline**: spacing scale only (`p-4`, never `p-[16px]`),
   `gap-*` over margins between siblings, `text-balance` on headlines.
6. **Real imagery everywhere** — product photos from the catalog do the
   heavy lifting; free stock hotlinks (Pexels/Unsplash) for editorial
   sections. NEVER abstract filler shapes (gradient circles, blobs).
   NEVER emojis as icons — one icon set, consistent 16/20/24px sizes.
7. **Content-rich**: no section may render empty or thin. Empty states are
   designed states with copy and structure, not blank space.
8. Component variants in the design system, not inline overrides.
9. Semantic HTML + ARIA + alt text + `sr-only` labels — always.
10. **Verify with your eyes**: screenshot after each major surface, critique
    it ("would a Lovable user accept this?"), fix, and only then move on.


## Motion language (CSS-first)

The store should feel alive, premium and intentional — every animation guides
attention, confirms an action, or rewards exploration. Rules:

- **Timing tokens** (use these, never ad-hoc numbers): 80ms instant feedback ·
  180ms hover · 300ms UI state change · 500-600ms section entrance · 900ms
  hero only. Stagger siblings 40-80ms.
- **Easing**: entrances `cubic-bezier(0.16, 1, 0.3, 1)` (out-expo); springy
  pops `cubic-bezier(0.34, 1.56, 0.64, 1)` (out-back); loops and hovers
  ease-in-out. Exits faster than entrances.
- **Reveals**: below-the-fold sections animate on viewport entry
  (IntersectionObserver — see `src/ui/shared/reveal.tsx`), never tied to
  scroll distance. One orchestrated reveal per section beats scattered
  effects; `viewport once` — do not re-animate on every scroll.
- **Micro-interactions**: CSS/WAAPI first (see `src/ui/shared/fly-to-cart.ts`
  for the pattern) — ripple, bump, image zoom, quick-add slide-up are all
  achievable without a library.
- **Pointer effects** (magnetic buttons, tilt cards, custom cursor, mouse
  parallax): desktop only — gate on `(pointer: fine)` and no-op under
  `prefers-reduced-motion`. `will-change: transform` ONLY on elements animated
  per-frame; never sprinkle it broadly.
- **Never `transition-all`** — always name the property
  (`transition-transform`, `transition-opacity`). Animate only compositor
  properties (`transform`, `opacity`) — never layout properties
  (width/height/top/margin). 60fps is non-negotiable.
- **Ambient effects** (gradient blobs, particles): maximum one per page, hero
  only — never on inner pages.
- **framer-motion / GSAP are not installed.** They are allowed, but they are
  new runtime dependencies — flag it to the user before adding.

## Hard-won gotchas (each one cost a real debugging session)

- **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.
  If you clone one for an animation and set `left`, the leftover `right: 0`
  wins in RTL documents (over-constrained boxes resolve to the RIGHT).
  Set `inset: 'auto'` before positioning.
- **Never name a custom class `overline`** — it is a Tailwind utility
  (`text-decoration-line: overline`) and will draw a line above your text.
- **`rounded` / `rounded-md` / `rounded-lg` all follow `--radius`** (shadcn
  convention, wired in tailwind.config.ts) — change the token, not the
  classes, when you want sharper or softer corners.
- **Hebrew has no uppercase** — remove `text-transform: uppercase` and wide
  `letter-spacing` from heading styles; they are Latin idioms that distort
  Hebrew (tracking is acceptable only at caption sizes).
- **Logical properties only**: `ms-/me-`, `ps-/pe-`, `start-/end-`,
  `text-start/end`. Never `ml-/mr-`, `left-/right-`, `text-left/right`,
  `flex-row-reverse`.
- **Motion**: wrap every animation in a `prefers-reduced-motion: reduce`
  guard. One well-orchestrated reveal beats scattered effects.
- **Fonts**: any face used for body or headlines must include the store's
  script (e.g. Google Fonts `hebrew` subset). Latin-only display faces are
  accent-only.
- **Public paths go through `localePath(locale, '/x')`** (`@/core/lib/locale-path`),
  never `` `/${locale}/x` ``. The default locale arrives as a real `params.locale`
  too, and the middleware 308-redirects `/{default}/x` to `/x`, so a canonical
  tag, breadcrumb link or JSON-LD url built the second way points at a redirect.
- **Every indexable page sets its own `alternates.canonical`; the root layout sets
  none.** A layout-level canonical is inherited by every page without its own and
  tells Google they are duplicates of it. `openGraph` on a page REPLACES the
  layout's object (it does not merge), so repeat `siteName` there.
- **Product meta description: `deriveSeoDescription(product)`**, never
  `product.seoDescription` alone. The merchant's text can arrive under either
  `seoDescription` or `metaDescription`; reading one silently falls back to the
  start of the description.
- **`og:type: product` and the `product:*` price/availability tags are real
  `<meta property>` elements** (`components/seo/product-og-meta.tsx`). Next's
  `openGraph.type` has no `product`, and `metadata.other` renders `name=`, which
  the crawlers that read these tags ignore. Do not also set `openGraph.type` on
  the product page, or it carries two `og:type` tags.
- **`/products` and the home grid are server-seeded.** `app/products/page.tsx`
  reads the URL (search, filters, sort, `?page=`) and passes the first render's
  products through `ListingSeedProvider`; `core/lib/listing-query.ts` is the ONE
  function turning a URL into a query, shared by that page and
  `useProductListing`. Do not fork it, and do not put the listing back behind
  `'use client'` or a `<Suspense>` fallback: the server HTML must contain the
  products, not a spinner. A seeded hook starts with `loading` false.
- **Metadata, JSON-LD and breadcrumb strings come from the message files**
  (`getServerNamespace('seo', locale)`), not from literals or a
  `locale === 'he'` ternary (English for every third language). The visible
  breadcrumb and the BreadcrumbList JSON-LD are built from the SAME items; the
  JSON-LD components take a required `breadcrumbs` prop.

### Cart and checkout (R1 to R6)

Six rules, each one a real incident on a live store (a cart that read "empty" until
the API answered, a full page reload on every menu click, three serial requests per
tap). The cart store behind `useCart()` already does R1 and R3 for you; a redesign
keeps it that way. The files this template ships already follow all six; the rules
bind whatever you rewrite in `src/ui/` and anything you add.

- **R1. Never draw "your cart is empty" before the cart has answered.** Render by
  `status`, in this order: `loading` is a skeleton of about `hintCount` rows (cap
  it, the shipped `cart-view.tsx` stops at 4; `hintCount` counts units, and it is a
  size hint, never a number to print as data) · `error` is a message with a `retry()`
  button (never an empty-cart message, never a spinner that does not end) · `empty`
  is the empty state, the ONLY status allowed to say the cart is empty · otherwise
  the cart. `cart === null` is not "empty". The header badge reads `itemCount`,
  which before the first answer is the count remembered from the last visit, so it
  never flashes 0.
- **R2. Links inside the store are router links.** In `src/ui/`, link to a path on
  this site with `Link` or `SmartLink` from `@/core/lib/navigation`, and navigate in
  code with `useRouter()` from the same module. `SmartLink` is the one for hrefs you
  do not control (menu items, footer columns, announcements, merchant-written
  URLs): a router link for `/paths`, a plain `<a>` for `http(s):`, `mailto:`,
  `tel:`, `#anchors` and `target="_blank"`. A raw `<a href="/cart">` or
  `window.location.href = '/cart'` reloads the page, throws away the cart that was
  loaded and flashes it empty. A rule in `.eslintrc.json` fails `next lint` and
  `next build` on a raw `<a href>` to an internal or dynamic path. The language
  switcher is the one deliberate exception: it builds a path for ANOTHER locale,
  which the locale-aware `Link` would rewrite back to the current one (the shipped
  `language-switcher.tsx` navigates with `window.location.href`; see
  `TRANSLATIONS.md`).
- **R3. Use the store's actions, and use the cart a write returns. Never mutate
  and then refetch.** `add`, `setQuantity(itemId, quantity)`, `remove(itemId)`,
  `applyCoupon`, `removeCoupon` and `clear` queue the write, show a quantity change
  or a removal at once (totals stay the last confirmed ones and `totalsStale` is
  true meanwhile: dim them, never compute them yourself) and adopt the server's
  answer, rolling back and setting `mutationError` if the write fails. Do not call
  `client.addToCart(...)` and then `refreshCart()`: the response already is the
  cart, and a refetch that lands after the next tap paints an older cart over a
  newer one. `refreshCart()` is only for changes the store did not make (an expired
  reservation, an order bump, a checkout coupon). Taps coalesce, so five taps on `+`
  send at most two requests: do not debounce them yourself and do not lock the
  buttons while a write is in flight. Target a line by its `item.id`, never by
  productId, because several lines can share a product (modifiers, notes). To go to
  checkout call `proceedToCheckout()` from `useCartPage()`: it awaits `flush()`, so
  the checkout is created from the cart the shopper sees, then navigates, and it
  stays on the cart with `mutationError` set when a change failed. Never render a
  bare link to `/checkout`.
- **R4. Keep the Vercel function region next to the API.** `vercel.json` ships with
  `{ "regions": ["fra1"] }`, which puts the store's server (the `/api/store` proxy
  that every cart call passes through) in Frankfurt beside the Brainerce API.
  Without it Vercel runs that function in `iad1` and every proxied call pays roughly
  300 to 450 ms more. Keep the file when you deploy to Vercel; on another host put
  the server region in Europe, close to the API. (This is hosting, nothing to do
  with commerce regions in the dashboard.)
- **R5. Nothing floats over the cart's quantity controls or the checkout fields.**
  The shopping assistant (`components/brainerce-bot.tsx`) is not mounted on `/cart`
  and `/checkout`, and `HideOnCheckout` (`components/site-chrome-gate.tsx`) removes
  the header, footer and announcement bar from `/checkout`, leaving the slim
  `CheckoutHeader` (`components/checkout-header.tsx`: the brand and a link to the
  cart, nothing else) as the way back. Any widget you add (chat
  bubble, WhatsApp button, cookie bar, back-to-top) must stay off those two routes:
  gate it on `useIsCartOrCheckoutRoute()` from `@/core/hooks/use-route-chrome`. The
  primary button under the order total is Checkout, "continue shopping" is a
  secondary link, and on a phone the cart keeps its sticky checkout bar
  (`role="region"`, `lg:hidden`, in `cart-view.tsx`) because the in-page button is
  far down the page.
- **R6. Checkout inputs carry autofill tokens.** Every input in the address and
  contact steps has an `autoComplete` token (`email`, `given-name`, `family-name`,
  `tel`, `postal-code`, `address-level1`, `address-level2`, `address-line2`,
  `country`), a `name`, and `inputMode` `email` or `tel` where it applies, so a
  phone fills the whole form in one tap. `components/checkout/` already does this;
  keep it if you ever touch those files. The address-line-1 input is the Places
  typeahead and keeps `autoComplete="off"` ON PURPOSE (the browser's saved-address
  dropdown would open on top of the suggestions); every other field keeps its
  token, and `verify:storefront` fails a checkout whose email, phone or name field
  has none.

## Never do

- Modify `src/core/`, `src/app/api/`, or checkout/auth/account internals.
- Remove accessibility attributes (`aria-*`, `role`, `alt`, focus styles).
- Hardcode catalog content, prices, or currency symbols.
- Hardcode the store name. `SiteHeader` / `SiteFooter` receive it as a prop
  from the layout; anywhere else use `useStoreName()` (client) or
  `resolveStoreName(storeInfo)` (server) from `src/core/lib/`. The name the
  scaffold knew may be nothing more than the project directory.
- Swallow the add-to-cart / checkout error states — restyle them, keep them.
- Say "your cart is empty" from `cart === null`, from `itemCount === 0`, or after
  a failed load. Only `status === 'empty'` may (R1).
- Write `<a href="/...">` or `window.location.href = '/...'` for a link inside the
  store. Use `SmartLink` or `Link` (R2).
- Call a cart write and then re-read the cart, compute cart totals from the
  optimistic lines, or send the shopper to `/checkout` without `proceedToCheckout()`
  (R3).
- Delete `vercel.json`, or move the Vercel function region away from `fra1`, when
  deploying to Vercel (R4).
- Float a widget over `/cart` or `/checkout` (R5).
- Strip `autoComplete`, `name` or `inputMode` from a checkout input (R6).
- Drop a `src/ui/` component that is the only place a mandatory feature
  exists. Rebuilding the look is free; losing the SDK call inside it is not,
  and it is silent. See "Rebuilding the look is free" in `CLAUDE.md` for the
  files people usually lose, and `get-required-features` for the real list.
- Introduce new runtime dependencies without flagging it.

## Wishlist (saved items)

Three places carry it, and a redesign must keep all three: the heart on a product
card, the heart beside add-to-cart on the product page (`ui/product/wishlist-button.tsx`,
`variant="icon"` and `variant="square"`), the heart-and-count link in the header
(`ui/layout/header-wishlist.tsx`, before the cart link in BOTH header branches), and
the page itself (`app/wishlist` + `ui/wishlist/wishlist-view.tsx`). The account page
links to it.

- **The heart is a SIBLING of the card's link, never inside it.** A button inside an
  `<a>` is invalid HTML and double-activates on some screen readers. On a card whose
  name link is stretched over the whole card (`after:absolute after:inset-0`), give the
  heart `z-10` and a positioned wrapper, or the stretched link swallows the tap.
- **Always visible.** Never reveal it on hover only: touch screens have no hover.
- **No toast library.** Feedback is the filled heart plus a polite `role="status"`
  region; a refusal (list full, save failed) is shown AND announced with `role="alert"`.
- **Never read the list as `keys.length`.** `status` first. The header badge and the
  account row show a number only when `status === 'ready'`; the page draws `error`
  as an error with a retry, never as "your wishlist is empty".
- **Keep the guest line on the page.** A guest's list is in this browser only; the page
  says so in one non-blocking line with a login link.
- All SDK calls (`client.wishlist.*`) live in `core/`. Do not call them from `ui/`.
- Logical CSS only (`start/end/ms/me`), and `rtl:rotate-180` on directional chevrons.

## Adding things

- New homepage section → new component in `src/ui/home/`, composed in
  `home-client.tsx`, data via existing hooks only.
- New place that shows a star rating or a review count (a card, a banner,
  structured data) → gate it with `useReviewsEnabled()` (client) or
  `reviewsAreOn(storeInfo)` from `src/core/lib/store-info` (server). Products
  keep their stored `avgRating` and `reviewCount` while the merchant has reviews
  switched off, so `reviewCount > 0` alone would show a rating for reviews nobody
  can open.
- New place that lists products (a card, a carousel, a search result) → render
  `<WishlistButton productId={product.id} product={product} />` as a sibling of the
  product link, so every grid saves the same way.
- New UI copy → add keys to **both** `messages/he.json` and
  `messages/en.json` (or all supported locales), use `useTranslations()`.
- New microinteraction → CSS-first; JS only for things CSS cannot do.
