构建电商店面（结账/购物车/商品页/导航）时的最佳实践与后端…

在开发任何电商店面组件（结账、购物车、商品页、商品列表、导航、首页等）时，提供 UI/UX、SEO、移动端、后端集成与常见错误的完整实施规范。

适用场景

解决思路

1. 在开始任何 UI 组件前，先加载 reference/design.md，发现已有的设计令牌（颜色、字体、间距、模式），避免引入不一致样式。
2. 根据任务加载对应参考文件：新店面加载 design.md；连接后端加载 connecting-to-backend.md；连接 Medusa 加载 medusa.md；首页加载 navbar.md、hero.md、footer.md、home-page.md；导航加载 navbar.md（可选 megamenu.md）；商品列表加载 product-listing.md；商品详情加载 product-details.md；结账加载 checkout.md；SEO 加载 seo.md；移动端加载 mobile-responsiveness.md。最低要求：实现前至少加载 1-2 个与任务相关的参考文件。
3. 制定实施计划时，为每个组件/页面/功能列出：1) 回看本技能；2) 加载对应参考文件；3) 遵循其中的模式与指南；4) 检查常见错误章节以规避已知陷阱。
4. 无障碍：购物车数量更新必须加 aria-live="polite"，否则屏幕阅读器不会播报；确保所有购物车/结账交互支持键盘导航。
5. 移动端：粘性底部元素必须使用 env(safe-area-inset-bottom)，否则 iOS home indicator 会遮挡购买按钮；购物车操作、变体选择器、数量按钮的触摸目标最小 44px。
6. 性能：首屏以下的商品图片必须显式加 loading="lazy"，不要依赖浏览器默认；为移动端优化商品图片（<500KB），因为大多数电商流量来自移动端。
7. 转化优化：购物流程中保持清晰 CTA；结账尽量减少摩擦（如后端支持则提供游客结账）；在购买按钮附近放置信任信号（评价、安全徽章、退货政策）；提前清晰展示价格与运费信息。
8. SEO：必须添加 Product schema（JSON-LD），这对 Google Shopping 和富摘要至关重要；用 PageSpeed Insights 测量 Core Web Vitals。
9. 视觉设计：店面 UI 中绝不使用 emoji，改用图标或图片（不专业且有可访问性问题）。
10. 后端集成：检测后端——若在 monorepo 中检查后端目录，不确定时询问用户使用哪个后端；绝不硬编码动态内容（分类、区域、商品、配送选项等必须从后端获取）；不要假设 API 结构，验证端点与数据格式。
11. 后端 SDK 方法验证工作流（写代码前必须严格执行）：Step 1 暂停，先不要写代码；Step 2 查询文档或 MCP server（如 medusa MCP），找到确切方法名、参数、返回类型；Step 3 向用户说明并展示你查到的内容，确认方法签名与参数；Step 4 才写代码，使用验证过的签名；Step 5 写完后检查 TypeScript 错误，若 SDK 方法报类型错误说明方法名或参数错误，回到 Step 2。
12. 禁止行为：未查询文档/MCP 就写调用后端 API/SDK 的代码；猜测方法名或参数；忽略 SDK 方法上的 TypeScript 错误；未经验证直接复制本技能中的示例（可能过时）；假设 SDK 方法与 REST 端点一致。
13. Medusa 专属：价格按原样显示，不要除以 100（与 Stripe 不同，Medusa 以展示格式存储价格）；推荐配置 Medusa MCP server（https://docs.medusajs.com/mcp）；加载 reference/medusa.md 了解区域、定价等模式。
14. 路由：商品与分类必须使用动态路由，绝不为单个条目创建静态页面。商品页用 /products/[handle] 或 /products/$handle，而非 /products/shirt.tsx；分类页用 /categories/[handle] 或 /categories/$handle，而非 /categories/women.tsx。框架对应：Next.js App Router 用 app/products/[handle]/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。
15. 模式选择：结账策略（单页 vs 多步）加载 checkout.md；导航策略（下拉 vs megamenu）加载 navbar.md 与 megamenu.md；商品列表策略（分页 vs 无限滚动 vs 加载更多）加载 product-listing.md；搜索策略加载 search.md；移动 vs 桌面优先级加载 mobile-responsiveness.md；变体选择加载 product-details.md；购物车模式加载 cart-popup.md 与 cart.md；信任信号策略加载 product-details.md 与 checkout.md。
16. 新店面实施顺序：1) 发现阶段读 design.md；2) 基础设置读 connecting-to-backend.md（或 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 审计与移动端测试。
17. 购物流程模式：浏览（home-page.md → product-listing.md）→ 查看（product-details.md + product-reviews.md）→ 购物车（cart-popup.md → cart.md）→ 结账（checkout.md → order-confirmation.md）。
18. 实现前考虑：用户偏好（读 design.md）、品牌识别（颜色/字体/语气）、目标受众（B2C vs B2B、人群、设备）、商品类型（时尚 vs 电子 vs 杂货影响布局）、业务需求（多币种、多语言、区域特定）、后端系统（API 结构影响组件实现）。
19. 最小可行功能（上线必备）：带购物车、分类、搜索的导航栏；带筛选与分页的商品列表；带变体选择的商品详情；加入购物车功能；可管理商品的购物车页；结账流程（配送、支付、复核）；订单确认页。
20. 锦上添花功能：相关商品推荐、商品评价与评分、心愿单、商品页图片缩放、移动端底部导航、mega-menu、邮件订阅、商品对比、快速查看弹窗。
21. 需询问用户后再实现：游客结账 vs 必须登录、账户仪表盘功能、多语言、多币种、在线客服。
22. 避免购物车与导航错误：不要把购物车指示器藏在移动端汉堡菜单里（应始终可见）；要显示实时购物车数量更新；购物车数量必须加 aria-live="polite"；购物车弹窗要显示变体详情（尺寸、颜色等）而非仅商品标题；megamenu 在悬停触发区或下拉内容时都必须保持打开；megamenu 定位三要点：navbar 必须有 position: relative，megamenu 相对 navbar 定位（用 absolute left-0）而非相对触发按钮，megamenu 必须全宽（用 right-0 或 w-full，而非仅 w-auto）；不要硬编码分类、精选商品等动态内容；分类导航中要清晰指示当前页面。
23. 避免商品浏览错误：不要为商品/分类创建静态路由（用 /products/[handle] 而非 /products/shirt.tsx）；要有带建议的"未找到商品"空状态；要有加载指示器；分页要有 SEO 友好 URL；筛选选择要在页面刷新后保持。
24. 避免商品详情错误：变体未选择前不要启用"加入购物车"；要优化商品图片（避免大未压缩图）；加入购物车后不要离开商品页（留在原页）；UI 中用图标或图片而非 emoji。
25. 避免设计与一致性错误：创建任何 UI 组件前必须加载 reference/design.md；引入新颜色前先检查现有主题；添加新字体前先确认已用字体；有主题令牌时不要用任意 Tailwind 值；检测 Tailwind 版本（v3 vs v4）以免语法错误。
26. 避免结账与转化错误：不要强制注册才能结账（后端支持则提供游客结账）；必须从后端获取支付方式，不要假设或跳过支付方式选择；多步结账不要超过 3 步（配送信息、配送方式+支付、复核）；要有信任信号（安全结账徽章、退货政策链接）；要优雅处理结账时的缺货错误。
27. 避免移动端错误：触摸目标不要小于 44x44px；移动端不要用桌面式悬停菜单（用点击）；为移动端优化图片；要有移动端专属模式（底部导航、抽屉筛选）。
28. 避免性能与 SEO 错误：不要缺结构化数据（Product schema）；首屏以下图片必须显式加 loading="lazy"；要有 meta 标签与 Open Graph；要优化 Core Web Vitals（LCP、FID、CLS），用 PageSpeed Insights 或 Lighthouse 测量。
29. 避免后端集成错误：不要未走 5 步验证工作流就写调用后端 API/SDK 的代码；不要忽略 SDK 方法上的 TypeScript 错误；不要猜测 API/SDK 方法名或参数；有 Medusa MCP server 时不要不用；不要未经验证就复制代码示例；要检测使用哪个后端；不要假设 API 结构；不要硬编码动态内容；不要为 Medusa 实体自定义类型（用 @medusajs/types）；初始化 Medusa SDK 必须带 publishable API key；获取 Medusa 商品必须传 region_id 查询参数；Medusa 结账只显示购物车区域内的国家；不要将 Medusa 价格除以 100；Vite 需为 Medusa SDK 加 SSR 配置（vite.config.ts 中 ssr.noExternal: ['@medusajs/js-sdk']）；Medusa 店面不要跑在 8000 以外端口（会 CORS 错误）；要处理 API 调用的加载、错误、空状态；该服务端发起的 API 调用不要放客户端（SEO、安全）；要有具体错误信息（"商品缺货"而非"发生错误"）；要有缓存失效（避免陈旧商品数据、价格、库存）；下单后必须清空购物车状态（Context/localStorage/缓存），否则购物车弹窗仍显示旧商品。

适用边界 · 注意事项

• 非电商店面项目（普通网站、后台管理系统、非购物类应用）不适用。
• 不使用 Medusa 或其他电商后端、纯静态展示页面时，后端集成与 Medusa 专属部分不适用。
• 仅做与购物流程无关的纯设计系统或纯 SEO 通用优化时，无需加载全部参考文件。