# 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/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:

- `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** — `check-template-parity.js` compares `@/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 SDK calls 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`.
- `useCartPage()` / `useCart()` → `{ cart, itemCount, totals, refreshCart }`

Hooks return data and handlers, never JSX. All catalog content (names, prices,
images, stock) comes from them — **never hardcode products**.

## 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.
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.

## 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.

## 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.
- 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.

## Adding things

- New homepage section → new component in `src/ui/home/`, composed in
  `home-client.tsx`, data via existing hooks only.
- 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.