create-magic-storefront 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-magic-storefront",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Scaffold a Next.js storefront on the MagicStore Storefront API v2",
   "license": "MIT",
   "type": "module",

package/template/.claude/skills/storefront-design/SKILL.md

@@ -15,11 +15,17 @@ merchant's own store, not like a template and not like an AI landing page. The d
 server owns it: prices, stock, discounts, images, reviews. Design never invents or recomputes any of
 it.
 
-Two skills work together:
+The design skills work together (all in `.claude/skills/`):
 
 - **This skill** decides what a store needs and what is off limits.
-- **`design-taste-frontend`** (next to this one) supplies taste: the design read, the three dials,
-  the anti-slop rules (its Sections 0, 1, 4, 9). Load it too.
+- **`design-taste-frontend`** supplies taste: the design read, the three dials, the anti-slop
+  rules (its Sections 0, 1, 4, 9). Load it too.
+- **`web-interface-guidelines`**: keyboard, focus, forms, touch targets. Apply it to every
+  interactive part (options, cart, checkout, account).
+- **`vercel-react-best-practices`**: keep the design fast; server components stay server
+  components, no client JS for what CSS can do.
+- **`storefront-verify`**: run last. Screenshots of every page type at 390 and 1280px, checked
+  against the pre-flight below.
 
 When they disagree, **this skill wins**. The overrides are listed in [Overrides](#overrides).
 
@@ -30,7 +36,7 @@ Design from the merchant's data, not from a guess. Read, through `lib/api.ts`:
 | What                                              | Why                                                               |
 | ------------------------------------------------- | ----------------------------------------------------------------- |
 | `api.shop()`: `name`, `description`, `branding`   | Identity: logo, favicon, colors, theme                            |
-| `api.home()`: the sections in the merchant's order | What the home page must hold; a design never drops or reorders them |
+| `api.home()`: the sections in the merchant's order | On a merchant-managed home, what it must hold. A custom home may skip it (`PAGES.md`, Home) |
 | `api.collectionsIndex()`, a few `api.productsIndex()` | Category, price range, how many products, how good the photos are |
 
 `shop.branding`:
@@ -106,9 +112,12 @@ animation, no decorative imagery, no experimental layout. Trust beats taste here
 **Account, search, content pages.** Same tokens, quiet layout. Search results reuse the product
 card.
 
-**Home** (`app/page.tsx`, `components/sections/`). The one place for a strong visual idea. Each
-section type keeps its renderer; restyle it, do not replace the data it renders. The merchant's
-banners and stories are the hero imagery.
+**Home** (`app/page.tsx`). The one place for a strong visual idea, and the page a design may
+rebuild from scratch: `GET /home` is optional (`PAGES.md`, Home). On a **merchant-managed** home,
+each section type keeps its renderer in `components/sections/`, restyled, in the merchant's order.
+On a **custom** home, compose the layout the design needs from catalog, collection, review and
+content data; merchant sections (banners, stories) may be pulled in as hero imagery where the
+design wants them. Either way every block shows real API data, and an empty read renders nothing.
 
 ## 4. Telegram Mini App
 
@@ -152,7 +161,8 @@ Before calling a design done, tick every box:
       (hero banner or first product image) is not lazy-loaded.
 - [ ] No invented data: prices, badges, ratings, reviews, stock, urgency, customer logos.
 - [ ] Money only through `<Money>` / `formatMoney`.
-- [ ] Every home section type from `api.home()` still renders, in the merchant's order.
+- [ ] Home: merchant-managed — every section type from `api.home()` renders, in the merchant's
+      order; custom — every block reads real API data and hides when that read is empty.
 - [ ] Product page: price and add to cart visible without scrolling at 390×844.
 - [ ] Cart and checkout: one column on mobile, labelled fields, errors next to fields, no motion.
 - [ ] Mobile 360px: no horizontal scroll, tap targets ≥ 44px, nothing hover-only.
@@ -161,3 +171,4 @@ Before calling a design done, tick every box:
 - [ ] Empty, error and not-found states styled, not bare text.
 - [ ] Taste skill Section 14 run for the home page and content pages.
 - [ ] `npm run typecheck`, `npm run build` and `npx create-magic-storefront check` pass.
+- [ ] `storefront-verify` done: every page type looked at, at 390 and 1280px.

package/template/.claude/skills/storefront-verify/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: storefront-verify
+description: >-
+  Look at the storefront before calling visual work done: build it, run it against the real shop,
+  screenshot every page type at phone and desktop width, check the screenshots against the
+  `storefront-design` pre-flight and the Web Interface Guidelines, fix, repeat. Use after any change
+  to how the storefront looks or behaves (a design, a restyle, a new section or component), and
+  whenever asked to "check", "verify", "screenshot" or "show" the storefront.
+---
+
+# Verify the storefront
+
+Code that type-checks can still look broken. After visual work, **look at the result** before
+saying it is done. Never describe a page you have not looked at.
+
+## 1. Build and run
+
+```bash
+npm run typecheck
+npm run build
+npx create-magic-storefront check
+npm start -- -p 3100          # in the background; needs .env.local (MAGICSTORE_SHOP_DOMAIN)
+```
+
+A build or `check` failure is fixed first; screenshots of a broken build prove nothing. Stop the
+server when you are done.
+
+## 2. Pick the pages
+
+Real data only, from the running shop:
+
+| Page       | URL                                                               |
+| ---------- | ----------------------------------------------------------------- |
+| Home       | `/`                                                               |
+| Collection | the first `/collections/…` link in the home page's HTML or its menu |
+| Product    | the first `/products/…` link, plus one sold out or with options if the shop has one |
+| Search     | `/search?q=<a word from a product title>` and one with no results |
+| Cart       | `/cart` (empty), then again after adding a product                |
+| Checkout   | `/checkout` with that cart                                        |
+| Not found  | `/products/this-does-not-exist`                                   |
+
+Never place an order while verifying: stop at the checkout form.
+
+## 3. Screenshot at two widths
+
+Phone **390×844** (also the Telegram Mini App) and desktop **1280×800**, full page.
+
+- With a browser tool in your environment (Playwright MCP, Chrome DevTools, Claude in Chrome), use
+  it: resize, navigate, screenshot. It can also click through the cart and read the console.
+- Otherwise, with the Playwright CLI (the first run downloads Chromium,
+  `npx -y playwright install chromium`):
+
+  ```bash
+  mkdir -p .screenshots
+  npx -y playwright screenshot --viewport-size "390,844" --full-page \
+    http://localhost:3100/ .screenshots/home-390.png
+  npx -y playwright screenshot --viewport-size "1280,800" --full-page \
+    http://localhost:3100/ .screenshots/home-1280.png
+  ```
+
+  Then open each image and look at it. `.screenshots/` is ignored by git.
+
+In a browser tool, also check each phone-width page for horizontal scroll:
+`document.documentElement.scrollWidth > window.innerWidth` must be `false`. And read the console:
+no errors, no hydration warnings.
+
+## 4. Check what you see
+
+For every screenshot, against `storefront-design`'s pre-flight:
+
+- Nothing overflows, overlaps or is cut off; no horizontal scroll at 390px.
+- Product page at 390×844: price and add to cart visible in the first screen.
+- Header readable on the merchant's colors; logo not stretched; badges readable.
+- Images keep their aspect ratio; a missing image shows the fallback, not a broken icon.
+- Empty cart, no search results and not found look designed, not like bare text.
+- Text is in the storefront's language, with no placeholder or invented copy.
+
+Then run a `web-interface-guidelines` review of the files you changed.
+
+## 5. Fix and repeat
+
+Fix what you found, rebuild, re-shoot only the affected pages. At most three rounds; if something
+still fails after that, report it with the screenshot's path instead of looping.
+
+Finish with a short report: pages checked, at which widths, what was fixed, what is left.