Back to Details

storefront-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
本指南全面介绍了构建现代、高转化率电商店面的方法，涵盖UI/UX模式、组件设计、布局结构、SEO优化和移动端适配。

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"
在处理任何店面任务时，请务必加载本技能：
  • 添加结账页面/流程 - 支付、配送、下单
  • 实现购物车 - 购物车页面、购物车弹窗、加入购物车功能
  • 构建产品页面 - 产品详情、产品列表、产品网格
  • 创建导航系统 - 导航栏、巨型菜单、页脚、移动端菜单
  • 集成Medusa后端 - SDK设置、购物车、产品、支付
  • 任何店面组件 - 首页、搜索、筛选、账户页面
  • 从零开始构建新的电商店面
  • 优化现有购物体验和转化率
  • 针对易用性、可访问性和SEO进行优化
  • 设计适配移动端的电商体验
应触发本技能的示例提示：
  • "添加结账页面"
  • "实现购物车"
  • "创建产品列表页面"
  • "连接到Medusa后端"
  • "添加导航菜单"
  • "为商店构建首页"

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.
⚠️ 在创建任何UI组件之前，请务必先加载
reference/design.md
  • 了解现有设计令牌（颜色、字体、间距、模式）
  • 避免引入不一致的样式
  • 为保持品牌一致性提供指导
  • 每个组件都需要，不仅限于新店面
根据你要实现的功能加载以下参考文件：
  • 启动新店面？ → 必须先加载
    reference/design.md
    以了解用户偏好
  • 连接到后端API？ → 必须先加载
    reference/connecting-to-backend.md
  • 连接到Medusa后端？ → 必须加载
    reference/medusa.md
    以获取SDK设置、定价、区域和Medusa相关模式
  • 实现首页？ → 必须加载
    reference/components/navbar.md
    、
    reference/components/hero.md
    、
    reference/components/footer.md
    和
    reference/layouts/home-page.md
  • 实现导航系统？ → 必须加载
    reference/components/navbar.md
    ，可选加载
    reference/components/megamenu.md
  • 构建产品列表？ → 必须先加载
    reference/layouts/product-listing.md
  • 构建产品详情？ → 必须先加载
    reference/layouts/product-details.md
  • 实现结账流程？ → 必须先加载
    reference/layouts/checkout.md
  • 优化SEO？ → 必须先加载
    reference/seo.md
  • 优化移动端体验？ → 必须先加载
    reference/mobile-responsiveness.md
最低要求： 在实现之前，至少加载1-2个与具体任务相关的参考文件

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
重要提示：如果你要创建店面功能的实施计划，请在计划中包含以下内容：
在计划中实现每个组件、页面、布局或功能时：
  1. 开始实施前，请回顾本技能
  2. 加载上述列出的与该组件/页面相关的参考文件
  3. 遵循参考文件中的模式和指导
  4. 查看常见错误部分，避免已知陷阱
计划结构示例：
任务1：实现导航系统
- 加载reference/components/navbar.md
- 遵循navbar.md中的模式（动态分类获取、购物车可见性等）
- 参考本技能中的常见错误（例如，硬编码分类）

任务2：实现产品列表页面
- 加载reference/layouts/product-listing.md
- 遵循product-listing.md中的分页/筛选模式
- 使用reference/components/product-card.md实现产品网格项
- 参考本技能中的后端集成指导

任务3：实现结账流程
- 加载reference/layouts/checkout.md
- 加载reference/medusa.md以获取Medusa支付集成指导
- 遵循组件架构建议（拆分步骤组件）
- 参考本技能中的支付方式获取要求
为什么这很重要：
  • 计划提供高层策略
  • 参考文件提供详细的实施模式
  • 技能文件包含需要避免的关键错误
  • 遵循此工作流可确保一致性和最佳实践

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
  • 重要提示：购物车数量更新必须使用
    aria-live="polite"
     - 没有它，屏幕阅读器无法播报更新
  • 确保所有购物车/结账交互支持键盘导航

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
  • 粘性底部元素必须使用
    env(safe-area-inset-bottom)
     - 否则iOS主屏幕指示器会遮挡购买按钮
  • 购物车操作、变体选择器、数量按钮的最小触摸目标为44px

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
  • 对于首屏下方的产品图片，请务必添加
    loading="lazy"
     - 不要依赖浏览器默认设置
  • 针对移动端优化产品图片（小于500KB）- 大多数电商流量来自移动端

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
  • 购物流程中使用清晰的CTA
  • 结账流程尽可能减少摩擦（如果支持，提供访客结账）
  • 购买按钮附近添加信任标识（评价、安全徽章、退货政策）
  • 提前显示清晰的定价和配送信息

SEO

SEO

  • Product schema (JSON-LD) required - Critical for Google Shopping and rich snippets
  • Use PageSpeed Insights to measure Core Web Vitals
  • 必须添加产品Schema（JSON-LD） - 对Google Shopping和富文本摘要至关重要
  • 使用PageSpeed Insights衡量Core Web Vitals

Visual Design

视觉设计

  • NEVER use emojis in storefront UI - Use icons or images instead (unprofessional, accessibility issues)
  • 店面UI中切勿使用表情符号 - 改用图标或图片（不专业，存在可访问性问题）

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
  • 后端检测：如果是单仓库，检查是否有后端目录。如果不确定，请询问用户使用的是哪个后端
  • 切勿硬编码动态内容：分类、区域、产品、配送选项等内容应始终从后端获取 - 这些内容经常变化
  • 不要假设API结构 - 验证端点和数据格式

⚠️ CRITICAL: Backend SDK Method Verification Workflow

⚠️ 重要提示：后端SDK方法验证工作流

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.)
在编写连接到后端的代码之前，请务必遵循此精确工作流：
步骤1：暂停 - 不要编写代码
  • 你即将编写调用后端API或SDK方法的代码（例如，Medusa SDK、REST API、GraphQL）
  • 停止 - 未经验证不要继续编码
步骤2：查询文档或MCP服务器
  • 如果MCP服务器可用：查询确切的方法（例如，medusa MCP）
  • 如果没有MCP服务器：搜索官方文档
  • 查找：确切的方法名称、参数、返回类型
步骤3：验证你找到的内容
  • 向用户明确说明：“我需要验证[操作]的正确方法。让我检查[MCP服务器/文档]。”
  • 向用户展示你找到的内容：“根据[来源]，方法是
    sdk.store.cart.methodName(params)
    ”
  • 确认方法签名和参数
步骤4：只有此时才能编写代码
  • 现在你可以使用已验证的方法编写代码
  • 使用你找到的确切签名
步骤5：检查TypeScript错误
  • 编写代码后，检查与SDK相关的任何TypeScript/类型错误
  • 如果SDK方法出现类型错误，说明你使用了错误的方法名称或参数
  • 类型错误表明你验证不正确 - 返回步骤2
这不是可选的 - 这是强制性的错误预防措施
以下行为属于严重错误：
  • ❌ 未明确查询文档/MCP就编写调用后端API/SDK的代码
  • ❌ 猜测方法名称或参数
  • ❌ 忽略SDK方法的TypeScript错误（错误表明方法使用不正确）
  • ❌ 未经验证就复制本技能中的示例（示例可能已过时）
  • ❌ 假设SDK方法与REST API端点匹配
对于Medusa的特别说明：
  • Medusa定价：按原样显示价格 - 不要除以100（与Stripe不同，Medusa以显示格式存储价格）
  • Medusa MCP服务器：https://docs.medusajs.com/mcp - 如果未安装，建议设置
  • 加载
    reference/medusa.md
    获取Medusa专属模式（区域、定价等）

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)
  • 务必使用动态路由处理产品和分类 - 切勿为单个商品创建静态页面
  • 产品页面：使用
    /products/[handle]
    或
    /products/$handle
    等动态路由，而不是
    /products/shirt.tsx
  • 分类页面：使用
    /categories/[handle]
    或
    /categories/$handle
    等动态路由，而不是
    /categories/women.tsx
  • 框架专属模式：
    • Next.js App Router：
      app/products/[handle]/page.tsx
      或
      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
  • 原因：动态路由可扩展到任意数量的产品/分类，无需创建单个文件
  • 静态路由难以维护且无法扩展（想象创建1000个产品文件）

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.
当你需要在多种实施模式中选择时，请加载相关参考文件：
  • 结账策略（单页 vs 多步骤）→ 加载
    reference/layouts/checkout.md
  • 导航策略（下拉菜单 vs 巨型菜单）→ 加载
    reference/components/navbar.md
    和
    reference/components/megamenu.md
  • 产品列表策略（分页 vs 无限滚动 vs 加载更多）→ 加载
    reference/layouts/product-listing.md
  • 搜索策略（自动完成 vs 筛选 vs 自然语言）→ 加载
    reference/components/search.md
  • 移动端 vs 桌面端优先级→ 加载
    reference/mobile-responsiveness.md
  • 变体选择（文本 vs 色板 vs 配置器）→ 加载
    reference/layouts/product-details.md
  • 购物车模式（弹窗 vs 抽屉式 vs 页面导航）→ 加载
    reference/components/cart-popup.md
    和
    reference/layouts/cart.md
  • 信任标识策略→ 加载
    reference/layouts/product-details.md
    和
    reference/layouts/checkout.md
每个参考文件都包含决策框架和具体标准，帮助你根据上下文选择正确的模式。

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
reference/connecting-to-backend.md    - 框架检测、API设置、后端集成模式
reference/medusa.md                    - Medusa SDK集成、定价、区域、TypeScript类型
reference/design.md                    - 用户偏好、品牌标识、设计系统
reference/seo.md                       - 元标签、结构化数据、Core Web Vitals
reference/mobile-responsiveness.md     - 移动端优先设计、响应式断点、触摸交互

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
reference/components/navbar.md         - 桌面端/移动端导航、Logo、菜单、购物车图标、所有页面都需加载
reference/components/megamenu.md       - 分类组织、特色产品、移动端替代方案
reference/components/cart-popup.md     - 加入购物车反馈、迷你购物车显示
reference/components/country-selector.md - 国家/地区选择、货币、定价、Medusa区域
reference/components/breadcrumbs.md    - 分类层级、结构化数据标记
reference/components/search.md         - 搜索输入、自动完成、结果、筛选
reference/components/product-reviews.md - 评价显示、评分汇总、提交
reference/components/hero.md           - 首页横幅布局、CTA位置、图片优化
reference/components/popups.md         - 新闻通讯订阅、折扣弹窗、退出意图弹窗
reference/components/footer.md         - 内容组织、导航、社交媒体、所有页面都需加载
reference/components/product-card.md   - 产品图片、定价、加入购物车、徽章
reference/components/product-slider.md - 轮播实现、移动端滑动、可访问性

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
reference/layouts/home-page.md         - 首页横幅、特色分类、产品列表
reference/layouts/product-listing.md   - 网格/列表视图、筛选、排序、分页
reference/layouts/product-details.md   - 图片画廊、变体选择、相关产品
reference/layouts/cart.md              - 购物车商品、数量更新、优惠码
reference/layouts/checkout.md          - 多步骤/单页、地址表单、支付
reference/layouts/order-confirmation.md - 订单号、摘要、配送信息
reference/layouts/account.md           - 仪表盘、订单历史、地址簿
reference/layouts/static-pages.md      - FAQ、关于我们、联系我们、配送/退货政策

Features

功能

reference/features/wishlist.md         - Add to wishlist, wishlist page, move to cart
reference/features/promotions.md       - Promotional banners, discount codes, sale badges
reference/features/wishlist.md         - 加入收藏夹、收藏夹页面、移至购物车
reference/features/promotions.md       - 促销横幅、折扣码、促销徽章

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.
重要提示：对于以下每个步骤，请在实施前加载参考文件。
1. 发现阶段 → 阅读design.md了解用户偏好
2. 基础设置 → 阅读connecting-to-backend.md（Medusa后端请阅读medusa.md）、mobile-responsiveness.md、seo.md
3. 核心组件 → 实现navbar.md、footer.md
4. 首页 → 阅读home-page.md
5. 产品浏览 → 阅读product-listing.md、product-card.md、search.md
6. 产品详情 → 阅读product-details.md、product-reviews.md
7. 购物车与结账 → 阅读cart-popup.md、cart.md、checkout.md、order-confirmation.md
8. 用户账户 → 阅读account.md
9. 附加功能 → 阅读wishlist.md、promotions.md
10. 优化 → SEO审计（seo.md）、移动端测试（mobile-responsiveness.md）
即使你创建了实施计划，在实施每个步骤时也要回顾本技能并加载相关参考文件。

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
浏览 → 查看 → 购物车 → 结账

浏览:   home-page.md → product-listing.md
查看:     product-details.md + product-reviews.md
购物车:     cart-popup.md → cart.md
结账: 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
产品网格和筛选 → 
product-listing.md
和
product-card.md
产品卡片 → 
product-card.md
导航系统 → 
navbar.md
和
megamenu.md
搜索功能 → 
search.md
结账流程 → 
checkout.md
促销和销售 → 
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
实施前请考虑：
  1. 用户偏好 - 阅读
    design.md
    了解设计风格偏好
  2. 品牌标识 - 与品牌匹配的颜色、排版、语气
  3. 目标受众 - B2C vs B2B、人口统计、设备使用情况
  4. 产品类型 - 时尚、电子、杂货等产品类型会影响布局选择
  5. 业务需求 - 多货币、多语言、区域特定需求
  6. 后端系统 - API结构会影响组件实现

Integration with Medusa

与Medusa集成

Medusa 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
.
Medusa是一个现代、灵活的电商后端。在以下场景中考虑使用Medusa：
  • 构建新的电商店面
  • 需要无头电商解决方案
  • 想要内置多区域、多货币支持
  • 需要强大的促销和折扣引擎
  • 需要灵活的产品建模
有关详细的Medusa集成指导，请查看
reference/medusa.md
。有关通用后端模式，请查看
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
所有指导都是框架无关的。在需要演示代码时，示例使用React/TypeScript，但模式适用于：
  • Next.js
  • SvelteKit
  • Tanstack Start
  • 任何现代前端框架

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
上线必备（核心购物流程）：
  • 包含购物车、分类、搜索的导航栏
  • 带筛选和分页的产品列表
  • 带变体选择的产品详情
  • 加入购物车功能
  • 带商品管理的购物车页面
  • 结账流程（配送、支付、确认）
  • 订单确认页面
锦上添花（如有时间可添加）：
  • 相关产品推荐
  • 产品评价和评分
  • 收藏夹功能
  • 产品页面图片缩放
  • 移动端底部导航
  • 巨型导航菜单
  • 新闻通讯订阅
  • 产品对比
  • 快速查看模态框
取决于用户（实施前询问）：
  • 访客结账 vs 强制登录
  • 账户仪表盘功能
  • 多语言支持
  • 多货币支持
  • 在线客服支持

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 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
实施前，请注意这些常见的电商专属陷阱：
1. 购物车和导航错误
  • ❌ 移动端汉堡菜单中隐藏购物车指示器（始终保持可见）
  • ❌ 不显示实时购物车数量更新
  • ❌ 重要提示：购物车数量缺少
    aria-live="polite"
     - 没有它，屏幕阅读器无法播报购物车更新
  • ❌ 购物车弹窗中不显示变体详情（尺寸、颜色等）- 仅显示产品标题
  • ❌ 巨型菜单在悬停下拉内容时关闭（悬停触发器或下拉内容时必须保持打开）
  • ❌ 重要提示：巨型菜单定位错误 - 三个常见错误：
    • ❌ 导航栏没有
      position: relative
      （巨型菜单无法正确定位）
    • ❌ 巨型菜单相对于触发按钮定位，而非导航栏（巨型菜单使用
      absolute left-0
      ）
    • ❌ 巨型菜单未占满宽度（必须使用
      right-0
      或
      w-full
      ，而不仅仅是
      w-auto
      ）
  • ❌ 硬编码分类、特色产品或任何动态内容，而非从后端获取
  • ❌ 分类导航中没有明确标记当前页面
2. 产品浏览错误
  • ❌ 为产品/分类创建静态路由（使用
    /products/[handle]
    等动态路由，而非
    /products/shirt.tsx
    ）
  • ❌ 缺少“未找到产品”的空状态提示和有用建议
  • ❌ 获取产品时没有加载指示器
  • ❌ 分页使用对SEO不友好的URL（针对搜索引擎）
  • ❌ 筛选选择在页面刷新后不保留
3. 产品详情错误
  • ❌ 未选择变体（尺寸、颜色等）就启用“加入购物车”
  • ❌ 未优化产品图片（大尺寸未压缩图片）
  • ❌ 加入购物车后离开产品页面（留在当前页面）
  • ❌ UI中使用表情符号而非图标或图片（不专业，存在可访问性问题）
4. 设计和一致性错误
  • ❌ 重要提示：创建任何UI组件前未加载
    reference/design.md
     - 导致颜色、字体和样式不一致
  • ❌ 未检查现有主题就引入新颜色
  • ❌ 未验证已使用的字体就添加新字体
  • ❌ 存在主题令牌时使用任意Tailwind值
  • ❌ 未检测Tailwind版本（v3 vs v4）- 导致语法错误
5. 结账和转化率错误
  • ❌ 结账要求创建账户（如果后端支持，提供访客结账）
  • ❌ 未从后端获取支付方式 - 假设可用支付选项或跳过支付方式选择
  • ❌ 结账流程过于复杂（4个以上步骤会降低转化率）- 最佳为3步：配送信息、配送方式+支付、确认
  • ❌ 缺少信任标识（安全结账徽章、退货政策链接）
  • ❌ 结账时未优雅处理缺货错误
6. 移动端体验错误
  • ❌ 触摸目标小于44x44px（按钮、链接、表单字段）
  • ❌ 移动端使用桌面端悬停菜单（改用点击/触摸）
  • ❌ 未针对移动端优化图片（加载大尺寸桌面端图片）
  • ❌ 缺少移动端专属模式（底部导航、抽屉式筛选）
7. 性能和SEO错误
  • ❌ 缺少产品结构化数据（Schema）- 对SEO至关重要
  • ❌ 未显式设置图片懒加载（不要依赖浏览器默认）- 首屏下方的图片务必添加
    loading="lazy"
  • ❌ 缺少元标签和Open Graph用于社交分享
  • ❌ 未优化Core Web Vitals（LCP、FID、CLS）- 使用PageSpeed Insights或Lighthouse衡量
8. 后端集成错误
  • ❌ 错误：未遵循5步验证工作流就编写连接后端的代码 - 你必须：1) 暂停，2) 查询文档/MCP，3) 与用户确认，4) 编写代码，5) 检查类型错误
  • ❌ 错误：忽略SDK方法的TypeScript错误 - 类型错误意味着你使用了错误的方法名称或参数。返回步骤重新验证
  • ❌ 错误：猜测API方法名称、SDK方法或参数 - 使用前务必验证确切的方法签名
  • ❌ 错误：可用时未使用Medusa MCP服务器 - 如果使用Medusa后端，务必查询MCP服务器获取方法
  • ❌ 错误：未验证就复制代码示例 - 示例可能已过时，务必先验证
  • ❌ 未检测使用的后端（检查单仓库，不确定时询问用户）
  • ❌ 未检查后端文档或MCP服务器就假设API结构
  • ❌ 硬编码动态内容（分类、区域、产品等）而非从后端获取
  • ❌ 为Medusa实体定义自定义类型而非使用
    @medusajs/types
    包
  • ❌ 未使用可发布API密钥初始化Medusa SDK（多区域商店和产品定价需要）
  • ❌ 获取Medusa产品时未传递
    region_id
    查询参数（导致定价缺失或错误）
  • ❌ Medusa结账中显示所有国家 - 应仅显示购物车区域中的国家
  • ❌ 将Medusa价格除以100（Medusa按原样存储价格，不像Stripe以分为单位）
  • ❌ Medusa SDK缺少Vite SSR配置（在vite.config.ts中添加
    ssr.noExternal: ['@medusajs/js-sdk']
    ）
  • ❌ Medusa店面运行在非8000端口（导致CORS错误 - Medusa后端默认期望8000端口）
  • ❌ API调用未处理加载、错误和空状态
  • ❌ 本应在服务端进行的API调用在客户端执行（影响SEO和安全性）
  • ❌ 未实现适当的错误消息（“发生错误” vs “产品缺货”）
  • ❌ 缺少缓存失效（产品数据、价格、库存过时）
  • ❌ 订单完成后未清除购物车状态 - 购物车弹窗显示旧商品，因为未从Context/localStorage/缓存中重置购物车