saleor-paper-storefront

Saleor Paper Storefront

Project-specific guide for the Saleor Paper storefront — a Next.js 16 e-commerce application with TypeScript, Tailwind CSS, and the Saleor GraphQL API. Contains 11 rules across 6 categories covering caching, PDP architecture, checkout components, UI patterns, and SEO.

Prerequisite: This skill depends on saleor-storefront for universal Saleor API knowledge (data model, permissions, checkout lifecycle, channels). Install it alongside this skill.

AI-Ready Structure

Built for front-end developers and AI agents. This skill package includes:

• AGENTS.md for architecture overview and quick reference
• rules/ with 11 task-specific rules (GraphQL, caching, variants, checkout, and more)
• .agents/skills/ compatibility for installed community skills
• Consistent patterns that make AI-assisted edits predictable

Whether you are pair-programming with Cursor, Claude, or Copilot, the structure is designed to help agents navigate and modify the codebase confidently.

When to Apply

Reference these guidelines when:

• Working on product detail pages (PDP), variant selection, or filtering
• Modifying checkout flow or payment integration
• Editing GraphQL queries or regenerating types
• Debugging caching, stale content, or revalidation
• Creating UI components with design tokens
• Adding SEO metadata, JSON-LD, or OG images
• Writing tests or investigating Saleor API behavior

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Data Layer	CRITICAL	data-
2	Product Pages	HIGH	product-
3	Checkout Flow	HIGH	checkout-
4	UI & Channels	MEDIUM	ui-
5	SEO	MEDIUM	seo-
6	Development	MEDIUM	dev-

Quick Reference

1. Data Layer (CRITICAL)

• data-caching - Cache Components (PPR), cache tags, revalidation, price flow
• data-graphql - Two codegen setups, permission patterns, nullable fields

2. Product Pages (HIGH)

• product-pdp - PDP architecture, gallery, data flow, add-to-cart, ErrorBoundary
• product-variants - Variant selection state machine, option states, discount badges
• product-filtering - Server vs client filtering, category slug resolution

3. Checkout Flow (HIGH)

• checkout-management - Checkout lifecycle, cookie storage, payment debugging
• checkout-components - Reusable checkout UI (SignInForm, AddressSelector, PaymentMethodSelector)

4. UI & Channels (MEDIUM)

• ui-components - Design tokens, shadcn/ui primitives, component locations
• ui-channels - Multi-channel URLs, fulfillment model, purchasability debugging, channel selector

5. SEO (MEDIUM)

• seo-metadata - JSON-LD structured data, metadata helpers, OG image generation

6. Development (MEDIUM)

• dev-investigation - Saleor API source code investigation methodology

How to Use

Read individual rule files for detailed explanations and code examples:

rules/data-caching.md
rules/product-variants.md

Each rule file contains:

• Brief explanation of why it matters
• File locations and architecture diagrams
• Code examples (correct and incorrect patterns)
• Anti-patterns to avoid

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md