Storefront Builder

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: ``bash 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.