create-brainerce-store 1.51.0 → 1.52.1

package/README.md

@@ -0,0 +1,71 @@
+# create-brainerce-store
+
+Scaffold a production-ready e-commerce storefront connected to [Brainerce](https://brainerce.com) — cart, checkout, variants, coupons, auth, SEO, and i18n wired out of the box.
+
+```bash
+npm create brainerce-store@latest my-store -- --connection-id vc_xxxxxxxx
+# or
+pnpm create brainerce-store my-store --connection-id vc_xxxxxxxx
+```
+
+Run it with no flags for a fully interactive setup. The CLI fetches your store's name, currency, language, and locales from the connection ID (`vc_*`, from your Brainerce dashboard), so the generated store matches the real channel from the first `dev` run.
+
+## The design
+
+Every scaffold ships **Atelier** — a complete, AI-built storefront look (not just a color theme): warm editorial gallery with soft washes + glass surfaces, a floating hero collage, near-full-bleed product grid, styled popover dropdowns, a mini-cart drawer that opens on add-to-cart, and an RTL-safe fly-to-cart micro-interaction. Fully de-branded — driven by your store's name, catalog and dashboard content.
+
+It's a starting point, not a lock-in: the entire look lives in `src/ui/` + `globals.css` and is designed to be rewritten (see below).
+
+## Blank-canvas mode
+
+```bash
+npm create brainerce-store@latest my-store -- --connection-id vc_xxx --canvas
+```
+
+`--canvas` ships `src/ui/` as bare, semantic, essentially-unstyled skeletons (`DESIGN ME` markers included) with zero aesthetic opinion — commerce stays fully wired. It's the starting point for designing a storefront from scratch with an AI session, and the authoring substrate for new gallery designs. Canvas mode skips the design pack entirely.
+
+## AI-first by default
+
+Every scaffolded store is ready to be redesigned by an AI coding session:
+
+- **`CLAUDE.md`** — auto-loaded by Claude Code; teaches the session the one rule (`core/` is the platform's, `ui/` is yours) before it touches anything.
+- **`AGENTS.md`** — the same context for other agentic tools.
+- **`/design <your art-direction brief>`** — a ready-made slash command that walks the full redesign: concept → implementation in `ui/` → verification (tsc, real browser, screenshots, RTL checks).
+- **`AI-GUIDE.md`** — the design contract: file map, per-page hook contracts, verification loop, and hard-won RTL/i18n gotchas from real agency builds.
+
+## Architecture (core/ui)
+
+- `src/core/` — platform-owned commerce: client, auth, providers, and data/behavior hooks that return state + handlers, never JSX. Don't modify.
+- `src/ui/` — 100% replaceable presentation. Delete-and-rebuild is encouraged; the store keeps working.
+- `src/app/` — thin routes composing the two (~10 lines each).
+- An ESLint boundary rule enforces the split in both directions.
+
+Full details: [TEMPLATE-ARCHITECTURE.md](./TEMPLATE-ARCHITECTURE.md).
+
+## Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--connection-id <id>` | Brainerce vibe-coded connection ID (`vc_*`) | prompted |
+| `--canvas` | Bare unstyled `src/ui/` skeletons for AI-driven design | off |
+| `--language <lang>` | Store language (`en`, `he`) | fetched from store |
+| `--pkg-manager <pm>` | `npm`, `pnpm`, `yarn`, `bun` | auto-detected |
+| `--framework <fw>` | `nextjs` (Vite/Remix coming) | `nextjs` |
+| `--api-url <url>` | Brainerce API base URL (or `BRAINERCE_API_URL` env) | auto-discovered |
+| `--no-git` | Skip git initialization | git on |
+| `--no-install` | Skip dependency installation | install on |
+
+Pass `.` as the project name to scaffold into the current directory.
+
+## Requirements
+
+Node `^20.19.0 || ^22.13.0 || >=24.0.0`.
+
+## After scaffolding
+
+```bash
+cd my-store
+pnpm dev          # store at http://localhost:3000
+```
+
+Want a unique look? Open the folder in Claude Code and run `/design <your art-direction brief>`.

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.51.0",
+      version: "1.52.1",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -288,37 +288,6 @@ async function runInteractive(defaults) {
       initial: 0
     });
   }
-  questions.push({
-    type: "select",
-    name: "framework",
-    message: "Framework:",
-    choices: [
-      { title: "Next.js 15 (recommended)", value: "nextjs" },
-      { title: "Vite + React (coming soon)", value: "vite", disabled: true },
-      { title: "Remix (coming soon)", value: "remix", disabled: true }
-    ],
-    initial: 0
-  });
-  if (!defaults.canvas && !defaults.design) {
-    questions.push({
-      type: "select",
-      name: "design",
-      message: "Design:",
-      choices: [
-        {
-          title: "Passe-Partout \u2014 warm gallery minimal (recommended)",
-          description: "Framed product cards, placard PDP, print-serif titles",
-          value: "passepartout"
-        },
-        {
-          title: "Minimal \u2014 bare clean base",
-          description: "Neutral tokens, unopinionated layout",
-          value: "minimal"
-        }
-      ],
-      initial: 0
-    });
-  }
   questions.push({
     type: "select",
     name: "pkgManager",
@@ -352,9 +321,8 @@ async function runInteractive(defaults) {
     projectName: defaults.projectName || response.projectName,
     connectionId: defaults.connectionId || response.connectionId,
     language: response.language || defaults.language || "en",
-    framework: response.framework || defaults.framework || "nextjs",
-    theme: response.theme || defaults.theme || "minimal",
-    design: response.design || defaults.design || "minimal",
+    framework: defaults.framework || "nextjs",
+    design: response.design || defaults.design || "atelier",
     pkgManager: response.pkgManager || defaults.pkgManager || detectInvokingPackageManager()
   };
 }
@@ -381,22 +349,8 @@ function toEnvLiteral(value) {
 function isValidLocale(locale) {
   return typeof locale === "string" && /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})?$/.test(locale);
 }
-function getFontConfig(language, theme) {
+function getFontConfig(language) {
   const isHebrew = language === "he";
-  if (theme === "luxury") {
-    const subsets = isHebrew ? "['latin']" : "['latin']";
-    return {
-      fontImport: "import { Cormorant_Garamond } from 'next/font/google';",
-      fontVariable: `const font = Cormorant_Garamond({ weight: ['400', '500', '600', '700'], subsets: ${subsets} });`
-    };
-  }
-  if (theme === "playful") {
-    const subsets = isHebrew ? "['latin']" : "['latin']";
-    return {
-      fontImport: "import { Nunito } from 'next/font/google';",
-      fontVariable: `const font = Nunito({ subsets: ${subsets} });`
-    };
-  }
   if (isHebrew) {
     return {
       fontImport: "import { Rubik } from 'next/font/google';",
@@ -409,7 +363,7 @@ function getFontConfig(language, theme) {
   };
 }
 async function scaffold(options) {
-  const { projectName, framework, theme, scaffoldInPlace } = options;
+  const { projectName, framework, scaffoldInPlace } = options;
   const targetDir = scaffoldInPlace ? process.cwd() : import_path.default.resolve(process.cwd(), projectName);
   if (!scaffoldInPlace && await import_fs_extra.default.pathExists(targetDir)) {
     const contents = await import_fs_extra.default.readdir(targetDir);
@@ -419,12 +373,11 @@ async function scaffold(options) {
   }
   const templatesRoot = findTemplatesDir(__dirname);
   const baseDir = import_path.default.join(templatesRoot, framework, "base");
-  const themeDir = import_path.default.join(templatesRoot, framework, "themes", theme);
   if (!await import_fs_extra.default.pathExists(baseDir)) {
     throw new Error(`Template "${framework}" not found at ${baseDir}`);
   }
   const direction = getDirection(options.language);
-  const fontConfig = getFontConfig(options.language, theme);
+  const fontConfig = getFontConfig(options.language);
   const ogLocale = options.language === "he" ? "he_IL" : "en_US";
   const rawSupportedLocales = options.i18n?.supportedLocales || [options.language];
   const supportedLocales = rawSupportedLocales.filter(isValidLocale);
@@ -537,16 +490,6 @@ async function scaffold(options) {
       await import_fs_extra.default.move(import_path.default.join(appDir, entry.name), import_path.default.join(localeDir, entry.name));
     }
   }
-  if (!options.canvas && !designName && await import_fs_extra.default.pathExists(themeDir)) {
-    const themeCss = import_path.default.join(themeDir, "globals.css");
-    if (await import_fs_extra.default.pathExists(themeCss)) {
-      await import_fs_extra.default.copy(themeCss, import_path.default.join(targetDir, "src", "app", "globals.css"));
-    }
-    const themeJson = import_path.default.join(themeDir, "theme.json");
-    if (await import_fs_extra.default.pathExists(themeJson)) {
-      await import_fs_extra.default.copy(themeJson, import_path.default.join(targetDir, "theme.json"));
-    }
-  }
 }
 function deepMerge(base, patch) {
   const out = { ...base };
@@ -777,10 +720,7 @@ var program = new import_commander.Command();
 program.name("create-brainerce-store").description("Scaffold a production-ready e-commerce storefront connected to Brainerce").version(pkg.version).argument("[project-name]", "Name for the project directory").option("--connection-id <id>", "Brainerce vibe-coded connection ID (vc_*)").option(
   "--api-url <url>",
   "Brainerce API base URL (overrides BRAINERCE_API_URL env, defaults to https://api.brainerce.com)"
-).option("--language <lang>", "Store language (en, he)").option("--framework <framework>", "Framework to use", "nextjs").option("--theme <theme>", "Token theme to apply (kept for backward compat)", "minimal").option(
-  "--design <design>",
-  "Storefront design pack: passepartout (warm gallery minimal) or minimal (bare base)"
-).option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option(
+).option("--language <lang>", "Store language (en, he)").addOption(new import_commander.Option("--framework <framework>", "Framework to use").default("nextjs").hideHelp()).addOption(new import_commander.Option("--design <design>", "Storefront design pack").hideHelp()).option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option(
   "--canvas",
   "Scaffold src/ui as bare unstyled skeletons \u2014 a blank canvas for AI-driven design (commerce stays fully wired)"
 ).option("--no-git", "Skip git initialization").option("--no-install", "Skip dependency installation").action(async (projectNameArg, options) => {
@@ -814,8 +754,7 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     const VALID_LANGUAGES = ["en", "he"];
     const VALID_PKG_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
     const VALID_FRAMEWORKS = ["nextjs"];
-    const VALID_THEMES = ["minimal", "luxury", "playful"];
-    const VALID_DESIGNS = ["minimal", "passepartout"];
+    const VALID_DESIGNS = ["minimal", "atelier"];
     let language = options.language;
     if (language && !VALID_LANGUAGES.includes(language)) {
       logger.error(
@@ -830,11 +769,6 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       );
       process.exit(1);
     }
-    let theme = options.theme;
-    if (!VALID_THEMES.includes(theme)) {
-      logger.error(`Invalid --theme "${theme}". Expected one of: ${VALID_THEMES.join(", ")}`);
-      process.exit(1);
-    }
     let design = options.design;
     if (design && !VALID_DESIGNS.includes(design)) {
       logger.error(`Invalid --design "${design}". Expected one of: ${VALID_DESIGNS.join(", ")}`);
@@ -888,7 +822,6 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
         connectionId,
         language: languageDefault,
         framework,
-        theme,
         design,
         pkgManager,
         canvas
@@ -897,7 +830,6 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       connectionId = answers.connectionId;
       language = answers.language;
       framework = answers.framework;
-      theme = answers.theme;
       design = answers.design;
       pkgManager = answers.pkgManager;
     }
@@ -945,14 +877,13 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       connectionId,
       apiBaseUrl: resolvedApiUrl,
       framework,
-      theme,
       storeName: storeInfo.name,
       currency: storeInfo.currency,
       language: language || storeInfo.language,
       i18n: storeInfo.i18n,
       scaffoldInPlace,
       canvas,
-      design: canvas ? void 0 : design || "minimal"
+      design: canvas ? void 0 : design || "atelier"
     });
     scaffoldSpinner.succeed(
       scaffoldInPlace ? "Scaffolded into current directory" : `Scaffolded into ./${projectName}`
@@ -966,9 +897,16 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
         const gitOpts = { cwd, stdio: ["ignore", "ignore", "pipe"] };
         execFileSync("git", ["init"], gitOpts);
         execFileSync("git", ["add", "-A"], gitOpts);
+        let hasIdentity = true;
+        try {
+          execFileSync("git", ["config", "user.email"], gitOpts);
+        } catch {
+          hasIdentity = false;
+        }
+        const identityArgs = hasIdentity ? [] : ["-c", "user.name=Brainerce", "-c", "user.email=scaffold@brainerce.com"];
         execFileSync(
           "git",
-          ["commit", "-m", "Initial commit from create-brainerce-store"],
+          [...identityArgs, "commit", "-m", "Initial commit from create-brainerce-store"],
           gitOpts
         );
         gitSpinner.succeed("Git initialized");
@@ -981,8 +919,14 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     if (!skipInstall) {
       const installSpinner = createSpinner(`Installing dependencies with ${pkgManager}...`);
       installSpinner.start();
+      const installDir = scaffoldInPlace ? "." : projectName;
       try {
-        await installDependencies(scaffoldInPlace ? "." : projectName, pkgManager);
+        const installArgs = pkgManager === "pnpm" ? ["--ignore-workspace"] : [];
+        await installDependencies(installDir, pkgManager, { args: installArgs });
+        const fsExtra = require("fs-extra");
+        if (!await fsExtra.pathExists(import_path2.default.join(installDir, "node_modules"))) {
+          throw new Error("Install completed but node_modules was not created.");
+        }
         installSpinner.succeed("Dependencies installed");
       } catch (err) {
         installSpinner.fail("Dependency installation failed");

package/messages/en.json

@@ -100,6 +100,38 @@
     "addingAll": "Adding...",
     "by": "By"
   },
+  "reviews": {
+    "title": "Reviews",
+    "noReviews": "No reviews yet — be the first to share your experience.",
+    "verifiedPurchase": "Verified purchase",
+    "loading": "Loading…",
+    "signIn": "Sign in",
+    "signInSuffix": "to leave a review for this product.",
+    "onlyPurchasers": "Only customers who purchased this product can leave a review.",
+    "reviewsDisabled": "Reviews are not enabled for this store.",
+    "cannotReview": "You cannot review this product right now.",
+    "confirmDelete": "Delete your review for this product?",
+    "deleteFailed": "Could not delete your review. Please try again.",
+    "startOver": "Want to start over? You can delete your review.",
+    "deleting": "Deleting…",
+    "deleteReview": "Delete review",
+    "alreadySubmitted": "You've already submitted a review for this product.",
+    "tooMany": "Too many submissions. Please try again in a few minutes.",
+    "updateFailed": "Could not update your review. Please try again.",
+    "submitFailed": "Could not submit your review. Please try again.",
+    "thanksUpdated": "Thanks! Your review has been updated.",
+    "thanksSubmitted": "Thanks! Your review has been submitted.",
+    "editYourReview": "Edit your review",
+    "writeReview": "Write a review",
+    "yourRating": "Your rating",
+    "starRating": "Star rating",
+    "yourReview": "Your review",
+    "optionalField": "optional",
+    "saving": "Saving…",
+    "submittingBtn": "Submitting…",
+    "saveChanges": "Save changes",
+    "submitReview": "Submit review"
+  },
   "customization": {
     "title": "Personalize this product",
     "selectPlaceholder": "Choose an option",

package/messages/he.json

@@ -100,6 +100,38 @@
     "addingAll": "מוסיף...",
     "by": "מאת"
   },
+  "reviews": {
+    "title": "ביקורות",
+    "noReviews": "אין עדיין ביקורות — היו הראשונים לשתף.",
+    "verifiedPurchase": "רכישה מאומתת",
+    "loading": "טוען…",
+    "signIn": "התחברו",
+    "signInSuffix": "כדי לכתוב ביקורת על המוצר.",
+    "onlyPurchasers": "רק לקוחות שרכשו את המוצר יכולים לכתוב ביקורת.",
+    "reviewsDisabled": "ביקורות אינן פעילות בחנות זו.",
+    "cannotReview": "לא ניתן לכתוב ביקורת על המוצר כרגע.",
+    "confirmDelete": "למחוק את הביקורת שלך על המוצר?",
+    "deleteFailed": "לא ניתן היה למחוק את הביקורת. נסו שוב.",
+    "startOver": "רוצים להתחיל מחדש? אפשר למחוק את הביקורת.",
+    "deleting": "מוחק…",
+    "deleteReview": "מחיקת ביקורת",
+    "alreadySubmitted": "כבר שלחתם ביקורת על המוצר הזה.",
+    "tooMany": "יותר מדי נסיונות. נסו שוב בעוד כמה דקות.",
+    "updateFailed": "לא ניתן היה לעדכן את הביקורת. נסו שוב.",
+    "submitFailed": "לא ניתן היה לשלוח את הביקורת. נסו שוב.",
+    "thanksUpdated": "תודה! הביקורת עודכנה.",
+    "thanksSubmitted": "תודה! הביקורת נשלחה.",
+    "editYourReview": "עריכת הביקורת",
+    "writeReview": "כתיבת ביקורת",
+    "yourRating": "הדירוג שלכם",
+    "starRating": "דירוג כוכבים",
+    "yourReview": "הביקורת שלכם",
+    "optionalField": "לא חובה",
+    "saving": "שומר…",
+    "submittingBtn": "שולח…",
+    "saveChanges": "שמירת שינויים",
+    "submitReview": "שליחת ביקורת"
+  },
   "customization": {
     "title": "התאמה אישית של המוצר",
     "selectPlaceholder": "בחר אפשרות",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.51.0",
+  "version": "1.52.1",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/.claude/commands/design.md

@@ -32,6 +32,15 @@ which surface.
 
 ## The process
 
+## The quality bar (non-negotiable — from the AI-GUIDE)
+
+Exactly 3-5 colors (no purple unless asked, no gradients by default), max 2
+font families, tokens-only colors, Tailwind spacing scale, real imagery
+(never abstract filler), content-rich sections, mobile-first. After EACH
+major surface: screenshot → self-critique ("would a Lovable user accept
+this?") → fix → continue. See AI-GUIDE.md "The quality bar".
+
+
 1. **Commit to ONE art direction** — write it down in 4 lines (typography
    pairing incl. a script-compatible webfont, 6-10 color tokens, layout
    concept, motion language) at the top of `DESIGN.md` in the project root.

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

@@ -26,10 +26,31 @@ core change, stop and say so instead.
 | `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
@@ -54,6 +75,34 @@ images, stock) comes from them — **never hardcode products**.
 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.
+
+
 ## Hard-won gotchas (each one cost a real debugging session)
 
 - **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.
@@ -62,9 +111,9 @@ images, stock) comes from them — **never hardcode products**.
   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-md` / `rounded-lg` are fixed radii** — they ignore your
-  `--radius` token. For token-driven corners use `rounded` (DEFAULT) or set
-  radii explicitly.
+- **`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).

package/templates/nextjs/base/CLAUDE.md

@@ -21,6 +21,16 @@ and handlers, never JSX. Never hardcode catalog content.
 contracts, and hard-won RTL/i18n gotchas that will save you real debugging
 time.
 
+## The dialect
+
+- `src/components/ui/` = official **shadcn/ui primitives** (Button, Card,
+  Badge, Input, Select, Accordion, Dialog, Sheet, Skeleton, …). Compose them;
+  extend looks via CVA **variants**, never repeated inline overrides.
+- Icons: **lucide-react only** — no inline `<svg>`, no emoji-as-icons.
+- Class merging: **`cn()`** from `@/core/lib/utils`.
+- Colors/radius come from the semantic HSL tokens in `globals.css`
+  (`--primary`, `--card`, `--ring`, `--radius`, …) — restyle via tokens.
+
 ## Redesigning? Use the ready-made flow
 
 Run `/design <your art-direction brief>` — it walks the whole process:

package/templates/nextjs/base/package.json.ejs

@@ -1,39 +1,52 @@
-{
-  "name": "<%= projectName %>",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint",
-    "setup": "node scripts/fetch-store-info.mjs"
-  },
-  "dependencies": {
-    "brainerce": "<%= brainerceVersion %>",
-    "next": "^15.3.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "clsx": "^2.1.0",
-    "tailwind-merge": "^2.2.0",
-    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
-    "sharp": "^0.35.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "autoprefixer": "^10.4.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "^15.3.4",
-    "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": ["sharp"]
-  }
-}
+{
+  "name": "<%= projectName %>",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "setup": "node scripts/fetch-store-info.mjs"
+  },
+  "dependencies": {
+    "brainerce": "<%= brainerceVersion %>",
+    "next": "^15.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@radix-ui/react-accordion": "^1.2.0",
+    "@radix-ui/react-checkbox": "^1.1.1",
+    "@radix-ui/react-dialog": "^1.1.2",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-radio-group": "^1.2.0",
+    "@radix-ui/react-select": "^2.1.1",
+    "@radix-ui/react-separator": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-tabs": "^1.1.0",
+    "@radix-ui/react-tooltip": "^1.1.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.462.0",
+    "tailwind-merge": "^2.5.2",
+    "tailwindcss-animate": "^1.0.7",
+    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.3.4",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["sharp"]
+  }
+}

package/templates/nextjs/base/src/app/globals.css

@@ -1,30 +1,36 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 0 0% 9%;
-    --primary: 0 0% 9%;
-    --primary-foreground: 0 0% 98%;
-    --secondary: 0 0% 96%;
-    --secondary-foreground: 0 0% 9%;
-    --muted: 0 0% 96%;
-    --muted-foreground: 0 0% 45%;
-    --accent: 0 0% 96%;
-    --accent-foreground: 0 0% 9%;
-    --destructive: 0 84% 60%;
-    --destructive-foreground: 0 0% 98%;
-    --border: 0 0% 90%;
-    --radius: 0.5rem;
-  }
-
-  * {
-    @apply border-border;
-  }
-
-  body {
-    @apply bg-background text-foreground antialiased;
-  }
-}
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 0 0% 9%;
+    --primary: 0 0% 9%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 0 0% 96%;
+    --secondary-foreground: 0 0% 9%;
+    --muted: 0 0% 96%;
+    --muted-foreground: 0 0% 45%;
+    --accent: 0 0% 96%;
+    --accent-foreground: 0 0% 9%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 0 0% 90%;
+    --input: 0 0% 90%;
+    --ring: 0 0% 9%;
+    --card: 0 0% 100%;
+    --card-foreground: 0 0% 9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 0 0% 9%;
+    --radius: 0.5rem;
+  }
+
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+  }
+}