create-magic-storefront 0.1.0 → 0.1.1

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,163 @@
+---
+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.
+
+Two skills work together:
+
+- **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.
+
+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.

package/template/AGENTS.md

@@ -31,6 +31,15 @@ each error code means — then `PAGES.md` for how each page type is built, and
 - Every page handles its empty, error and not-found states (`orNotFound` turns `NOT_FOUND` into
   the 404 page).
 
+## Design
+
+Before changing how the storefront looks — a new design, a redesign, restyling a page, section or
+component — read `.claude/skills/storefront-design/SKILL.md` and follow it. It uses
+`.claude/skills/design-taste-frontend/SKILL.md` for taste and overrides it where a store differs
+from a landing page: brand colors come from `shop.branding` at runtime, product and banner images
+come only from the API, nothing is invented (prices, badges, reviews, urgency), and the cart and
+checkout stay conventional.
+
 ## Where things go
 
 | Path                           | What                                                                     |

package/template/PAGES.md

@@ -31,7 +31,10 @@ API's, not the build's. The fetch cache still spares the API.
 ## Layout — `app/layout.tsx`
 
 - Reads `api.shop()` and the navigation (`api.collectionsIndex` or `api.menusShow({ path: { handle: 'main' } })`).
-- `generateMetadata`: `shop.seo.title || shop.name`, `shop.seo.description ?? shop.description`.
+- `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
+  tokens `app/globals.css` falls back from; the header shows `shop.branding.logo` when there is one.
 - Wraps the page in `Providers` (`MagicStoreProvider` with `shop` passed in, so the browser does not
   load it again).
 

package/template/app/globals.css

@@ -3,8 +3,14 @@
   --fg: #16161a;
   --muted: #6b6b76;
   --line: #e7e7ec;
-  --accent: #1f5eff;
   --danger: #c62828;
+  /* Brand tokens: app/layout.tsx overrides them with the merchant's colors (lib/brand.ts). */
+  --accent: #1f5eff;
+  --on-accent: #fff;
+  --nav-bg: var(--bg);
+  --nav-fg: var(--fg);
+  --label-bg: var(--accent);
+  --label-fg: var(--on-accent);
   font-family:
     system-ui,
     -apple-system,
@@ -30,6 +36,8 @@ main {
 }
 header.site {
   border-bottom: 1px solid var(--line);
+  background: var(--nav-bg);
+  color: var(--nav-fg);
 }
 header.site nav {
   max-width: 1100px;
@@ -45,6 +53,11 @@ header.site .brand {
   text-decoration: none;
   margin-right: auto;
 }
+header.site .brand img {
+  display: block;
+  width: auto;
+  height: 32px;
+}
 .grid {
   display: grid;
   grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
@@ -110,7 +123,7 @@ button.primary,
 .button.primary {
   background: var(--accent);
   border-color: var(--accent);
-  color: #fff;
+  color: var(--on-accent);
 }
 button[aria-pressed='true'] {
   border-color: var(--fg);
@@ -221,8 +234,8 @@ fieldset {
   align-self: flex-start;
   padding: 2px 10px;
   border-radius: 999px;
-  background: var(--accent);
-  color: #fff;
+  background: var(--label-bg);
+  color: var(--label-fg);
 }
 .stories {
   display: flex;

package/template/app/layout.tsx

@@ -1,8 +1,10 @@
 import type { Metadata } from 'next';
 import Link from 'next/link';
 import type { ReactNode } from 'react';
+import { Image } from '@magicstoreai/hydrogen';
 import { CartLink } from '@/components/cart-link';
 import { api, locale } from '@/lib/api';
+import { brandStyle } from '@/lib/brand';
 import { Providers } from './providers';
 import './globals.css';
 
@@ -15,6 +17,7 @@ export async function generateMetadata(): Promise<Metadata> {
   return {
     title: shop.seo.title || shop.name,
     description: shop.seo.description ?? shop.description,
+    icons: shop.branding.favicon ? { icon: shop.branding.favicon.url } : undefined,
   };
 }
 
@@ -26,13 +29,18 @@ export default async function RootLayout({ children }: { children: ReactNode })
   ]);
 
   return (
-    <html lang={locale}>
+    // The merchant's colors, read per request: a change in the admin shows after SHOP_UPDATED.
+    <html lang={locale} style={brandStyle(shop.branding)}>
       <body>
         <Providers shop={shop}>
           <header className="site">
             <nav>
               <Link href="/" className="brand">
-                {shop.name}
+                {shop.branding.logo ? (
+                  <Image data={shop.branding.logo} alt={shop.name} height={32} loading="eager" />
+                ) : (
+                  shop.name
+                )}
               </Link>
               {collections.map((collection) => (
                 <Link key={collection.id} href={`/collections/${collection.handle}`}>

package/template/components/product-grid.tsx

@@ -2,6 +2,29 @@ import { Image, Money } from '@magicstoreai/hydrogen';
 import type { Schema } from '@magicstoreai/storefront-client';
 import Link from 'next/link';
 
+/** Badges come only from the product's data; at most two, so the card stays readable. */
+function ProductBadges({ product }: { product: Schema<'Product'> }) {
+  const badges = [
+    product.preOrder && 'Pre-order',
+    product.compareAtPrice && 'Sale',
+    product.isNew && 'New',
+  ]
+    .filter((badge): badge is string => typeof badge === 'string')
+    .slice(0, 2);
+  if (badges.length === 0) {
+    return null;
+  }
+  return (
+    <span className="row">
+      {badges.map((badge) => (
+        <span key={badge} className="badge">
+          {badge}
+        </span>
+      ))}
+    </span>
+  );
+}
+
 export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
   if (products.length === 0) {
     return <p className="muted">Nothing here yet.</p>;
@@ -15,6 +38,7 @@ export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
             alt={product.title}
             fallback={<div className="noimg" />}
           />
+          <ProductBadges product={product} />
           <span>{product.title}</span>
           <span className="row">
             <Money data={product.price} fallback={<span className="muted">—</span>} />

package/template/lib/brand.ts

@@ -0,0 +1,60 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+import type { CSSProperties } from 'react';
+
+type Branding = Schema<'Shop'>['branding'];
+
+/** `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`. The admin stores colors as free text; nothing else is trusted. */
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+function hexColor(value: string | null): string | null {
+  return value !== null && HEX_COLOR.test(value) ? value : null;
+}
+
+/** WCAG relative luminance of a hex color; alpha is ignored. */
+function luminance(hex: string): number {
+  const digits = hex.slice(1);
+  const channels =
+    digits.length <= 4
+      ? [0, 1, 2].map((i) => parseInt(digits[i]! + digits[i]!, 16))
+      : [0, 2, 4].map((i) => parseInt(digits.slice(i, i + 2), 16));
+  const [r, g, b] = channels.map((channel) => {
+    const c = channel / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!;
+}
+
+/** Black or white, whichever contrasts more with the background. */
+export function readableTextOn(background: string): '#000' | '#fff' {
+  const l = luminance(background);
+  const onBlack = (l + 0.05) / 0.05;
+  const onWhite = 1.05 / (l + 0.05);
+  return onBlack >= onWhite ? '#000' : '#fff';
+}
+
+/**
+ * The merchant's colors as CSS custom properties for `<html style>`. A color the merchant didn't
+ * set is left out, so the design's fallback in `globals.css` applies; a text color the merchant
+ * didn't set is picked for contrast against its background.
+ */
+export function brandStyle(branding: Branding): CSSProperties {
+  const { colors } = branding;
+  const tokens: Record<string, string> = {};
+  const pair = (name: string, background: string | null, text: string | null) => {
+    const bg = hexColor(background);
+    if (bg === null) {
+      return;
+    }
+    tokens[`--${name}-bg`] = bg;
+    tokens[`--${name}-fg`] = hexColor(text) ?? readableTextOn(bg);
+  };
+
+  const accent = hexColor(colors.main);
+  if (accent !== null) {
+    tokens['--accent'] = accent;
+    tokens['--on-accent'] = hexColor(colors.buttonText) ?? readableTextOn(accent);
+  }
+  pair('nav', colors.navbarBackground, colors.navbarText);
+  pair('label', colors.labelBackground, colors.labelText);
+  return tokens as CSSProperties;
+}