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.

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]( step 1 project bootstrap) 2 → [Step 2: Design & Aesthetic]( step 2 design aesthetic) 3 → [Step 3: Catalog — Product List + PDP]( step 3 catalog product list pdp) If no step is provided or the step is unrecognized, print: 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: Write AGENTS.md , including only the @ references for skills that are present: 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: 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: 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: 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: If it fails with a network error, help troubleshoot (wrong URL, missing auth, etc.). 8. Summary 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 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: 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: 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 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: Price formatting Always use Intl.NumberFormat with the currency from the response — never hardcode currency symbols: 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) A

storefront-builder