# SILT SEOUL Storefront Replication Spec

Status: active case reference
Date: 2026-05-07

Use this document to recreate a SILT SEOUL-style independent brand, single-product
Shopify storefront inside the Shopify24H/Meravoq system.

The output should be a production-ready one-page store that:

- sells one product with a bundle ladder
- shares an existing Shopify backend if needed
- lives in its own private GitHub repo
- deploys to Cloudflare Pages
- hands checkout to Shopify cart permalinks
- keeps buyer-facing policies inside the branded page
- includes a complete ecommerce media pack
- implements the Shopify24H CRO Kit

## 1. Inputs

Required operator inputs:

| Input | Example |
| --- | --- |
| Product idea | Black mud mask stick |
| Market | United States |
| Supplier status | Supplier already exists |
| Shopify backend | Shared Pine & Puddle Shopify store |
| Brand mode | Independent brand |
| Storefront repo | Private GitHub project |
| Traffic plan | Meta-first paid traffic |

Default assumptions:

- English-first storefront.
- Selective non-English packaging cues are allowed if they support positioning.
- One product, three paid offers: single, two-pack, three-pack.
- Shopify is the commerce source of truth.
- Cloudflare/Next storefront is the conversion surface.

## 2. Artifact Map

The SILT SEOUL implementation used this structure:

```text
silt-seoul-storefront/
  app/
    layout.tsx
    page.tsx
    globals.css
  components/
    brand-logo.tsx
    cro-page-tracker.tsx
    cro-provider.tsx
    purchase-panel.tsx
    tracked-checkout-link.tsx
  data/
    media-pack.json
  docs/
    CRO_KIT.md
    MERAVOQ_LAUNCH.md
  exports/
    cro-contract-check.json
    cro-runtime-smoke.json
    shopify-draft-payload.json
    shopify-draft-result.json
    shopify-media-result.json
    storefront-checkout-smoke.json
  lib/
    cro.ts
    product.ts
  public/
    media/ecommerce/
  scripts/
    load-env.mjs
    seed-shopify-draft.mjs
    shopify-media-pack.mjs
    silt-seoul-catalog.mjs
    smoke-cro-runtime.mjs
    smoke-storefront-checkout.mjs
    validate-cro.mjs
```

## 3. Brand Packet

Create `lib/product.ts` as the single source of storefront truth.

Required fields:

- `brand`
- `brandHangul` or equivalent selective packaging cue
- `title`
- `handle`
- `vendor`
- `productType`
- `koreanLine` or equivalent subline
- `heroHeadline`
- `heroBody`
- `seoTitle`
- `seoDescription`
- `ingredients`
- `variants`
- `testimonials`
- `ritual`
- `policies`
- `legalLinks`
- `faq`

Variant ladder shape:

```ts
variants: [
  {
    id: "single",
    title: "Single Stick",
    subtitle: "Try the ritual",
    quantity: 1,
    price: "24",
    compareAtPrice: "32",
    perStick: "24.00",
    savings: "Save $8",
    badge: "First drop",
    checkoutLabel: "Checkout single",
    cartPermalink: "https://{shop}.myshopify.com/cart/{variant_id}:1",
  },
  {
    id: "two-pack",
    title: "Two Stick Reset",
    quantity: 2,
    price: "39",
    compareAtPrice: "64",
    perStick: "19.50",
    savings: "Save $25",
    cartPermalink: "https://{shop}.myshopify.com/cart/{variant_id}:1",
  },
  {
    id: "three-pack",
    title: "Three Stick Drop",
    quantity: 3,
    price: "54",
    compareAtPrice: "96",
    perStick: "18.00",
    savings: "Save $42",
    featured: true,
    cartPermalink: "https://{shop}.myshopify.com/cart/{variant_id}:1",
  },
]
```

Claim boundary:

- Allowed: cosmetic, visible routine, absorbs excess oil, surface buildup,
  smoother-looking after rinse, mess-free ritual.
- Blocked: cures acne, removes blackheads permanently, shrinks pores
  permanently, treats skin disease, detoxes blood or body.

## 4. Ecommerce Media Pack

Do not mark the store built until the media pack exists.

Minimum square assets:

| Asset ID | Role |
| --- | --- |
| `01-main-packshot` | main product packshot |
| `02-open-stick-angle` | open product detail |
| `03-texture-closeup` | formula or texture close-up |
| `04-bundle-offer` | bundle or offer image |
| `05-primary-model-application` | primary model application |
| `06-secondary-model-routine` | secondary model or routine context |
| `07-ingredients-flatlay` | ingredients, ritual, or flat lay |
| `product-stick-cutout` | transparent product cutout for selectors |

`data/media-pack.json` must include:

- `id`
- `src`
- `file`
- `alt`
- role/category if useful

Variant selectors should use clean product-only cutouts, not text-heavy bundle
graphics.

## 5. Shopify Product Backend

Create a Shopify catalog script equivalent to `scripts/silt-seoul-catalog.mjs`.

Required product write:

- product title, handle, vendor, type
- HTML description
- tags
- SEO title/description
- product option for the offer ladder
- three variants with SKU, price, compare-at price
- metafields for subtitle, benefits, included items, ingredients, fit, ritual

Execution sequence:

```bash
npm run seed:shopify:draft
npm run shopify:media-pack
npm run smoke:checkout
```

Evidence files:

- `exports/shopify-draft-payload.json`
- `exports/shopify-draft-result.json`
- `exports/shopify-media-result.json`
- `exports/storefront-checkout-smoke.json`

## 6. One-Page Storefront

The first screen must be the store, not a landing page about the store.

Required sections:

1. sticky topbar with brand lockup, anchors, and checkout
2. product gallery
3. purchase column with hero copy, price, countdown, proof stats, offer ladder
4. testimonial grid
5. ritual/use section
6. model or product context images
7. FAQ
8. internal policy section
9. footer policy anchors

Policy rule:

Refund Policy, Privacy Policy, Terms of Service, and Contact links should point
to internal anchors unless a deliberate branded external policy surface exists.
They should not leak to the shared source Shopify storefront.

Offer ladder behavior:

- inactive offers are compact
- selected offer expands
- selected offer contains unit economics, savings, and checkout button
- inactive checkout links are not keyboard-focusable
- offer visuals match selected quantity

## 7. CRO Kit

Implement `lib/cro.ts` and the three client components:

- `components/cro-provider.tsx`
- `components/cro-page-tracker.tsx`
- `components/tracked-checkout-link.tsx`

Required events:

- `view_page`
- `view_product`
- `view_offer`
- `select_variant`
- `click_checkout`
- `scroll_depth`
- `view_faq`
- `view_policy`
- `countdown_seen`
- `experiment_exposure`

Required public env vars:

```bash
NEXT_PUBLIC_CRO_COLLECTOR_URL=
NEXT_PUBLIC_CRO_DEBUG=0
NEXT_PUBLIC_GA_MEASUREMENT_ID=
NEXT_PUBLIC_META_PIXEL_ID=
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=
NEXT_PUBLIC_TIKTOK_PIXEL_ID=
```

Provider behavior:

- Always push to `window.siltCROEvents`.
- Always push to `window.dataLayer`.
- Optional adapters may fan out to Meta Pixel, GA4, TikTok Pixel, PostHog, and a
  collector URL.
- Do not hardcode provider IDs.

Checkout behavior:

- preserve UTM and ad IDs
- append `anonymous_id` and `session_id`
- append `cro_store_id` and `cro_launch_id`
- append selected offer id, quantity, and CTA position
- duplicate these as Shopify `attributes[key]` query parameters

Purchase bridge:

The one-page storefront owns pre-checkout events. Shopify customer events, the
Facebook & Instagram by Meta app, GA4, or an approved Shopify pixel path owns
purchase tracking.

## 8. QA Contract

Required commands:

```bash
npm run cro:check
npm run lint
npm run build
npm run cro:smoke
npm run smoke:checkout
```

What they prove:

| Command | Proof |
| --- | --- |
| `npm run cro:check` | Source contract includes events, provider adapters, UTM handoff, cart attributes, and docs. |
| `npm run lint` | React/Next rules pass. |
| `npm run build` | Static export compiles and type-checks. |
| `npm run cro:smoke` | Headless Chromium emits runtime events and verifies checkout URL attribution. |
| `npm run smoke:checkout` | Shopify Storefront API can create a checkout cart. |

Evidence:

- `exports/cro-contract-check.json`
- `exports/cro-runtime-smoke.json`
- `exports/storefront-checkout-smoke.json`

## 9. Deployment

Use a private GitHub repo per brand.

Recommended deployment:

```bash
npm run build
wrangler pages deploy out --project-name {brand-slug}-storefront --branch main
```

Push to GitHub after checks pass. If GitHub Actions deploys Cloudflare Pages,
verify the run and then live-smoke the production URL.

## 10. Agent Done Definition

A local agent can mark the store replication complete only when:

- product data and Shopify variant ladder are present
- media pack and cutout assets are present
- storefront has all required one-page sections
- checkout links use tracked cart permalinks
- policies are internal to the branded page
- CRO events and provider adapters exist
- UTM and Shopify cart attributes are verified in runtime smoke
- Shopify checkout smoke passes
- docs include claim boundary, CRO, and launch QA
- commit and push are complete