storefront-builder

name	storefront-builder
description	Saleor storefront data + UX playbook. Covers GraphQL query design, channel handling, data contracts per surface (PLP/PDP/nav/pricing/availability/media), variant-selection UX, and Saleor-specific correctness rules. Framework-agnostic — agent inspects repo and applies conventions locally.
license	MIT
metadata	{"author":"saleor","version":"2.0.0"}

Saleor Storefront Playbook

This skill owns Saleor data contracts and UX/data-layer behaviour. It does not own framework scaffolding, CSS setup, or env-loading specifics — the agent discovers those from the local project.

Parse $ARGUMENTS to determine which step to run.

Step routing

Read the first word of $ARGUMENTS as the step number and jump to that section. Execute only that step, then stop and wait for the user to ask for the next one. Never chain steps automatically.

• 1 → Step 1: Project Bootstrap
• 2 → Step 2: Design & Aesthetic
• 3 → Step 3: Catalog — Product List + PDP

If no step is provided or the step is unrecognized, print:

Saleor Storefront Builder

Usage: /storefront-builder <step>

Steps:
  1   Bootstrap — wire GraphQL client, codegen, Saleor API connection
  2   Design & aesthetic — color palette, typography, accent color
  3   Catalog — product list page + product detail page with variant selection

Example: /storefront-builder 1

---

Step 1: Project Bootstrap

Connect an existing project to Saleor's GraphQL API with correct client separation and codegen.

0. Saleor instance check

Ask the user:

"Do you have a Saleor instance ready?

• No — create one at https://cloud.saleor.io/ (free tier available), then come back with the API URL.
• Yes — paste your storefront/API URL and we'll get started."

Wait for the user's response before continuing. If they don't have an instance yet, stop here and let them set one up. If they provide a URL, note it for use in step 6.

1. Inspect the project

Read package.json and any framework config files present (nuxt.config.ts, next.config.*, svelte.config.js, remix.config.js, vite.config.*, etc.) to understand:

• Framework and version
• Package manager in use (check for lockfiles: pnpm-lock.yaml, yarn.lock, package-lock.json)
• Existing GraphQL setup (if any)
• Import alias conventions (e.g. @/, ~/, #)
• Source directory layout (src/, app/, flat root)

Do not ask about any of the above — derive it from the project. Only ask if something cannot be determined and is needed to proceed.

2. Create AGENTS.md

If AGENTS.md does not already exist at the repo root, create it now. This wires Saleor-specific rules into the AI harness for all future interactions in this repo.

Check for installed skills:

ls .agent-skills/saleor-storefront/AGENTS.md 2>/dev/null && echo "STOREFRONT" || echo ""
ls .agent-skills/saleor-configurator/AGENTS.md 2>/dev/null && echo "CONFIGURATOR" || echo ""

Write AGENTS.md, including only the @ references for skills that are present:

# Saleor Storefront

This is a Saleor-powered storefront.

## Workflow

When running `/storefront-builder`, execute only the requested step, then stop and wait for the user to ask for the next one. Never chain steps automatically.

## Saleor rules

<!-- include if .agent-skills/saleor-storefront/ exists -->
@.agent-skills/saleor-storefront/AGENTS.md

<!-- include if .agent-skills/saleor-configurator/ exists -->
@.agent-skills/saleor-configurator/AGENTS.md

If AGENTS.md already exists, skip this step entirely — do not overwrite it.

3. Install GraphQL dependencies

Using the package manager detected in step 1:

graphql-request graphql
@graphql-codegen/cli @graphql-codegen/client-preset  (dev)

4. Create codegen config

Write a codegen config file at the project root (filename: codegen.ts or codegen.js based on project conventions). Key values to set:

• schema: Saleor GraphQL API URL, read from the env variable the project uses (or SALEOR_API_URL if none is established)
• documents: glob pointing to the project's GraphQL files directory, following local conventions
• generates: use the client preset with gqlTagName: "graphql"

Add a codegen script to package.json.

5. Create Saleor API clients

Two-client pattern — this is a Saleor correctness rule, not optional:

Write a client module in the location that matches the project's library/util conventions. Export two clients:

saleorClient      — anonymous, no auth headers — safe for RSC, SSG, public product queries
saleorAuthClient  — server-only, reads app token from env — NEVER use in browser bundles

Why two clients matter: passing an app token on public/cached queries leaks privileged access and can expose customer data. Anonymous queries must stay anonymous.

The auth client should only include the Authorization header when the token env var is set (guard with a conditional so the module doesn't throw on front-end environments where the var is absent).

6. Configure environment

Determine the env variable naming convention from the project (e.g. Next.js uses NEXT_PUBLIC_* for browser-accessible vars, Nuxt uses NUXT_PUBLIC_*, etc.).

Required variables:

• [PUBLIC_PREFIX]_SALEOR_API_URL — Saleor GraphQL endpoint
• [PUBLIC_PREFIX]_SALEOR_CHANNEL — default channel slug
• SALEOR_APP_TOKEN (no public prefix — server-side only)

Write or update the project's env file (.env.local, .env, etc.) with placeholder values and comments. Ask the user if they have a Saleor API URL and channel slug to fill in.

Tip — inspecting an existing store with Configurator If you have access to an existing Saleor instance and are unsure what channels, categories, or products are configured, use the Configurator CLI:

export SALEOR_URL=https://your-store.saleor.cloud/graphql/
export SALEOR_TOKEN=YOUR_TOKEN
pnpm dlx @saleor/configurator introspect

Read the resulting config.yml to find exact channel slugs, published products, and category structure — use these values directly in env and queries.

7. Verify

If the API URL is configured, run codegen to confirm the schema is reachable:

[package-manager] codegen 2>&1 | head -20

If it fails with a network error, help troubleshoot (wrong URL, missing auth, etc.).

8. Summary

[✓/–] AGENTS.md: [created / already existed]
✓ Framework: [detected framework]
✓ Package manager: [pm]
✓ Deps: graphql-request, @graphql-codegen/cli, @graphql-codegen/client-preset
✓ Clients: [path] (public + authenticated)
✓ Codegen: codegen.ts
[✓/⚠] API URL: [set / not set]
[✓/⚠] Channel: [slug / placeholder]

Next: /storefront-builder 2

After printing the summary, stop. Do not proceed to Step 2 unless the user explicitly asks.

---

Step 2: Design & Aesthetic

Define the visual identity of the storefront before writing any UI code. The output of this step is a theme module and design tokens that all future steps will import. The exact file paths and token format follow the project's existing conventions.

1. Inspect the project's styling setup

Read the project to determine:

• CSS framework in use (Tailwind, CSS Modules, styled-components, UnoCSS, vanilla CSS, etc.)
• Existing design token conventions (CSS custom properties, a theme.* file, Tailwind config, etc.)
• Where shared styles live

Do not assume Tailwind or any specific CSS approach — derive it from the project.

2. Ask about the aesthetic

Ask the user three questions in one message — conversational, not a form:

"Let's define the look of your storefront. A few quick questions:

1. Do you have any references? (a brand, a URL, a screenshot — or skip)
2. What's the general vibe? Some starting points if helpful: minimalist light, dark luxury, bold & colorful, soft & warm, classic editorial — or describe it in your own words.
3. Any accent color in mind? This goes on buttons and links. A hex, a color name, or leave it to me."

If the user gives very little, ask one follow-up before proceeding.

3. Decide on tokens

Determine values for: background, surface, border, text primary, text secondary, accent, accent-hover, border radius, heading font, body font.

4. Write theme tokens

Write a theme module in a location consistent with the project's conventions. Include a comment block capturing:

• Style preset name
• Reference (if any)
• Accent rationale
• Typography choice

Wire the tokens into the project's styling system following local conventions:

• Tailwind: extend tailwind.config.* with the token values
• CSS custom properties: write to the project's global CSS file
• Other: follow what's already in use

Update the global/base CSS to apply background and text defaults.

5. Summary

✓ Style: [preset name]
✓ Accent: [color]
✓ Typography: [font choice]
✓ Theme tokens: [path]
✓ Styling system updated: [tailwind.config / globals.css / etc.]

Next: /storefront-builder 3

After printing the summary, stop. Do not proceed to Step 3 unless the user explicitly asks.

---

Step 3: Catalog — Product List + PDP

Build a product listing page and product detail page with variant selection.

Prerequisites check

Verify the Saleor client module exists (search for it based on what was set up in Step 1). If missing, tell the user to run /storefront-builder 1 first.

Check for a channel slug in the project's env file. If missing and not passed as argument, ask:

"What's your Saleor channel slug? (Saleor Dashboard → Channels, or press Enter for 'default-channel')"

Inspect the framework and routing conventions from the project to determine where to write pages and how data-fetching works (server components, getStaticProps, loaders, load functions, asyncData, etc.).

1. GraphQL queries — Saleor data contracts

Write a products.graphql file in the project's GraphQL documents directory.

ProductCard fragment

Required fields for a product listing surface:

fragment ProductCard on Product {
  id
  name
  slug
  thumbnail {
    url
    alt
  }
  pricing {
    priceRange {
      start {
        gross {
          amount
          currency
        }
      }
    }
  }
  category {
    name
    slug
  }
}

Why these fields:

• thumbnail is nullable — always guard with a fallback image or placeholder
• pricing.priceRange.start is nullable — guard before rendering price
• category is nullable — guard before rendering category label

ProductDetails fragment

Required fields for a PDP surface:

fragment ProductDetails on Product {
  id
  name
  slug
  description
  thumbnail {
    url
    alt
  }
  media {
    url
    alt
    type
  }
  pricing {
    priceRange {
      start {
        gross {
          amount
          currency
        }
      }
    }
  }
  category {
    name
    slug
  }
  variants {
    id
    name
    sku
    pricing {
      price {
        gross {
          amount
          currency
        }
      }
      priceUndiscounted {
        gross {
          amount
          currency
        }
      }
    }
    selectionAttributes: attributes(variantSelection: VARIANT_SELECTION) {
      attribute {
        name
        slug
      }
      values {
        name
        slug
      }
    }
    quantityAvailable
  }
}

Why these fields:

• media array preferred over thumbnail on PDP — use thumbnail as fallback when media is empty
• variants.pricing is nullable — guard before accessing amount
• quantityAvailable is nullable for anonymous users — treat null as in-stock (behave as if 1 available)
• selectionAttributes uses variantSelection: VARIANT_SELECTION filter — returns only variant-differentiating attributes (size, color, etc.), not product-level attributes

Queries

query ProductList($channel: String!, $first: Int = 20, $after: String) {
  products(channel: $channel, first: $first, after: $after) {
    edges {
      node {
        ...ProductCard
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

query ProductBySlug($slug: String!, $channel: String!) {
  product(slug: $slug, channel: $channel) {
    ...ProductDetails
  }
}

Channel is always required — queries without channel return no pricing or availability data.

Run codegen after writing the queries.

2. Saleor data handling rules

Apply these rules when implementing the pages and components:

Description parsing

Saleor stores description as EditorJS JSON. Never render it raw. Parse safely:

function extractDescriptionText(description: unknown): string {
  try {
    const parsed = typeof description === "string" ? JSON.parse(description) : description;
    return parsed?.blocks
      ?.map((b: { data?: { text?: string } }) => b.data?.text ?? "")
      .filter(Boolean)
      .join(" ") ?? "";
  } catch {
    return "";
  }
}

Price formatting

Always use Intl.NumberFormat with the currency from the response — never hardcode currency symbols:

function formatPrice(amount: number, currency: string) {
  return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(amount);
}

Use undefined locale to respect the user's browser locale (or pass a locale if the project has a locale system).

Image handling

• On PDP: prefer product.media[0] over thumbnail; fall back to thumbnail if media is empty
• Always guard for missing images — render a neutral placeholder, not a broken <img> tag
• Use alt ?? product.name as the alt text fallback

Inventory / availability semantics

• quantityAvailable === null → treat as available (anonymous users don't see inventory)
• quantityAvailable === 0 → out of stock — disable selection and show visual indicator (strikethrough or muted)
• quantityAvailable > 0 → in stock

Variant selection UX

• Show all variants; disable (not hide) out-of-stock ones — visibility helps users understand what exists
• Use selectionAttributes to label variants (e.g. "Size: M", "Color: Red") when attributes are present
• If a product has only one variant and no selection attributes, skip the selector and go straight to Add to Cart
• The selected variant's pricing.price overrides the product-level pricing.priceRange — update the displayed price on selection

Empty / error states

• Product list with no results: show a clear message with troubleshooting hint (wrong channel slug or products not published)
• Product not found (null from ProductBySlug): use the framework's not-found/404 mechanism
• Pricing missing: omit price entirely rather than showing $0 or NaN

3. Write shared navigation

Write a nav/header component in the project's component directory following local naming conventions. The nav should use the theme tokens established in Step 2 (or sensible neutral defaults if Step 2 was skipped).

Wire the nav into the root layout / app shell following framework conventions detected from the project.

4. Write product list page

Write the product list page at the path that fits the project's routing conventions (e.g. app/page.tsx, pages/index.tsx, pages/index.vue, src/routes/+page.svelte, app/routes/_index.tsx).

Data-fetching pattern: use whatever the framework provides (async server component, getStaticProps/ISR, load function, asyncData, Remix loader). For SSG-capable frameworks, set a reasonable revalidation interval (e.g. 60s).

Apply all data handling rules from section 2: guard nullables, format prices correctly, show empty state.

5. Write PDP

Write the PDP at the path that fits routing conventions (e.g. app/p/[slug]/page.tsx, pages/p/[slug].tsx, pages/p/[slug].vue, src/routes/p/[slug]/+page.svelte).

Apply all data handling rules from section 2.

6. Write VariantSelector component

Write a VariantSelector component in the project's component directory. It must be client-interactive (use whatever interactivity primitive the framework provides — React state, Vue ref, Svelte store, etc.).

Behaviour:

• Shows all variants; disables out-of-stock ones (do not hide them)
• Highlights selected variant
• Updates displayed price when a variant is selected (variant pricing.price takes precedence)
• Add to Cart button is disabled until a variant is selected (when selection is required)
• Single-variant / no-attribute products: skip selector, show Add to Cart directly
• Add to Cart is non-functional at this step — placeholder only, note this clearly in a comment

7. Run and verify

Start the dev server using the project's dev command. Direct the user to the product list and a PDP URL to confirm data loads correctly.

Common issues:

• Empty list: wrong channel slug or products not published in that channel — suggest running configurator introspect to inspect the store
• Codegen errors: API URL not set or unreachable
• Product not found on every slug: channel mismatch or product unpublished in that channel

Summary

✓ GraphQL queries: [path]/products.graphql
✓ Types generated
✓ Navigation: [path] (wired into root layout)
✓ Product list: [route]
✓ Product detail: [route]
✓ VariantSelector: [path]

Note: "Add to Cart" is present but non-functional — checkout is not covered by this skill

This is the last step currently available in this skill.

After printing the summary, stop.

---

Saleor correctness rules (always apply)

These rules apply across all steps and any future storefront work:

1. Always pass channel — every product/pricing/availability query requires it; omitting it returns no data
2. Parse description safely — it is EditorJS JSON, not plain text or HTML
3. Never expose SALEOR_APP_TOKEN to the browser — use the two-client pattern; the auth client is server-side only
4. quantityAvailable null = available — anonymous users don't receive inventory counts; null means "don't block purchase"
5. pricing is nullable at every level — guard pricing, pricing.price, pricing.priceRange, and gross before accessing amount
6. Use Intl.NumberFormat for prices — never hardcode currency symbols or assume locale
7. PDP media priority: media[0] → thumbnail → placeholder
8. Disable, don't hide, out-of-stock variants — hiding them confuses users about what the product offers