Neway Commerce OS

One prompt in, one runnable storefront out.

This file is the single source of truth for generation. templates/base,
scripts/ and references/ are all downstream of it. If a rule here conflicts
with anything in the template or the scripts, this file wins — and the
inconsistency should be reported to the user, not silently resolved.

0. IRON RULES (highest priority — never violate, never "improve")

These three rules come from the user and apply to every artifact this skill
produces. They are enforced by machine gates (G-01, G-02) — a violation is a
hard failure, not a style preference.

> IR-2 and IR-3 reinforce each other: an emoji used as an icon violates both.
> Replace 🛒 with <ShoppingCart />, ❤️ with <Heart />, ✓ with <Check />.

1. HARD GATES (all must pass before delivery)

scripts/validate_generated_project.py implements every gate below. Run it on
the generated project. Exit code 0 is a precondition for delivery; a failing
gate means fixing the output, not the gate.

python <skill>/scripts/validate_generated_project.py <project_dir> --lang en --currency CNY

Build gate (not covered by the script — run it yourself):

cd <project_dir> && npm install && npm run build   # tsc --noEmit && vite build

Must exit 0 with zero TypeScript errors. A project that does not build is not a
deliverable.

> Repo hygiene (not an output gate): scripts/check_skill_language.py fails
> if any Chinese text appears in the skill itself. This skill ships to a global
> audience, so everything except README.cn.md and the description_zh /
> display_name frontmatter lines must be English — commit messages included.
> A file that genuinely needs CJK data (e.g. a regex that must also match a zh-CN
> build) carries it as a \uXXXX escape, never a literal character.

2. EXECUTION WORKFLOW (follow exactly)

0. Detect language. powershell -Command "Get-Culture | Select-Object -ExpandProperty Name" on Windows, locale | grep LANG elsewhere. zh* → Chinese UI and lang="zh-CN". Otherwise → English UI. If detection fails or is unavailable, default to English — never block on this step.
1. Normalize the prompt into a brief: brand name, product category, tone, hero product, palette hint.
2. Scaffold — never copy files by hand:
   bash python <skill>/scripts/scaffold_project.py "<prompt>" --output <cwd> --brand "<Brand>" [--site-name "<Name>"]
   This copies templates/base, resolves every placeholder, and never deletes an existing directory (a re-run renames the old one to <slug>.bak-<timestamp>).
3. Fill content. Open every page and component in the scaffold and replace the demo catalog with content that fits the brief: products, categories, brand story, promo codes, AI responses. Keep the structure and conventions — the template is a compliant reference implementation, not a blank page.
4. Apply conventions (§6–§11).
5. Localize money (§7).
6. Run the gate: validate_generated_project.py. Fix every FAIL and re-run until clean.
7. Run the build gate: npm install && npm run build. Fix every error.
8. Preview: npm run dev, confirm all 7 routes render.
9. Deliver with Handoff Notes (§12) plus the gate and build evidence.

> Fail-stop rule: if a gate or the build fails, fix the output and re-run.
> Never deliver with a failing gate, never edit the validator to make a failure
> disappear, and never describe a failing project as "ready except for…".

3. Output location & file structure

Generate into the current working directory (or a directory the user names)
as <slug>/. Never generate inside the skill directory, never overwrite an
existing project, never modify templates/base while generating.

<slug>/
├── index.html                  ← lang attr + Google Fonts
├── package.json
├── tailwind.config.js          ← two palettes + font families
├── postcss.config.js
├── vite.config.ts              ← publicDir: 'static'
├── tsconfig.json
├── .env.example
├── .gitignore
├── edgeone.json
├── README.md
├── static/images/              ← bundled demo image pool
├── src/
│   ├── main.tsx
│   ├── App.tsx                 ← 7 routes + global CartDrawer + AIChatWidget
│   ├── styles.css
│   ├── utils/format.ts         ← formatPrice() — the only money formatter
│   ├── components/
│   │   ├── Navbar.tsx
│   │   ├── Footer.tsx
│   │   ├── ProductCard.tsx
│   │   ├── CartDrawer.tsx
│   │   └── AIChatWidget.tsx
│   ├── pages/
│   │   ├── HomePage.tsx
│   │   ├── ShopPage.tsx
│   │   ├── ProductPage.tsx
│   │   ├── CartPage.tsx
│   │   ├── CheckoutPage.tsx
│   │   ├── WishlistPage.tsx
│   │   └── AdminPage.tsx
│   ├── data/products.ts        ← single source of truth (TypeScript, not JSON)
│   ├── store/cartStore.ts      ← cart + wishlist stores, both persisted
│   └── types/index.ts
└── functions/
    ├── api/products.ts
    ├── api/checkout.ts
    ├── api/assistant.ts
    └── node/stripe-webhook.ts

Route table — all 7 must exist and render.

4. Language

One rule, no exceptions: every user-facing string is in the detected
language — nav, hero, buttons, placeholders, error messages, checkout steps,
footer, AI greeting / quick replies / mock responses, admin metric labels and
table headers, category names, filter options, and mock data (order rows,
customer names, AI replies).

For en output, name = English and nameEn = an optional short subtitle. For
zh-CN output, every product sets name = Chinese and nameEn = the Latin name.

The bundled template ships en. When the detected language is zh-CN,
translate every string — do not leave English copy in a zh-CN build. Gate L-01
catches the lang attribute; the rest is on you.

5. Product data contract

src/data/products.ts is the only product source. products.json must not exist.
All money is CNY unless the market says otherwise (§7).

export interface Product {
  id: string;             // URL-safe slug, used by /product/:id
  name: string;           // primary display name
  nameEn?: string;        // optional secondary line — short subtitle or Latin name
  brand: string;
  category: string;       // must match a Category.key
  price: number;          // current price
  originalPrice?: number; // crossed-out price
  unit?: string;          // e.g. 'item'
  images: string[];       // >= 2 — [0] primary, [1] hover swap (must differ)
  colors: { name: string; hex: string }[];
  sizes: string[];
  description: string;    // full paragraph
  details: string[];      // feature bullets
  highlight: string;      // one-line selling point on the card
  tags: string[];         // must match the shop filter tag list
  material: string;
  fit: string;
  rating: number;         // 0–5
  reviewCount: number;
  stock: number;          // <= 10 renders the low-stock badge
  isNew: boolean;
  isSale: boolean;
}

Also export categories (each with key, label, icon = a lucide component,
and image) and PROMO_CODES.

Requirements: ≥ 8 products, ≥ 5 real categories (natural names for the
domain — never category-a), each category with at least one product.

6. Images

Default: the bundled local pool. templates/base/static/images/ holds 16
demo photos (apparel, bags, accessories, plus one interior shot for story blocks).
vite.config.ts sets publicDir: 'static', so they resolve as
/images/<file>.jpg and are copied to dist/images/ on build.

• Prefer local images: deterministic, offline-safe, immune to proxy/network
  failures. Gate I-01 verifies every local reference exists.
• Use a remote URL only when the brief's domain has no match in the pool. Then
  every URL must return HTTP 200 — verify with --check-images and record any
  replacement in the handoff notes.
• Never invent an image path. Never reference static/images/... in code —
  always /images/....

7. Currency

• The symbol lives in exactly one place: src/utils/format.ts
  (CURRENCY_SYMBOL). Components must call formatPrice(); hardcoding ¥ or $
  in JSX is a gate failure (G-03).
• Default market is CN → CNY (¥). For a non-CN market, change CURRENCY_SYMBOL
  and .env's VITE_DEFAULT_CURRENCY, then run the gate with --currency USD.
• The free-shipping threshold lives in format.ts as FREE_SHIPPING_THRESHOLD
  and must be imported by CartDrawer / ProductPage / CheckoutPage, never re-typed.

8. Code conventions

Fonts — index.html must load:

<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@300;400;500;700&family=Noto+Serif+SC:wght@400;600;700&family=Playfair+Display:wght@400;700&display=swap" rel="stylesheet">

tailwind.config.js defines font-body (Noto Sans SC + Latin fallback) and
font-display (Playfair Display + Noto Serif SC, so Chinese headings do not
fall back to sans).

Icons — lucide-react only; size 12–22 matched to surrounding text; no fill.
See §0 IR-3.

Typography — even px only, ≥ 12 (IR-1). Prefer Tailwind's scale (text-xs,
text-sm, text-base) over arbitrary values.

State — Zustand + persist. Cart key <slug>-cart, wishlist key
<slug>-wishlist. Wishlist must use the store, never local useState.

Routing — react-router-dom v6. Always useNavigate() / <Link>; never
window.location (gate U-02).

Animation — framer-motion. Hover lift { y: -4, scale: 1.02 }, page enter
{ opacity: 0, y: 20 } → { opacity: 1, y: 0 }, stagger staggerChildren: 0.08.
Ease-out, never bounce.

TypeScript — strict: true, no any outside placeholder API handlers, and
npm run build must be clean.

Dependencies — the stack is fixed. Do not add packages: no component
libraries, no icon sets other than lucide, no axios, no date libraries.

Visual language — off-white or near-black backgrounds (never pure #000 or
#fff), soft borders, rounded corners, muted gradients only, generous whitespace.

9. Quality floor (minimum complexity per screen)

If time is short, build fewer pages at higher quality rather than spreading thin.

HomePage — hero (overlay text + 2 CTAs), category banner grid (image + label,
hover colour change), new arrivals (4–8 isNew products with stagger),
bestsellers (rating ≥ 4.7, 4 products), brand story (two-column text + image),
AI assistant entry section.

ShopPage — sticky category tab bar driven by ?category=, toolbar with
filter toggle / sort dropdown / grid-list toggle, filter panel (tag multi-select +
price slider), responsive grid (2/3/4 cols), empty state.

ProductPage — image gallery (aspect-[4/5] + thumbnail strip), badges,
name + optional subtitle, 5-level quality bar, rating, price + crossed original,
colour and size selectors, add-to-cart + wishlist, spec rows (fit / material),
description, detail bullets, delivery info, related products (same category, ≤ 4).

ProductCard — hover image swap, badges (new / sale / low stock), heart toggle,
quick-add on hover, brand + name + optional nameEn, 5-level quality bar, rating,
highlight line, price + crossed original, colour dots, and a layout prop
('grid' | 'list').

CartDrawer — right-side slide-in (max-w-sm), backdrop, item rows with
quantity steppers and delete, subtotal, free-shipping hint, checkout + continue
shopping, empty state. Mounted once in App.tsx, toggled from the Navbar.

CheckoutPage — three steps (shipping → payment & promo → review) with a
numbered stepper: full name, email, country select, city, postal code, street
address; 3 shipping methods with fees; promo code validated against PROMO_CODES
with applied/error feedback; payment methods with lucide icons; invoice
toggle; order notes; review step with edit links, item list and agreement
checkbox; sticky order summary; success screen with a generated order number.
clearCart() runs only on the final review submit — never earlier.

WishlistPage — reads wishlistStore, empty state, add-all-to-cart.

AdminPage — 4 metric cards, recent orders table with status pills, top
products, stock overview driven by product.stock.

AIChatWidget — FAB → chat panel (w-96, max-h-[600px]), brand-coloured
header, ≥ 8 keyword scenarios, product card embeds, typing indicator, 4
quick-reply chips. Keywords must be written in the same language as the UI —
English keywords for an en build, Chinese for a zh-CN build.

Footer — service banner row (4 lucide icons), four-column link grid,
newsletter block, dynamic copyright year.

10. Animation & interaction standard

Smooth, restrained, purposeful. Every interactive element has a hover and active
state. No layout shift on hover, no transition longer than 0.8s, no infinite
decorative loops.

11. Anti-patterns (things that have actually gone wrong here)

• Mounting AIChatWidget in both App.tsx and a page → two floating buttons.
• Using window.location.href for in-app navigation → full reload and lost SPA state.
• Referencing an icon component that was never imported → build failure.
• Reusing the same URL for images[0] and images[1] → hover swap does nothing.
• Keyword language drifting from the UI language → the AI assistant goes silent.
• Copying the template's demo catalog verbatim → the store sells the wrong
  products, and gates P-02 / D-01 / D-03 fire.
• Deleting or relaxing validator rules instead of fixing the output.

12. Handoff Notes (the only delivery document)

Deliver in the reply — do not create a second NEWAY_BRIEF.md (that duplication
was removed on purpose).

## Handoff Notes — <Brand> Store

### Gates
- validate_generated_project.py: PASS (0 errors, 0 warnings)
- npm run build: exit 0 (tsc --noEmit + vite build clean)

### Scaffold status
- [x] 7 routes implemented and rendering
- [x] Product data wired (N products, M categories)
- [x] Cart + wishlist persisted
- [x] Three-step checkout with promo codes
- [x] AI concierge (K scenarios, zh + en keywords)
- [x] Admin dashboard scaffold
- [x] Iron rules verified (no emoji / even px >= 12 / lucide icons)
- [x] Images resolved (local pool or verified remote)

### Production wiring still required
- [ ] Stripe live keys (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET)
- [ ] AI endpoint (AI_API_BASE, AI_API_KEY, AI_MODEL)
- [ ] Real order persistence
- [ ] VITE_SITE_NAME / VITE_DEFAULT_CURRENCY in EdgeOne env

### Run it
npm install && npm run dev   →  http://localhost:5173

13. References

Read on demand — do not load everything up front.