create-magic-storefront 0.1.0 → 0.1.2

package/template/.claude/skills/design-taste-frontend/SOURCE.md

@@ -0,0 +1,9 @@
+# Source
+
+Vendored unchanged from [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill),
+`skills/taste-skill/SKILL.md` at commit `ce26fc25c0e5e8cab638f883de62d9a86ee5e45b` (MIT, see
+`LICENSE`).
+
+Do not edit `SKILL.md` here: storefront-specific rules and overrides live in
+`../storefront-design/SKILL.md`. To update, copy the upstream file over this one and record the
+new commit above.

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

@@ -0,0 +1,170 @@
+---
+name: storefront-design
+description: >-
+  Visual design for this MagicStore storefront: brand tokens from the shop's branding, a design
+  direction per merchant, commerce page patterns (product card, collection, product page, cart,
+  checkout, account), and a pre-flight check. Load it before any work that changes how the
+  storefront looks: a new design, a redesign, restyling a page or a home section, a new component.
+  It drives the `design-taste-frontend` skill and overrides it wherever the two disagree.
+---
+
+# Storefront design
+
+The storefront renders one merchant's shop from the MagicStore API. Its design must look like that
+merchant's own store, not like a template and not like an AI landing page. The data is real and the
+server owns it: prices, stock, discounts, images, reviews. Design never invents or recomputes any of
+it.
+
+The design skills work together (all in `.claude/skills/`):
+
+- **This skill** decides what a store needs and what is off limits.
+- **`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).
+
+## 1. Read the shop before designing
+
+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.collectionsIndex()`, a few `api.productsIndex()` | Category, price range, how many products, how good the photos are |
+
+`shop.branding`:
+
+- `logo`, `favicon`: `Image | null`. With a logo, the header shows it (via `<Image>`), not the
+  shop name in bold text. Without one, set the name as a wordmark in the display face.
+- `colors.main`, `navbarBackground`, `navbarText`, `buttonText`, `labelBackground`, `labelText`:
+  each a CSS color **or `null`**. `main` is the accent.
+- `theme`: a free-form name from the merchant's admin. Treat it as a hint, not an enum.
+
+Then write the design read from `design-taste-frontend` Section 0.B, in store terms:
+
+> Reading this as: a _category_ store for _audience_, with a _vibe_ language, accent from
+> `branding.colors.main`, leaning toward _type pairing + density_.
+
+Category and audience come from the catalog (products, collections, price range), not from the
+shop name. A kids' store, a hardware store and a jewellery store must not come out looking alike.
+
+## 2. Brand tokens: from the API, at runtime
+
+The merchant changes colors in the admin, and `SHOP_UPDATED` revalidates the shop. So:
+
+- **Never hard-code the merchant's colors** into CSS. The starter does this already:
+  `app/layout.tsx` puts `brandStyle(shop.branding)` (`lib/brand.ts`) on `<html style>`, and
+  `app/globals.css` declares every token with the design's own fallback, used when a color is `null`.
+  Keep that wiring; restyle through the tokens.
+- Tokens: `--accent` / `--on-accent` (`colors.main` / `buttonText`), `--nav-bg` / `--nav-fg`
+  (header), `--label-bg` / `--label-fg` (badges: "New", "Sale", "Pre-order").
+- One accent, used the same way on every page (the taste skill's Color Consistency Lock).
+- A text color the merchant didn't set is picked by contrast (`readableTextOn`), never assumed
+  white. Only hex colors are accepted: anything else is dropped, never written into the style.
+- A pair the merchant did set is theirs, even when its contrast is low; point it out to the owner
+  rather than overriding it.
+- Merchant colors are unknown at design time, so check contrast with a light, a dark and a
+  saturated accent, not only the one shop you are looking at.
+- Everything else (neutrals, radius, spacing, type scale, shadows) belongs to the design and lives
+  in `globals.css` as tokens.
+
+## 3. Page patterns
+
+Every page handles its empty, error and not-found states (see `PAGES.md`). The patterns below are
+about how pages look.
+
+**Header.** Logo or wordmark, top collections, search, account, cart with a live count. One line at
+desktop. On mobile: logo, search, cart visible; the rest in a menu. Sticky is fine; the header stays
+at most 64px high on mobile.
+
+**Product card** (`components/product-grid.tsx`). Image with a fixed aspect ratio (no layout
+shift), title (at most 2 lines), price via `<Money>`, `compareAtPrice` struck through when present.
+Badges come only from data: `isNew`, a `compareAtPrice` above `price`, `preOrder`,
+`availableForSale: false`. At most two badges. `rating` only when present, with its real value.
+The whole card is one link; a quick-add button, if any, is a separate control.
+
+**Collection.** Title, product count, then the grid straight away: no hero blocks pushing products
+below the fold. Grid: 2 columns on mobile, 3 to 5 on desktop depending on density. Sorting and
+filters sit above the grid; pagination via `<Pagination>`.
+
+**Product page** (`app/products/[handle]`, `components/buy-box.tsx`). Gallery left, buy box right
+on desktop; on mobile gallery, then title, price, options, add to cart. Price and add to cart are
+visible without scrolling on a 390×844 screen. Options: sold-out values stay visible but disabled
+(`isOptionValueAvailable`), never hidden. Stock text comes from `quantityAvailable`; do not add
+urgency the API didn't send. Attributes (SKU, weight, vendor, option values) are allowed and
+wanted: set them as a clean definition list.
+
+**Cart.** Lines with a thumbnail (`<Image width={64} height={64}>`), quantity stepper, remove, line
+total from the cart. Subtotal and checkout button visible without scrolling. The empty cart links
+back to the catalog.
+
+**Checkout.** Conventional and calm: one column, clear labels above the fields, visible
+errors next to the field (`error.detail`), a summary of lines and totals from the checkout. No
+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.
+
+## 4. Telegram Mini App
+
+The same app runs inside Telegram's in-app browser. Design mobile-first for a 360–430px viewport:
+tap targets at least 44px, no hover-only controls, no information that only appears on hover,
+`env(safe-area-inset-*)` padding on fixed bars. `min-height: 100dvh`, never `100vh`.
+
+## 5. Stack
+
+Keep the starter's approach: plain CSS with custom properties in `app/globals.css`, no UI
+framework. Add Tailwind v4 or Motion only when the owner of this storefront asks for it. If you add
+Motion, use it only in `'use client'` leaf components on the home page and content pages. Fonts via
+`next/font`. Before importing any package, check `package.json` (taste skill Section 3.F).
+
+## Overrides
+
+Where `design-taste-frontend` says otherwise, this is what applies here:
+
+| Taste skill                                                 | In this storefront                                                                                                                                                                 |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 4.8: generate images, use Picsum, stock photos              | **Never** for products, collections, banners or stories: those images come from the API only. A missing image renders `<Image fallback>`. Generated imagery only for decoration the merchant has no data for, and only when asked. |
+| 4.8 / 9.F: logo walls, "Trusted by", testimonials           | Only real data: `api.reviewsSite()` / the store-reviews section, the shop's own logo. No invented brands, customers, ratings or review counts.                                        |
+| 9.D: invent realistic content                               | Never. Real product titles, prices and copy only. Placeholder copy in a shipped page is a bug.                                                                                      |
+| 4.6 / 13: forms and multi-step flows out of scope           | Cart, checkout and account follow Section 3 here: conventional, accessible, no creative layout.                                                                                     |
+| 4.9 / 9.F: spec sheets banned                               | Product attributes are allowed, as a definition list without a border on every row.                                                                                               |
+| 5: sticky-stack, horizontal pan, GSAP                       | Home and content pages only. Never on collection, product, cart or checkout pages.                                                                                                 |
+| 6.C / 8: dark mode mandatory                                | One theme per store, chosen from `branding` (Theme Lock still holds). Add a dark variant only if the brand colors pass contrast in it.                                             |
+| 3.A: Tailwind v4 + Motion by default                        | Section 5 here.                                                                                                                                                                    |
+| 12: block library files                                     | Ignore: blocks are not shipped with this storefront.                                                                                                                               |
+| Urgency: countdowns, "only N left", "X people viewing"      | Only from data: the deal-of-day and flash-sale sections' end dates, `quantityAvailable`. Never invented.                                                                         |
+
+## Pre-flight
+
+Before calling a design done, tick every box:
+
+- [ ] Design read written; category and audience taken from the catalog.
+- [ ] Brand colors read from `shop.branding` at runtime; every token has a fallback for `null`.
+- [ ] Contrast AA for text on accent, on the header and on badges, checked with light, dark and
+      saturated accents.
+- [ ] All images from the API via `<Image>`, fixed aspect ratios, no layout shift; the LCP image
+      (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.
+- [ ] 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.
+- [ ] Keyboard: visible focus ring on every control, logical tab order; `prefers-reduced-motion`
+      respected.
+- [ ] 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           |
+| 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.