create-magic-storefront 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-magic-storefront",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Scaffold a Next.js storefront on the MagicStore Storefront API v2",
   "license": "MIT",
   "type": "module",
@@ -18,8 +18,8 @@
     "esbuild": "^0.27.0"
   },
   "devDependencies": {
-    "@magicstoreai/hydrogen": "0.5.0",
-    "@magicstoreai/storefront-client": "0.5.0",
+    "@magicstoreai/hydrogen": "0.6.0",
+    "@magicstoreai/storefront-client": "0.6.0",
     "@types/node": "^26.6.2",
     "react": "^19.3.0",
     "tsup": "^8.5.1",

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

@@ -61,10 +61,11 @@ The merchant changes colors in the admin, and `SHOP_UPDATED` revalidates the sho
 
 - **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.
+  `app/styles/tokens.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").
+  (header), `--label-bg` / `--label-fg` (badges: "New", "Sale", "Pre-order"); the accent as text on
+  the page is `--accent-text`, never `--accent` (a pale accent fails on white).
 - 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.
@@ -72,8 +73,10 @@ The merchant changes colors in the admin, and `SHOP_UPDATED` revalidates the sho
   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.
+- Everything else (neutrals, radius, spacing, type scale, shadows) belongs to the design. The
+  token table, theme settings, CSS layers and the UI primitives in `components/ui/` are in
+  `DESIGN.md`: read it and build from them instead of restating values or writing one-off
+  components.
 
 ## 3. Page patterns
 
@@ -94,7 +97,7 @@ The whole card is one link; a quick-add button, if any, is a separate control.
 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
+**Product page** (`app/products/[handle]`, `components/product/`). 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
@@ -128,10 +131,11 @@ tap targets at least 44px, no hover-only controls, no information that only appe
 
 ## 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).
+Keep the starter's approach: plain CSS with custom properties, one file per layer in
+`app/styles/` (`DESIGN.md`), 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
 

package/template/AGENTS.md

@@ -51,6 +51,13 @@ from a landing page: brand colors come from `shop.branding` at runtime, product
 come only from the API, nothing is invented (prices, badges, reviews, urgency), and the cart and
 checkout stay conventional.
 
+`DESIGN.md` is the design system: tokens (`app/styles/tokens.css`), type, the global theme
+settings (`theme/settings.ts` → `data-*` on `<html>`: corner radius, image ratio, card style,
+sticky header, vendor, rating, cart type, announcement), the CSS layers in `app/styles/`, and the
+contrast and layout-shift rules. Build pages from the primitives in `components/ui/` (`Button`,
+`Drawer`, `Accordion`, `QuantityStepper`, `Badge`, `Skeleton`, `Breadcrumbs`, `EmptyState`,
+`Field`, `Price`, `Rating`, `Icon`) — never one-off markup with its own styles.
+
 Before calling visual work done, follow `.claude/skills/storefront-verify/SKILL.md`: build, run,
 screenshot every page type at 390 and 1280px, fix what you see. Interactive UI follows
 `.claude/skills/web-interface-guidelines/SKILL.md`; React and Next.js code follows
@@ -58,22 +65,31 @@ screenshot every page type at 390 and 1280px, fix what you see. Interactive UI f
 
 ## Where things go
 
-| Path                            | What                                                                                                           |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `app/`                          | Pages (server components) and route handlers                                                                   |
-| `app/error.tsx`                 | Error boundary: the API's `detail`, a retry                                                                    |
-| `app/blog/`                     | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                        |
-| `app/sitemap.ts`                | Sitemap from `GET /sitemap`                                                                                    |
-| `app/page.tsx`                  | Home: the theme's `index` template (`loadTemplate` + `ThemeSections`, `PAGES.md`)                              |
-| `theme/`                        | The theme: `sections/` (schema + component), `templates/*.json`, `settings.ts`, registered in `index.ts`       |
-| `components/sections/`          | One renderer per `GET /home` section type (the `platform-home` theme section); an unknown type renders nothing |
-| `components/`                   | Shared UI; client components start with `'use client'`                                                         |
-| `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                    |
-| `lib/api.ts`                    | The server-side client (`nextCacheFetch`), `orNotFound`                                                        |
-| `app/providers.tsx`             | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                       |
-| `app/storefront-api/[...path]`  | Same-origin proxy (`createStorefrontProxy`); holds tokens and cart / checkout ids in httpOnly cookies          |
-| `app/api/magicstore/webhook`    | Signed webhook → `revalidateTag`                                                                               |
-| `app/api/magicstore/preview`    | Theme editor preview: signed token → draft mode; pages pass `themePreview()` (`lib/preview.ts`) as `preview`   |
+| Path                            | What                                                                                                                |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `app/`                          | Pages (server components) and route handlers                                                                        |
+| `app/error.tsx`                 | Error boundary: the API's `detail`, a retry                                                                         |
+| `app/not-found.tsx`             | 404 with search; a route with a `loading.tsx` checks its resource in `layout.tsx` (a real 404 status)               |
+| `app/collections/`              | All collections; a collection with facets and sort from the URL (`lib/catalog-params.ts`, `components/catalog/`)    |
+| `app/products/[handle]`         | Product: `components/product/` (gallery, variant picker, buy box, reviews, recommendations)                         |
+| `app/cart`, `app/checkout`      | Cart page (`components/cart/`), checkout steps (`components/checkout/`); titles in their `layout.tsx`               |
+| `app/account/`                  | Overview, order, addresses, profile (`components/account/`)                                                         |
+| `app/wishlist`, `app/contacts`  | Wishlist (`features.wishlist`), contacts from `api.contacts()` (`lib/contacts.ts`)                                  |
+| `app/blog/`                     | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                             |
+| `app/sitemap.ts`                | Sitemap from `GET /sitemap`                                                                                         |
+| `app/page.tsx`                  | Home: the theme's `index` template (`loadTemplate` + `ThemeSections`, `PAGES.md`)                                   |
+| `theme/`                        | The theme: `sections/` (schema + component), `templates/*.json`, `settings.ts`, registered in `index.ts`            |
+| `components/sections/`          | One renderer per `GET /home` section type (the `platform-home` theme section); an unknown type renders nothing      |
+| `components/`                   | Shared UI; client components start with `'use client'`                                                              |
+| `components/ui/`                | Primitives every page is built from (`DESIGN.md`, Components)                                                       |
+| `components/header/`, `footer/` | Desktop nav and phone drawer from `lib/menu.ts`; footer columns and contacts                                        |
+| `app/styles/`                   | Layered CSS (`tokens`, `base`, `components`, `layout`, `sections`, `pages`, `utilities`), imported by `globals.css` |
+| `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                         |
+| `lib/api.ts`                    | The server-side client (`nextCacheFetch`), `orNotFound`                                                             |
+| `app/providers.tsx`             | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                            |
+| `app/storefront-api/[...path]`  | Same-origin proxy (`createStorefrontProxy`); holds tokens and cart / checkout ids in httpOnly cookies               |
+| `app/api/magicstore/webhook`    | Signed webhook → `revalidateTag`                                                                                    |
+| `app/api/magicstore/preview`    | Theme editor preview: signed token → draft mode; pages pass `themePreview()` (`lib/preview.ts`) as `preview`        |
 
 ## Creating a new section
 

package/template/DESIGN.md

@@ -0,0 +1,117 @@
+# Design
+
+The contract for anyone (person or agent) who restyles this storefront. It says what the design is
+made of and where each part lives; the reasoning and the rules behind it are in the skills, not here:
+
+- `.claude/skills/storefront-design/SKILL.md`: what a store needs, what is off limits, pre-flight.
+  It wins over everything below.
+- `.claude/skills/design-taste-frontend/SKILL.md`: taste (design read, dials, anti-slop rules).
+- `.claude/skills/web-interface-guidelines/SKILL.md`: keyboard, focus, forms, touch targets.
+- `.claude/skills/storefront-verify/SKILL.md`: look at every page type before calling it done.
+
+## Design read
+
+> Reading this as: a general-purpose commerce theme for mainstream online shoppers in Uzbekistan
+> and Russia (mobile-first, often inside Telegram), with a calm Dawn-style language, accent from
+> `branding.colors.main`, leaning toward one neutral grotesk (Onest) with Cyrillic and Uzbek Latin,
+> portrait 3:4 product media, and low density.
+
+What the shops showed (2026-10-03, `humo.magicstore.dev`, `market.magicbot.test`):
+
+- Catalogs of electronics accessories, cosmetics, clothing, toys: anything. Prices from 27 000 to
+  2 650 000 UZS, often with a `compareAtPrice`.
+- Product photos are marketplace cards: 3:4 portrait (600×800, 800×1066), busy, saturated, with
+  text printed on them. The interface around them stays quiet: neutral surfaces, one accent, no
+  decoration competing with the photo.
+- Branding: a saturated accent (`#16A34A`, `#2563eb`), a dark navbar (`#052E16`, `#0F172A`) with
+  white text, a logo. Image sizes come without `width`/`height`, so every media box has a fixed
+  ratio.
+
+Dials (taste skill §1):
+
+| Pages                                     | `DESIGN_VARIANCE` | `MOTION_INTENSITY` | `VISUAL_DENSITY` |
+| ----------------------------------------- | ----------------- | ------------------ | ---------------- |
+| Catalog, product, cart, checkout, account | 4                 | 3                  | 4                |
+| Home and content pages (blog, pages)      | 5                 | 4                  | 3                |
+
+## Tokens
+
+All in `app/styles/tokens.css`. Components never use a raw color, size or radius; they use these.
+
+| Group    | Tokens                                                                                       | Notes                                                                       |
+| -------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Brand    | `--accent --on-accent --accent-text --nav-bg --nav-fg --label-bg --label-fg`                 | From `shop.branding` at runtime (`lib/brand.ts`); fallbacks in `tokens.css` |
+| Neutrals | `--bg --fg --muted --line --surface --placeholder --subtle --danger --success --warning`     | Cool neutral grey; Telegram's theme replaces them in a Mini App             |
+| Spacing  | `--space-1` … `--space-10` (4, 8, 12, 16, 24, 32, 48, 64, 96, 128 px)                        | Gaps and padding only from this scale                                       |
+| Type     | `--text-xs` … `--text-4xl`, `--leading-tight/snug/normal`, `--font-body`, `--font-heading`   | Sizes from `xl` up are fluid (`clamp`)                                      |
+| Shape    | `--radius-sm` (controls) `--radius-md` (cards, media) `--radius-lg` (panels) `--radius-pill` | One scale, set by the `cornerRadius` theme setting                          |
+| Depth    | `--shadow-1` (raised) `--shadow-2` (drawers, menus)                                          | Tinted with the foreground, never pure black                                |
+| Layout   | `--container` (1320px) `--gutter` (16px phone, up to 48px) `--header-h`                      |                                                                             |
+| Layers   | `--z-header --z-drawer --z-toast`                                                            | Nothing else sets `z-index` above 1                                         |
+| Motion   | `--duration-fast --duration --ease`                                                          | `0ms` under `prefers-reduced-motion`                                        |
+| Media    | `--media-ratio`                                                                              | Product image ratio, from the `productImageRatio` theme setting             |
+
+Breakpoints, mobile first: **750px** (tablet) and **990px** (desktop).
+
+Shape rule (taste skill §4.4): buttons, inputs and chips use `--radius-sm` (chips and badges may use
+`--radius-pill`); cards and images `--radius-md`; drawers and menus `--radius-lg`. Nothing else.
+
+## Type
+
+Onest (variable, 100 to 900, OFL, `app/fonts/`), self-hosted through `next/font/local` so builds
+need no network. It covers Cyrillic (with `Ғ Қ Ҳ Ў`) and Uzbek Latin (`oʻ gʻ`, U+02BB). One family:
+headings take weight 600, body 400, prices 500. No second display face, no serif.
+
+## Theme settings
+
+Merchant-editable in the admin (`theme/settings.ts`), mapped by `app/layout.tsx` to `data-*` on
+`<html>` and read by `tokens.css`:
+
+| Setting                                                | `data-*`               | Values                                       |
+| ------------------------------------------------------ | ---------------------- | -------------------------------------------- |
+| `cornerRadius`                                         | `data-radius`          | `none`, `small` (default), `medium`, `large` |
+| `productImageRatio`                                    | `data-image-ratio`     | `square`, `portrait` (default), `natural`    |
+| `cardStyle`                                            | `data-card-style`      | `minimal` (default), `card`                  |
+| `stickyHeader`                                         | `data-sticky-header`   | on by default                                |
+| `showVendor`, `showRating`, `cartType`, `announcement` | — (read by components) |                                              |
+
+Colors are not theme settings: they stay in `shop.branding`.
+
+## CSS architecture
+
+`app/globals.css` declares the layer order and imports one file per layer from `app/styles/`:
+
+```
+@layer reset, tokens, base, components, layout, sections, pages, utilities;
+```
+
+Class names are BEM-lite without a prefix: a block (`.product-card`), its elements
+(`.product-card__media`), modifiers as a second class (`.button--primary`) or a `data-*` attribute
+for state (`[data-state='open']`, `[aria-expanded='true']`). Telegram overrides stay on
+`html[data-telegram]`.
+
+## Components
+
+UI primitives in `components/ui/` (reuse them, never restyle a page with one-off markup): `Icon`,
+`Button`, `IconButton`, `Drawer`, `Accordion`, `QuantityStepper`, `Badge`, `Skeleton`,
+`Breadcrumbs`, `EmptyState`, `Field`, `Price`, `Rating`.
+
+## Accessibility and stability
+
+- Contrast AA (4.5:1) for what the design owns: a text color the merchant left empty is black or
+  white by contrast (`lib/brand.ts`); a pair the merchant set is theirs (point a low one out to the
+  owner); the accent used as text on the page is `--accent-text` (half way to `--fg`, AA for pale
+  and dark accents alike). In Telegram's dark scheme the status colors switch to lighter values.
+  Text on a status or muted fill uses `var(--bg)`, not a fixed white.
+- Tap targets at least 44px (24px with spacing for text links in lists); a visible focus ring on
+  everything focusable; drawers trap focus and return it; nothing only on hover.
+- No layout shift: images keep their box (`aspect-ratio`), the LCP image is eager with
+  `fetchpriority="high"`, `loading.tsx` skeletons take the final sizes, and `.site-main` is at least
+  a screen tall so the footer never moves on screen.
+
+## Merchant data vs design
+
+The merchant owns: colors, logo, favicon, every product, collection, page and article, banner
+images, section content and order, the announcement. The design owns: neutrals, type, spacing,
+shape, layout, interface words (`lib/i18n.ts`). A missing value hides its block; it is never
+replaced with invented copy, images, ratings or urgency.

package/template/PAGES.md

@@ -42,6 +42,12 @@ storefront token sends the browser straight to the API; then the tokens and the
 ## Layout — `app/layout.tsx`
 
 - Reads `api.shop()` and the navigation (`api.collectionsIndex` or `api.menusShow({ path: { handle: 'main' } })`).
+  `lib/menu.ts` turns them into links: `mainNav` (the `main` menu, else the root collections) for
+  `components/header/desktop-nav.tsx` and the phone drawer `components/header/mobile-menu.tsx`;
+  `footerNav` (the `footer` menu) for `components/footer/site-footer.tsx`, whose contact column
+  comes from `api.contacts()` through `lib/contacts.ts`.
+- `<main>` is at least a screen tall, so the footer starts below the fold: a streamed page or a
+  client list replacing its placeholder moves nothing on screen.
 - `generateMetadata`: `shop.seo.title || shop.name`, `shop.seo.description ?? shop.description`,
   the favicon from `shop.branding.favicon`.
 - The merchant's colors: `brandStyle(shop.branding)` (`lib/brand.ts`) on `<html style>`, as the
@@ -121,40 +127,73 @@ a contract change. The steps, the setting types and a worked example (`size-guid
 `AGENTS.md` and `.claude/skills/theme-section/SKILL.md`; `theme/sections/testimonials.tsx` is a
 section with blocks to copy from.
 
+## Collections — `app/collections/page.tsx`
+
+- Every root collection: `api.collectionsIndex({ query: { 'filter[root]': 'true', perPage: 100 } })`
+  as tiles (`CollectionTiles` in `components/sections/collections.tsx`; text cards when no
+  collection has an image), with its product count. The footer and the phone menu link it.
+- States: no collections yet (an empty state with search).
+
 ## Collection — `app/collections/[handle]/page.tsx`
 
-- `api.collectionsShow({ path: { handle } })` and `api.collectionsProducts({ path: { handle }, query: { page, perPage } })`,
-  both through `orNotFound`.
-- Filters and sorts: `api.collectionsFilters` lists the facets; pass them as `filter[…]` and `sort`
-  query parameters. An unknown filter or sort is a `VALIDATION_FAILED`, not ignored.
-- SEO: `pageMeta({ seo: collection.seo, title, description })`, and `breadcrumbJsonLd`.
-- States: an empty collection ("Nothing here yet"), a `page` past the last one (empty list), 404.
-
-## Product — `app/products/[handle]/page.tsx`, `components/buy-box.tsx`
-
-- `api.productsShow({ path: { handle } })` through `orNotFound`. Recommendations:
-  `productsRecommendations` (`intent=RELATED` or `COMPLEMENTARY`); reviews: `productsReviews`
-  (`meta.rating` has the average and breakdown). Both are catalog reads, cached like the product.
-- The buy box is a client component: `useVariantSelection(product)` (or `ProductProvider` +
-  `useProduct`), `useCart().addLine({ productId, variantId, quantity })`, `useWishlist()`, and
-  `useAnalytics().productView(...)`.
-- Price: the selected variant's `price` / `compareAtPrice`, else the product's, with `<Money>`.
+- `app/collections/[handle]/layout.tsx` checks `api.collectionsShow` through `orNotFound` before
+  anything streams, so a missing handle is a real 404 (the route's `loading.tsx` would have sent
+  200). The page reads the same cached request.
+- `api.collectionsShow`, `api.collectionsFilters` and the shop, then `api.collectionsProducts` with
+  the URL's filters, and the child collections (`hasChildren`) as chips; the FAQ below.
+- Filters and sort live in the URL, so every view is a link and works without JavaScript:
+  `lib/catalog-params.ts` reads them (`parseCatalog`) against the facets the API offered and
+  drops the rest — an unknown filter or sort is a `VALIDATION_FAILED`, not ignored — then builds
+  the API query (`apiQuery`) and every link (`catalogQuery`, `without`, `cleared`, `onPage`).
+  `components/catalog/catalog-layout.tsx` renders the facets (`facets.tsx`: lists, price range,
+  in stock; a sidebar on desktop, a drawer on phones through `facets-shell.tsx`), the count, the
+  sort, the active filters as removable chips, the grid and the pager. Search uses the same layout.
+- SEO: `pageMeta({ seo: collection.seo, title, description })`, `breadcrumbJsonLd`; filtered and
+  sorted views are `noindex`.
+- States: an empty collection ("Nothing here yet"), a filter with no match (clear the filters), a
+  `page` past the last one (empty list), 404.
+
+## Product — `app/products/[handle]/page.tsx`, `components/product/`
+
+- `app/products/[handle]/layout.tsx` checks the product exists before the page streams (a real 404,
+  as for a collection).
+- `api.productsShow({ path: { handle } })` through `orNotFound`, then in parallel: the shop,
+  `productsReviews` (first page; `meta.rating` has the average and the per-rating `breakdown`) and
+  `productsRecommendations` (`intent=COMPLEMENTARY` "pairs well with", `RELATED` "you may also
+  like"). All are catalog reads, cached like the product.
+- `ProductSelection` (`product-selection.tsx`) holds `useVariantSelection(product)` for the parts
+  that depend on the variant: `Gallery` shows its `image`, `VariantPicker` its options (pills, a
+  `<select>` past eight values), `BuyBox` its price, stock and add to cart.
+- The buy box: `<Price>` of the selected variant (else the product), the stock the API reports
+  (`quantityAvailable`; nothing when `null`), `QuantityStepper` bounded by it,
+  `useCart().addLine({ productId, variantId, quantity })` then the cart drawer, `useWishlist()`
+  (only with `features.wishlist`), `shop.checkout.deliveryText`, and
+  `useAnalytics().productView(...)`. A product with `preOrder` takes a pre-order instead
+  (`pre-order-form.tsx`, `preOrdersStore`: name and phone, none for a signed-in customer).
+- Below: description and `faq` as accordions, share (Web Share API, else copy the link); reviews
+  (`reviews.tsx` server-renders the summary and first page, `review-list.tsx` loads more and
+  filters by `filter[rating]`); the two recommendation shelves.
 - SEO: `pageMeta({ seo, title, description, images })`, and
-  `jsonLdScript(productJsonLd(product, { url }))` in a `<script type="application/ld+json">`.
+  `jsonLdScript(productJsonLd(product, { url }))` plus `breadcrumbJsonLd` in
+  `<script type="application/ld+json">`.
 - States: 404; out of stock (`availableForSale` false on the product or the selected variant —
-  disable "add to cart", say "Sold out"); an option value that leads nowhere
-  (`isAvailable(name, value)` false — disable it); a failed add (`CART_LINES_UNAVAILABLE` and others:
-  show `detail`); no images (`<Image fallback>`).
+  "Sold out", no stepper); an option value no variant for sale has (`isAvailable(name, value)`
+  false — struck through, still selectable: it moves to the closest variant); a failed add
+  (`CART_LINES_UNAVAILABLE` and others: show `detail`); no images (a placeholder); no reviews (the
+  section is hidden); no recommendations (the shelf is hidden).
 
 ## Search — `app/search/page.tsx`
 
 - `api.search({ query: { q, page, perPage } })` — not cached (no tag). Suggestions while typing:
-  `searchSuggestions({ query: { q } })` from the browser; popular queries: `searchTrending`.
-- Facets: `searchFilters({ query: { q } })`.
-- States: no query yet (show the form only), no results, pagination.
+  `searchSuggestions({ query: { q } })` from the browser (`components/search/`); popular queries:
+  `searchTrending`.
+- Facets: `searchFilters({ query: { q } })`, rendered by the collection's `CatalogLayout` with `q`
+  kept in every link.
+- States: no query yet (the form and popular searches), no results (an empty state and popular
+  searches), no match for the filters (clear them), pagination.
 - Search pages are usually `noindex`; report `useAnalytics().search(q, total)`.
 
-## Cart — `app/cart/page.tsx`
+## Cart — `app/cart/page.tsx`, `components/cart/`
 
 - Client only: `useCart()` — `cart`, `status` (`loading` / `updating` / `idle`), `error`, and the
   changes (`updateLine`, `removeLine`, `setDiscountCodes`, `setNote`, `setGift`, `setPoints`).
@@ -162,9 +201,13 @@ section with blocks to copy from.
   Discount codes answer `applicable` and a `reasonCode`.
 - States: loading (the stored cart is being fetched), empty or no cart, a line no longer available,
   a rejected code, the last failed change (`error`, the cart is already back to the server's).
+- The page lists the lines; `components/cart/cart-summary.tsx` holds the discount codes (a
+  rejected one says why, from `reasonCode`), the note (saved on blur through `setNote`), the
+  discounts and the total from `cart.cost`, and the checkout button. The cart drawer is the same
+  cart, opened after every add.
 - Never put the cart id in a URL.
 
-## Checkout — `app/checkout/page.tsx`
+## Checkout — `app/checkout/page.tsx`, `components/checkout/`
 
 - Client only. `checkoutsStore({ body: { cartId } })` (safe to repeat), then fill what
   `checkout.missing` lists, in order: `CONTACT` → `DELIVERY_ADDRESS` (or a pickup point from
@@ -176,10 +219,25 @@ section with blocks to copy from.
 - States: empty cart, preparing, each step's validation errors (`VALIDATION_FAILED` → per field),
   `DELIVERY_QUOTE_EXPIRED` (list the options again), `CHECKOUT_NOT_READY`, `CHECKOUT_CLOSED`,
   `STORE_UNAVAILABLE`, a payment that is still pending.
+- `components/checkout/use-checkout.ts` runs the steps and maps `VALIDATION_FAILED` to
+  `fieldErrors`; `steps.tsx` renders contact, delivery and payment (`radio-card.tsx` for the
+  choices) behind `step-indicator.tsx`; `order-summary.tsx` shows the lines and `checkout.cost`
+  (collapsed on phones); `thank-you.tsx` the order number after completion.
 - Never put the checkout id in a URL or a log.
 
-## Account — `app/account/page.tsx`
-
+## Account — `app/account/`, `components/account/`
+
+- Pages: overview with the orders (`app/account/page.tsx`), an order
+  (`app/account/orders/[id]/page.tsx`), addresses (`app/account/addresses/page.tsx`) and the
+  profile (`app/account/profile/page.tsx`), each inside `components/account/account-shell.tsx`
+  (sign-in gate, header, navigation). Client pages take their titles from
+  `app/account/layout.tsx`.
+- An order (`order-detail.tsx`): its lines, amounts and status; "Order again" calls
+  `useCart().reorder(orderId)` (the server copies what is still for sale into a new cart, which
+  becomes the buyer's) and opens the cart; "Cancel" asks to confirm, then
+  `customerOrdersCancellation`.
+- Addresses: `customerAddresses*` (add, edit, delete, make default). Profile: name, gender,
+  language through `customerUpdate`, and sign out.
 - Client only. Signed out:
   - Phone: `useCustomer().requestOtp(phone)` → `verifyOtp(phone, code)` (`OTP_INVALID`: re-type;
     `OTP_EXPIRED`: ask again). On a shop whose sign-in code is off
@@ -246,7 +304,7 @@ same API.
 
 All blog reads are `magicstore:pages`. Rules: the backend's `docs/api/v2/blog.md`.
 
-- **Index** `app/blog/page.tsx`: heading and intro from `shop.blog` (else `t.blog`), categories
+- **Index** `app/blog/(index)/page.tsx` (a route group: its `loading.tsx` covers the index only): heading and intro from `shop.blog` (else `t.blog`), categories
   (`api.blogCategoriesIndex()`, `CategoryNav`), editor's picks (`filter[featured]=true`, first page
   only), a search box (`q`, at most 200 characters) and newest / popular (`sort=-recentViews`),
   then `api.blogArticlesIndex({ query: { page, perPage: 12, … } })` with `Pager`. Only a `sort` the
@@ -278,6 +336,21 @@ All blog reads are `magicstore:pages`. Rules: the backend's `docs/api/v2/blog.md
     `X-Anonymous-Id`; the proxy forwards it). `ArticleView` reports `ARTICLE_VIEW`.
 - Dates render in `shop.timezone` (`ArticleDate`).
 
+## Wishlist — `app/wishlist/page.tsx`
+
+- Only with `shop.features.wishlist` (else 404); `noindex`. `useWishlist()` holds the ids (the
+  browser for a guest, the account when signed in); `components/wishlist/wishlist-view.tsx` reads
+  them with `productsIndex({ query: { 'filter[ids]': … } })` in chunks of 100 and keeps the
+  wishlist's order. A guest sees that signing in keeps the list.
+- States: empty, signed out (the hint), a product no longer for sale (dropped by the API).
+
+## Contacts — `app/contacts/page.tsx`
+
+- `api.contacts()`: phones and emails (`tel:` and `mailto:` links via `lib/contacts.ts`), the head
+  office with its hours (weekday names from `Intl`, closed days), branches with a map link,
+  requisites, socials. Nothing the shop did not fill in is shown; no contacts at all → an empty
+  state.
+
 ## Content pages, sitemap — `app/pages/[handle]/page.tsx`, `app/sitemap.ts`
 
 - `api.pagesShow({ path: { handle } })` (`magicstore:pages`) through `orNotFound`,
@@ -291,7 +364,12 @@ updatedAt }` rows — on `SITE_URL` or the shop's `primaryDomain` (`lib/site.ts`
 ## Every page
 
 - Import only the SDK's entry points; `npx create-magic-storefront check` passes.
-- Not found → `notFound()`; any other failure shows `describe(error, t.tryAgainLater)`
+- Not found → `notFound()` before anything streams: a route with a `loading.tsx` checks the
+  resource in its `layout.tsx` (see Collection), else the answer is a 200 marked `noindex`. The blog
+  index keeps its skeleton in the route group `app/blog/(index)/` so articles are not covered by it.
+- Loading: `loading.tsx` skeletons (`components/page-loading.tsx`, `components/ui/skeleton.tsx`)
+  take the final layout's sizes.
+- Any other failure shows `describe(error, t.tryAgainLater)`
   (`lib/errors.ts`) or lets `app/error.tsx` catch it (it shows `detail`, and "temporarily closed"
   on `STORE_UNAVAILABLE`).
 - The interface speaks the storefront's language: every word the storefront itself shows comes from

package/template/README.md

@@ -2,9 +2,13 @@
 
 A Next.js (App Router) storefront on the MagicStore Storefront API v2, built only on the public SDK
 (`@magicstoreai/storefront-client`, `@magicstoreai/hydrogen`). The home page from the merchant's
-sections (or your own composition: `GET /home` is optional), catalog, collections, search, product with variants, cart, checkout (pickup or delivery,
-payment), OTP sign-in and orders, SEO and JSON-LD, a webhook that revalidates cached pages — and it
-runs as a Telegram Mini App (sign-in from the bot, back button, Telegram's theme, phone sharing).
+sections (or your own composition: `GET /home` is optional), all collections, a collection and
+search with facets and sort, product with gallery, variants, reviews and recommendations, wishlist,
+cart drawer and cart page, a stepped checkout (pickup or delivery, payment), an account (OTP
+sign-in, orders with reorder and cancel, addresses, profile), blog, contacts and content pages,
+SEO and JSON-LD, a webhook that revalidates cached pages — and it runs as a Telegram Mini App
+(sign-in from the bot, back button, Telegram's theme, phone sharing). The design is a calm,
+Dawn-like theme in plain CSS with tokens; the merchant's colors and theme settings restyle it.
 
 ```bash
 cp .env.example .env.local   # set MAGICSTORE_SHOP_DOMAIN
@@ -15,6 +19,7 @@ npm run dev
 | Where                          | What                                                                          |
 | ------------------------------ | ----------------------------------------------------------------------------- |
 | `PAGES.md`                     | How each page type is built: data calls, cache tags, SEO, required states.    |
+| `DESIGN.md`                    | The design system: tokens, type, theme settings, CSS layers, UI primitives.   |
 | `lib/api.ts`                   | The server-side client. Public reads are cached under `magicstore:*` tags.    |
 | `components/sections/`         | One renderer per `GET /home` section type; an unknown type renders nothing.   |
 | `app/providers.tsx`            | `MagicStoreProvider`: customer, cart, wishlist and analytics in the browser.  |
@@ -41,3 +46,10 @@ The same secret signs the theme editor's preview links: the admin opens
 and serves the draft theme to that browser only (`lib/preview.ts`); `?exit=1` ends it. Previews also need
 `MAGICSTORE_STOREFRONT_TOKEN`, the storefront token that webhook belongs to: the API previews only a
 read that names its token.
+
+**Look before you ship.** After a visual change, build, run and screenshot every page type at 390
+and 1280px (`.claude/skills/storefront-verify/SKILL.md`); the screenshots go to `.screenshots/`,
+which git ignores.
+
+**Font.** Onest, self-hosted from `app/fonts/` (SIL Open Font License 1.1, `app/fonts/OFL.txt`), so
+builds need no network.

package/template/app/account/addresses/page.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { useMagicStore } from '@magicstoreai/hydrogen';
+import { AccountShell } from '@/components/account/account-shell';
+import { Addresses } from '@/components/account/addresses';
+import { messages } from '@/lib/i18n';
+
+export default function AddressesPage() {
+  const t = messages(useMagicStore().locale);
+  return (
+    <AccountShell>
+      <h2 className="account__section-title">{t.addresses}</h2>
+      <Addresses />
+    </AccountShell>
+  );
+}

package/template/app/account/layout.tsx

@@ -0,0 +1,14 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import { locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+// Account pages are client components; their title and robots come from here. Personal: not indexed.
+export const metadata: Metadata = {
+  title: messages(locale).account,
+  robots: { index: false, follow: false },
+};
+
+export default function AccountLayout({ children }: { children: ReactNode }) {
+  return children;
+}

package/template/app/account/loading.tsx

@@ -0,0 +1,15 @@
+import { PageLoading } from '@/components/page-loading';
+import { Skeleton, TitleSkeleton } from '@/components/ui/skeleton';
+
+export default function AccountLoading() {
+  return (
+    <PageLoading>
+      <TitleSkeleton width="30%" />
+      <div className="stack">
+        <Skeleton height="5.5rem" />
+        <Skeleton height="5.5rem" />
+        <Skeleton height="5.5rem" />
+      </div>
+    </PageLoading>
+  );
+}

package/template/app/account/orders/[id]/page.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import { useParams } from 'next/navigation';
+import { AccountShell } from '@/components/account/account-shell';
+import { OrderDetail } from '@/components/account/order-detail';
+
+/** One order. Order ids are the customer's own (another's answers `NOT_FOUND`), so the path is safe. */
+export default function OrderPage() {
+  const { id } = useParams<{ id: string }>();
+  return (
+    <AccountShell>
+      <OrderDetail id={id} />
+    </AccountShell>
+  );
+}