Generate, scaffold, build and verify a React + Vite + Hono commerce storefront from a short product brief — catalog, cart, wishlist, three-step checkout, admin dashboard, AI sales assistant and EdgeOne Pages deployment files. Use when the user wants a complete ecommerce/store website skeleton from o
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.
#
Rule
Concrete meaning
IR-1
Even px, never below 12
Every font-size in px must be even and ≥ 12. text-[10px], text-[11px], text-[13px] are forbidden. Minimum is 12.
IR-2
No emoji in UI
No emoji anywhere in UI source — not in JSX, not in product data, not in mock responses, not as icon substitutes, not in i18n strings, not decoratively.
IR-3
lucide line icons only
All icons come from lucide-react (line style, no fill, single colour). Never a filled icon set, never an emoji glyph, and an inline SVG only when lucide genuinely lacks the glyph.
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.
bash
python <skill>/scripts/validate_generated_project.py <project_dir> --lang en --currency CNY
Gate
Rule
F-01
All required files exist (see §3)
F-02
Style file exists (src/styles.css)
F-03
Deployment files exist (warn)
F-04
No template leftovers: AccountPage.tsx, AiConcierge.tsx, products.json, src/lib/api.ts
P-01
Zero__PLACEHOLDER__ tokens left in any file
P-02
No placeholder copy: Product One, Category A, category-a, Lorem ipsum, TODO:, example.com
G-01
IR-2: no emoji in src/, functions/, index.html
G-02
IR-1: every text-[Npx] is even and ≥ 12
G-03
Currency consistent: CNY output contains no $<digit>, USD output contains no ¥<digit>
D-01
≥ 8 products
D-02
Each product's images[0] !== images[1] (hover swap must be visible)
D-03
≥ 5 real categories, no generic category-a style keys
Every local /images/* reference resolves to a real file
I-02
Remote images reachable (only with --check-images)
Build gate (not covered by the script — run it yourself):
bash
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)
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.
Normalize the prompt into a brief: brand name, product category, tone, hero product, palette hint.
This copies templates/base, resolves every placeholder, and never deletes an existing directory (a re-run renames the old one to <slug>.bak-<timestamp>).
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.
Apply conventions (§6–§11).
Localize money (§7).
Run the gate:validate_generated_project.py. Fix every FAIL and re-run until clean.
Run the build gate:npm install && npm run build. Fix every error.
Preview:npm run dev, confirm all 7 routes render.
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.
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).
ts
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.
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.
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.
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).
text
## 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.
File
When to read
references/architecture.md
Explaining the layer model, or extending the scaffold
references/commerce-flows.md
Wiring a real cart / checkout / payment backend
references/deployment.md
Deploying to EdgeOne Pages, env vars, webhook setup
