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:

Refer back to this skill before starting implementation
Load relevant reference files listed above for the specific component/page you're building
Follow the patterns and guidance in the reference files
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：实现导航系统
- 加载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

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]

/products/$handle

, NOT

/products/shirt.tsx

Category pages: Use dynamic routes like

/categories/[handle]

/categories/$handle

, NOT

/categories/women.tsx

Framework-specific patterns:

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
```

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:

User preferences - Read
```
design.md
```
to discover design style preferences
Brand identity - Colors, typography, tone that match the brand
Target audience - B2C vs B2B, demographics, device usage
Product type - Fashion vs electronics vs groceries affect layout choices
Business requirements - Multi-currency, multi-language, region-specific
Backend system - API structure affects component implementation

实施前请考虑：

用户偏好 - 阅读
```
design.md
```
了解设计风格偏好
品牌标识 - 与品牌匹配的颜色、排版、语气
目标受众 - B2C vs B2B、人口统计、设备使用情况
产品类型 - 时尚、电子、杂货等产品类型会影响布局选择
业务需求 - 多货币、多语言、区域特定需求
后端系统 - 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/缓存中重置购物车