create-brainerce-store 1.61.0 → 1.63.0

package/templates/nextjs/base/AI-GUIDE.md

@@ -1,174 +1,174 @@
-# 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`, customization
-  + modifier state and errors
-- `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. `pnpm exec tsc --noEmit` → must be 0.
-2. `pnpm dev` → drive the real flow you changed: home → listing → product →
-   add to cart → cart → checkout page renders.
-3. Screenshot desktop (1440) AND mobile (390), in the store's language.
-4. 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.
-- Swallow the add-to-cart / checkout error states — restyle them, keep them.
-- 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.
+# 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`, customization
+  + modifier state and errors
+- `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. `pnpm exec tsc --noEmit` → must be 0.
+2. `pnpm dev` → drive the real flow you changed: home → listing → product →
+   add to cart → cart → checkout page renders.
+3. Screenshot desktop (1440) AND mobile (390), in the store's language.
+4. 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.
+- Swallow the add-to-cart / checkout error states — restyle them, keep them.
+- 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.