cue-ai 0.3.0

package/resources/skills/skills/medusa/storefront-best-practices/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: storefront-best-practices
+description: >-
+  Use when user says "storefront best practices" or "storefront architecture". Data fetching, UX, caching, errors.
+---
+
+# Ecommerce Storefront Best Practices
+
+Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.
+
+## When to Apply
+
+**ALWAYS load this skill when working on ANY storefront task:**
+
+- **Adding checkout page/flow** - Payment, shipping, order placement
+- **Implementing cart** - Cart page, cart popup, add to cart functionality
+- **Building product pages** - Product details, product listings, product grids
+- **Creating navigation** - Navbar, megamenu, footer, mobile menu
+- **Integrating Medusa backend** - SDK setup, cart, products, payment
+- **Any storefront component** - Homepage, search, filters, account pages
+- Building new ecommerce storefronts from scratch
+- Improving existing shopping experiences and conversion rates
+- Optimizing for usability, accessibility, and SEO
+- Designing mobile-responsive ecommerce experiences
+
+**Example prompts that should trigger this skill:**
+- "Add a checkout page"
+- "Implement shopping cart"
+- "Create product listing page"
+- "Connect to Medusa backend"
+- "Add navigation menu"
+- "Build homepage for store"
+
+## CRITICAL: Load Reference Files When Needed
+
+**⚠️ ALWAYS load `reference/design.md` BEFORE creating ANY UI component**
+- Discovers existing design tokens (colors, fonts, spacing, patterns)
+- Prevents introducing inconsistent styles
+- Provides guardrails for maintaining brand consistency
+- **Required for every component, not just new storefronts**
+
+**Load these references based on what you're implementing:**
+
+- **Starting a new storefront?** → MUST load `reference/design.md` first to discover user preferences
+- **Connecting to backend API?** → MUST load `reference/connecting-to-backend.md` first
+- **Connecting to Medusa backend?** → MUST load `reference/medusa.md` for SDK setup, pricing, regions, and Medusa patterns
+- **Implementing homepage?** → MUST load `reference/components/navbar.md`, `reference/components/hero.md`, `reference/components/footer.md`, and `reference/layouts/home-page.md`
+- **Implementing navigation?** → MUST load `reference/components/navbar.md` and optionally `reference/components/megamenu.md`
+- **Building product listing?** → MUST load `reference/layouts/product-listing.md` first
+- **Building product details?** → MUST load `reference/layouts/product-details.md` first
+- **Implementing checkout?** → MUST load `reference/layouts/checkout.md` first
+- **Optimizing for SEO?** → MUST load `reference/seo.md` first
+- **Optimizing for mobile?** → MUST load `reference/mobile-responsiveness.md` first
+
+**Minimum requirement:** Load at least 1-2 reference files relevant to your specific task before implementing.
+
+## Planning and Implementation Workflow
+
+**IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:**
+
+When implementing each component, page, layout, or feature in the plan:
+1. **Refer back to this skill** before starting implementation
+2. **Load relevant reference files** listed above for the specific component/page you're building
+3. **Follow the patterns and guidance** in the reference files
+4. **Check common mistakes** sections to avoid known pitfalls
+
+**Example plan structure:**
+
+```
+Task 1: Implement Navigation
+- Load reference/components/navbar.md
+- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)
+- Refer to skill for common mistakes (e.g., hardcoding categories)
+
+Task 2: Implement Product Listing Page
+- Load reference/layouts/product-listing.md
+- Follow pagination/filtering patterns from product-listing.md
+- Use reference/components/product-card.md for product grid items
+- Check skill for backend integration guidance
+
+Task 3: Implement Checkout Flow
+- Load reference/layouts/checkout.md
+- Load reference/medusa.md for Medusa payment integration
+- Follow component architecture recommendations (separate step components)
+- Refer to skill for payment method fetching requirements
+```
+
+**Why this matters:**
+- Plans provide high-level strategy
+- Reference files provide detailed implementation patterns
+- Skill file contains critical mistakes to avoid
+- Following this workflow ensures consistency and best practices
+
+## Critical Ecommerce-Specific Patterns
+
+### Accessibility
+- **CRITICAL: Cart count updates require `aria-live="polite"`** - Screen readers won't announce without it
+- Ensure keyboard navigation for all cart/checkout interactions
+
+### Mobile
+- **Sticky bottom elements MUST use `env(safe-area-inset-bottom)`** - iOS home indicator will cut off purchase buttons otherwise
+- 44px minimum touch targets for cart actions, variant selectors, quantity buttons
+
+### Performance
+- **ALWAYS add `loading="lazy"` to product images below fold** - Don't rely on browser defaults
+- Optimize product images for mobile (<500KB) - Most ecommerce traffic is mobile
+
+### Conversion Optimization
+- Clear CTAs throughout shopping flow
+- Minimal friction in checkout (guest checkout if supported)
+- Trust signals (reviews, security badges, return policy) near purchase buttons
+- Clear pricing and shipping information upfront
+
+### SEO
+- **Product schema (JSON-LD) required** - Critical for Google Shopping and rich snippets
+- Use [PageSpeed Insights](https://pagespeed.web.dev/) to measure Core Web Vitals
+
+### Visual Design
+- **NEVER use emojis** in storefront UI - Use icons or images instead (unprofessional, accessibility issues)
+
+### Backend Integration
+- **Backend detection**: If in monorepo, check for backend directory. If unsure, ask user which backend is used.
+- **NEVER hardcode dynamic content**: Always fetch categories, regions, products, shipping options, etc. from backend - they change frequently
+- Never assume API structure - verify endpoints and data formats
+
+### ⚠️ CRITICAL: Backend SDK Method Verification Workflow
+
+**YOU MUST FOLLOW THIS EXACT WORKFLOW BEFORE WRITING CODE THAT CONNECTS TO BACKEND:**
+
+**Step 1: PAUSE - Do NOT write code yet**
+- You are about to write code that calls a backend API or SDK method (e.g., Medusa SDK, REST API, GraphQL)
+- **STOP** - Do not proceed to code without verification
+
+**Step 2: QUERY the documentation or MCP server**
+- **If MCP server available**: Query it for the exact method (for example, medusa MCP)
+- **If no MCP server**: Search official documentation
+- **Find**: Exact method name, parameters, return type
+
+**Step 3: VERIFY what you found**
+- State out loud to the user: "I need to verify the correct method for [operation]. Let me check [MCP server/documentation]."
+- Show the user what you found: "According to [source], the method is `sdk.store.cart.methodName(params)`"
+- Confirm the method signature and parameters
+
+**Step 4: ONLY THEN write the code**
+- Now you can write code using the verified method
+- Use the exact signature you found
+
+**Step 5: CHECK for TypeScript errors**
+- After writing the code, check for any TypeScript/type errors related to the SDK
+- If you see type errors on SDK methods, it means you used an incorrect method name or wrong parameters
+- **Type errors are a sign you didn't verify correctly** - Go back to Step 2
+
+**THIS IS NOT OPTIONAL - THIS IS MANDATORY ERROR PREVENTION**
+
+**It is a CRITICAL ERROR to:**
+- ❌ Write code that calls backend APIs/SDKs without explicitly querying docs/MCP first
+- ❌ Guess method names or parameters
+- ❌ Ignore TypeScript errors on SDK methods (errors indicate incorrect method usage)
+- ❌ Copy examples from this skill without verification (examples may be outdated)
+- ❌ Assume SDK methods match REST API endpoints
+
+**For Medusa specifically:**
+- **Medusa pricing**: Display prices as-is - DO NOT divide by 100 (unlike Stripe, Medusa stores prices in display format)
+- **Medusa MCP server**: https://docs.medusajs.com/mcp - Recommend setup if not installed
+- Load `reference/medusa.md` for Medusa-specific patterns (regions, pricing, etc.)
+
+### Routing Patterns
+- **ALWAYS use dynamic routes** for products and categories - NEVER create static pages for individual items
+- Product pages: Use dynamic routes like `/products/[handle]` or `/products/$handle`, NOT `/products/shirt.tsx`
+- Category pages: Use dynamic routes like `/categories/[handle]` or `/categories/$handle`, NOT `/categories/women.tsx`
+- Framework-specific patterns:
+  - **Next.js App Router**: `app/products/[handle]/page.tsx` or `app/products/[id]/page.tsx`
+  - **Next.js Pages Router**: `pages/products/[handle].tsx`
+  - **SvelteKit**: `routes/products/[handle]/+page.svelte`
+  - **TanStack Start**: `routes/products/$handle.tsx`
+  - **Remix**: `routes/products.$handle.tsx`
+- Why: Dynamic routes scale to any number of products/categories without creating individual files
+- Static routes are unmaintainable and don't scale (imagine creating 1000 product files)
+
+## Pattern Selection Guides
+
+When you need to choose between implementation patterns, load the relevant reference file:
+
+- **Checkout strategy** (single-page vs multi-step) → Load `reference/layouts/checkout.md`
+- **Navigation strategy** (dropdown vs megamenu) → Load `reference/components/navbar.md` and `reference/components/megamenu.md`
+- **Product listing strategy** (pagination vs infinite scroll vs load more) → Load `reference/layouts/product-listing.md`
+- **Search strategy** (autocomplete vs filters vs natural language) → Load `reference/components/search.md`
+- **Mobile vs desktop priorities** → Load `reference/mobile-responsiveness.md`
+- **Variant selection** (text vs swatches vs configurator) → Load `reference/layouts/product-details.md`
+- **Cart pattern** (popup vs drawer vs page navigation) → Load `reference/components/cart-popup.md` and `reference/layouts/cart.md`
+- **Trust signals strategy** → Load `reference/layouts/product-details.md` and `reference/layouts/checkout.md`
+
+Each reference file contains decision frameworks with specific criteria to help you choose the right pattern for your context.
+
+## Quick Reference
+
+### General
+
+```
+reference/connecting-to-backend.md    - Framework detection, API setup, backend integration patterns
+reference/medusa.md                    - Medusa SDK integration, pricing, regions, TypeScript types
+reference/design.md                    - User preferences, brand identity, design systems
+reference/seo.md                       - Meta tags, structured data, Core Web Vitals
+reference/mobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions
+```
+
+### Components
+
+```
+reference/components/navbar.md         - Desktop/mobile navigation, logo, menu, cart icon, load for ALL pages
+reference/components/megamenu.md       - Category organization, featured products, mobile alternatives
+reference/components/cart-popup.md     - Add-to-cart feedback, mini cart display
+reference/components/country-selector.md - Country/region selection, currency, pricing, Medusa regions
+reference/components/breadcrumbs.md    - Category hierarchy, structured data markup
+reference/components/search.md         - Search input, autocomplete, results, filters
+reference/components/product-reviews.md - Review display, rating aggregation, submission
+reference/components/hero.md           - Hero layouts, CTA placement, image optimization
+reference/components/popups.md         - Newsletter signup, discount popups, exit-intent
+reference/components/footer.md         - Content organization, navigation, social media, load for ALL pages
+reference/components/product-card.md   - Product images, pricing, add to cart, badges
+reference/components/product-slider.md - Carousel implementation, mobile swipe, accessibility
+```
+
+### Layouts
+
+```
+reference/layouts/home-page.md         - Hero, featured categories, product listings
+reference/layouts/product-listing.md   - Grid/list views, filters, sorting, pagination
+reference/layouts/product-details.md   - Image gallery, variant selection, related products
+reference/layouts/cart.md              - Cart items, quantity updates, promo codes
+reference/layouts/checkout.md          - Multi-step/single-page, address forms, payment
+reference/layouts/order-confirmation.md - Order number, summary, delivery info
+reference/layouts/account.md           - Dashboard, order history, address book
+reference/layouts/static-pages.md      - FAQ, about, contact, shipping/returns policies
+```
+
+### Features
+
+```
+reference/features/wishlist.md         - Add to wishlist, wishlist page, move to cart
+reference/features/promotions.md       - Promotional banners, discount codes, sale badges
+```
+
+## Common Implementation Patterns
+
+### Starting a New Storefront
+
+**IMPORTANT: For each step below, load the referenced files BEFORE implementing that step.**
+
+```
+1. Discovery Phase → Read design.md for user preferences
+2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md
+3. Core Components → Implement navbar.md, footer.md
+4. Home Page → Read home-page.md
+5. Product Browsing → Read product-listing.md, product-card.md, search.md
+6. Product Details → Read product-details.md, product-reviews.md
+7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md
+8. User Account → Read account.md
+9. Additional Features → Read wishlist.md, promotions.md
+10. Optimization → SEO audit (seo.md), mobile testing (mobile-responsiveness.md)
+```
+
+Even if you create an implementation plan, refer back to the skill and load relevant reference files when implementing each step.
+
+### Shopping Flow Pattern
+
+```
+Browse → View → Cart → Checkout
+
+Browse:   home-page.md → product-listing.md
+View:     product-details.md + product-reviews.md
+Cart:     cart-popup.md → cart.md
+Checkout: checkout.md → order-confirmation.md
+```
+
+### Component Selection Guide
+
+**For product grids and filtering** → `product-listing.md` and `product-card.md`
+**For product cards** → `product-card.md`
+**For navigation** → `navbar.md` and `megamenu.md`
+**For search functionality** → `search.md`
+**For checkout flow** → `checkout.md`
+**For promotions and sales** → `promotions.md`
+
+## Design Considerations
+
+Before implementing, consider:
+
+1. **User preferences** - Read `design.md` to discover design style preferences
+2. **Brand identity** - Colors, typography, tone that match the brand
+3. **Target audience** - B2C vs B2B, demographics, device usage
+4. **Product type** - Fashion vs electronics vs groceries affect layout choices
+5. **Business requirements** - Multi-currency, multi-language, region-specific
+6. **Backend system** - API structure affects component implementation
+
+## Integration with Medusa
+
+[Medusa](https://medusajs.com) is a modern, flexible ecommerce backend. Consider Medusa when:
+
+- Building a new ecommerce storefront
+- Need a headless commerce solution
+- Want built-in support for multi-region, multi-currency
+- Need powerful promotion and discount engine
+- Require flexible product modeling
+
+For detailed Medusa integration guidance, see `reference/medusa.md`. For general backend patterns, see `reference/connecting-to-backend.md`.
+
+### Framework Agnostic
+
+All guidance is framework-agnostic. Examples use React/TypeScript where code demonstrations are helpful, but patterns apply to:
+
+- Next.js
+- SvelteKit
+- Tanstack Start
+- Any modern frontend framework
+
+## Minimum Viable Features
+
+**Mandatory for launch (core shopping flow):**
+- Navbar with cart, categories, search
+- Product listing with filtering and pagination
+- Product details with variant selection
+- Add to cart functionality
+- Cart page with item management
+- Checkout flow (shipping, payment, review)
+- Order confirmation page
+
+**Nice-to-have (add if time permits):**
+- Related products recommendations
+- Product reviews and ratings
+- Wishlist functionality
+- Image zoom on product pages
+- Bottom navigation on mobile
+- Mega-menu for navigation
+- Newsletter signup
+- Product comparison
+- Quick view modals
+
+**User-dependent (ask before implementing):**
+- Guest checkout vs login-required
+- Account dashboard features
+- Multi-language support
+- Multi-currency support
+- Live chat support
+
+## Top Ecommerce Mistakes to Avoid
+
+Before implementing, watch out for these common ecommerce-specific pitfalls:
+
+**1. Cart and Navigation Mistakes**
+- ❌ Hiding cart indicator in mobile hamburger menu (keep always visible)
+- ❌ Not showing real-time cart count updates
+- ❌ **CRITICAL: Missing `aria-live="polite"` on cart count** - Screen readers won't announce cart updates without it
+- ❌ Not displaying variant details (size, color, etc.) in cart popup - only showing product title
+- ❌ Megamenu closes when hovering over dropdown content (must stay open when hovering trigger OR dropdown)
+- ❌ **CRITICAL: Megamenu positioning errors** - Three common mistakes:
+  - ❌ Navbar doesn't have `position: relative` (megamenu won't position correctly)
+  - ❌ Megamenu positioned relative to trigger button instead of navbar (use `absolute left-0` on megamenu)
+  - ❌ Megamenu doesn't span full width (must use `right-0` or `w-full`, not just `w-auto`)
+- ❌ Hardcoding categories, featured products, or any dynamic content instead of fetching from backend
+- ❌ No clear indication of current page in category navigation
+
+**2. Product Browsing Mistakes**
+- ❌ Creating static routes for products/categories (use dynamic routes like `/products/[handle]` instead of `/products/shirt.tsx`)
+- ❌ Missing "no products found" empty state with helpful suggestions
+- ❌ No loading indicators while fetching products
+- ❌ Pagination without SEO-friendly URLs (for search engines)
+- ❌ Filter selections that don't persist on page reload
+
+**3. Product Details Mistakes**
+- ❌ Enabling "Add to Cart" before variant selection (size, color, etc.)
+- ❌ Missing product images optimization (large uncompressed images)
+- ❌ Navigating away from product page after adding to cart (stay on page)
+- ❌ Using emojis in UI instead of icons or images (unprofessional, accessibility issues)
+
+**4. Design and Consistency Mistakes**
+- ❌ **CRITICAL: Not loading `reference/design.md` before creating ANY UI component** - Leads to inconsistent colors, fonts, and styles
+- ❌ Introducing new colors without checking existing theme first
+- ❌ Adding new fonts without verifying what's already used
+- ❌ Using arbitrary Tailwind values when theme tokens exist
+- ❌ Not detecting Tailwind version (v3 vs v4) - Causes syntax errors
+
+**5. Checkout and Conversion Mistakes**
+- ❌ Requiring account creation to checkout (offer guest checkout if backend supports it)
+- ❌ Not fetching payment methods from backend - assuming available payment options or skipping payment method selection
+- ❌ Overly complex multi-step checkout (4+ steps kills conversion) - Optimal is 3 steps: Shipping Info, Delivery Method + Payment, Review
+- ❌ Missing trust signals (secure checkout badge, return policy link)
+- ❌ Not handling out-of-stock errors gracefully during checkout
+
+**6. Mobile Experience Mistakes**
+- ❌ Touch targets smaller than 44x44px (buttons, links, form fields)
+- ❌ Desktop-style hover menus on mobile (use tap/click instead)
+- ❌ Not optimizing images for mobile (loading huge desktop images)
+- ❌ Missing mobile-specific patterns (bottom nav, drawer filters)
+
+**7. Performance and SEO Mistakes**
+- ❌ Missing structured data (Product schema) for SEO
+- ❌ No explicit image lazy loading (don't assume browser defaults) - Always add `loading="lazy"` to images below the fold
+- ❌ Missing meta tags and Open Graph for social sharing
+- ❌ Not optimizing Core Web Vitals (LCP, FID, CLS) - Use [PageSpeed Insights](https://pagespeed.web.dev/) or Lighthouse to measure
+
+**8. Backend Integration Mistakes**
+- ❌ **ERROR: Writing code that calls backend APIs/SDKs without following the 5-step verification workflow** - You MUST: 1) PAUSE, 2) QUERY docs/MCP, 3) VERIFY with user, 4) Write code, 5) CHECK for type errors
+- ❌ **ERROR: Ignoring TypeScript errors on SDK methods** - Type errors mean you used wrong method names or parameters. Go back and verify with docs/MCP
+- ❌ **ERROR: Guessing API method names, SDK methods, or parameters** - Always verify exact method signatures before use
+- ❌ **ERROR: Not using Medusa MCP server when available** - If using Medusa backend, always query MCP server for methods
+- ❌ **ERROR: Copying code examples without verifying they're current** - Examples may be outdated, always verify first
+- ❌ Not detecting which backend is being used (check monorepo, ask user if unsure)
+- ❌ Assuming API structure without checking backend documentation or MCP server
+- ❌ Hardcoding dynamic content (categories, regions, products, etc.) instead of fetching from backend
+- ❌ Defining custom types for Medusa entities instead of using `@medusajs/types` package
+- ❌ Initializing Medusa SDK without publishable API key (required for multi-region stores and product pricing)
+- ❌ Fetching Medusa products without passing `region_id` query parameter (causes missing or incorrect pricing)
+- ❌ Showing all countries in Medusa checkout - should only show countries from cart's region
+- ❌ Dividing Medusa prices by 100 (Medusa stores prices as-is, not in cents like Stripe)
+- ❌ Missing Vite SSR config for Medusa SDK (add `ssr.noExternal: ['@medusajs/js-sdk']` to vite.config.ts)
+- ❌ Running Medusa storefront on port other than 8000 (causes CORS errors - Medusa backend expects port 8000 by default)
+- ❌ Not handling loading, error, and empty states for API calls
+- ❌ Making API calls on client-side that should be server-side (SEO, security)
+- ❌ Not implementing proper error messages ("Error occurred" vs "Product out of stock")
+- ❌ Missing cache invalidation (stale product data, prices, inventory)
+- ❌ **Not clearing cart state after order is placed** - Cart popup shows old items because cart wasn't reset from Context/localStorage/cache

package/resources/skills/skills/medusa/storefront-best-practices/reference/components/breadcrumbs.md

@@ -0,0 +1,123 @@
+# Breadcrumbs Component
+
+## Contents
+
+- [Overview](#overview)
+- [When to Use Breadcrumbs](#when-to-use-breadcrumbs)
+- [Ecommerce Breadcrumb Patterns](#ecommerce-breadcrumb-patterns)
+- [Mobile Breadcrumbs](#mobile-breadcrumbs)
+- [SEO Structured Data](#seo-structured-data)
+- [Checklist](#checklist)
+
+## Overview
+
+Breadcrumbs show the user's location within the site hierarchy (Home → Category → Subcategory → Product). Critical for ecommerce navigation and SEO.
+
+**Assumed knowledge**: AI agents know how to build breadcrumbs with separators and links. This guide focuses on ecommerce-specific patterns.
+
+### Key Requirements
+
+- Show full path from homepage to current page
+- Each level clickable (except current page)
+- Position below navbar, above page title
+- Include structured data for SEO (JSON-LD)
+- Mobile-optimized (back link pattern)
+
+## When to Use Breadcrumbs
+
+**Use for:**
+- Product pages (Home → Category → Subcategory → Product)
+- Category pages (Home → Category → Subcategory)
+- Deep site hierarchies (3+ levels)
+- Large catalogs with many categories
+
+**Don't use for:**
+- Homepage (no parent pages)
+- Flat site structures (1-2 levels)
+- Checkout flow (linear, not hierarchical)
+- Search results (not hierarchical)
+
+## Ecommerce Breadcrumb Patterns
+
+### Product Page Breadcrumbs
+
+**Standard pattern:**
+- Home / Category / Subcategory / Product Name
+- Example: Home / Electronics / Laptops / Gaming Laptop Pro
+
+**Key considerations:**
+- All levels except product name are clickable
+- Product name is current page (non-clickable, darker text)
+- Shows product's location in catalog
+
+**Multiple category membership:**
+- If product in multiple categories, choose primary/canonical
+- Match category in URL or navigation path
+- Be consistent across site
+
+### Category Page Breadcrumbs
+
+**Standard pattern:**
+- Home / Parent Category / Current Category
+- Example: Home / Electronics / Laptops
+
+**Current category:**
+- Non-clickable (plain text)
+- Visually distinct from links (darker or bold)
+
+### Path Construction
+
+**Hierarchy:**
+- Start with "Home" (or home icon)
+- Follow category hierarchy
+- End with current page
+- Maximum 5-6 levels (keep shallow)
+
+**URL alignment:**
+- Breadcrumb path should match URL hierarchy
+- Consistent naming between URLs and breadcrumbs
+- Example: `/categories/electronics/laptops` → "Home / Electronics / Laptops"
+
+## Mobile Breadcrumbs
+
+### Mobile Pattern: Collapse to Back Link
+
+**Recommended approach:**
+- Show only previous level as back link
+- Back arrow icon (←) + parent page name
+- Example: "← Gaming Laptops"
+
+**Why:**
+- Saves vertical space on mobile
+- Clear affordance (back navigation)
+- Simpler than full breadcrumb trail
+- Mobile users have device back button
+
+**Alternative: Truncated path**
+- Show "Home ... Current Page"
+- Hide middle levels
+- Balances space and context
+
+## SEO Structured Data
+
+**BreadcrumbList schema (CRITICAL)**: Add JSON-LD structured data. Breadcrumbs appear in search results, improves CTR, helps search engines understand site structure.
+
+**Implementation**: schema.org BreadcrumbList with items array. Each item has position (1, 2, 3...), name, and URL. See seo.md for schema details.
+
+## Checklist
+
+**Essential features:**
+
+- [ ] Positioned below navbar, above page title
+- [ ] Full path shown (Home → Category → Product)
+- [ ] All levels clickable except current page
+- [ ] Current page visually distinct (non-clickable, darker)
+- [ ] Clear separators (›, /, > or chevron)
+- [ ] Mobile: Back link pattern ("← Category")
+- [ ] Structured data (JSON-LD BreadcrumbList)
+- [ ] Semantic HTML (`<nav aria-label="Breadcrumb">`)
+- [ ] `aria-current="page"` on current item
+- [ ] Keyboard accessible (tab through links)
+- [ ] Truncate long labels (20-30 characters max)
+- [ ] Consistent with navigation labels
+- [ ] Maximum 5-6 levels deep