Storefront Best Practices

• 构建或扩展电商店面 — 任何框架（Next.js、SvelteKit、TanStack Start、React、Vue）：产品页面、产品列表、购物车、结账、导航、首页、搜索、账户页面或订单确认。
• 集成后端（包括 Medusa） — SDK 配置、获取产品/分类/地区、价格展示、支付方式选择以及购物车管理。
• 优化现有店面 — 提升转化率、修复移动端体验问题、添加 SEO 结构化数据，或改善购物流程中的无障碍访问体验。
• 规划店面实施方案 — 生成分步构建计划，该计划引用正确的参考文件，并在编写任何代码之前规避已知的常见问题。

• 非电商项目 — 管理后台、SaaS 应用、博客或任何不含购物/购买流程的网站，均无需使用本技能的相关模式。
• 纯后端或 API 工作 — 如果您仅负责服务端的商业逻辑，不涉及任何前端店面组件，本技能所能提供的价值十分有限。

在编写任何调用后端 API 或 SDK 的代码之前，该技能强制执行一套 5 步工作流：暂停、查询文档或 MCP 服务器、与用户确认方法、编写代码，然后检查 TypeScript 错误。这可以有效防止方法名称猜测错误、示例过时以及无提示的运行时故障。

该技能将每一项店面任务——结账、商品列表、导航、SEO、移动端、Medusa 集成等——映射到特定的参考文件（例如 reference/layouts/checkout.md、reference/medusa.md）。它明确指定在实现每项功能之前需要加载哪些文件，从而确保模式得到一致应用。

涵盖店面特有的高影响力规则：在购物车数量上使用 aria-live="polite" 以支持屏幕阅读器，使用 env(safe-area-inset-bottom) 处理 iOS 粘性按钮，最小 44px 触控目标，对首屏以下的商品图片强制使用 loading="lazy"，以及禁止在店面 UI 中使用 emoji。

为 Next.js（App Router 和 Pages Router）、SvelteKit、TanStack Start 以及 Remix 提供正确的动态路由模式，适用于产品页面和分类页面。明确警告不应使用无法扩展的静态单条目路由。

涵盖 Medusa SDK 初始化（需要可发布的 API 密钥）、正确的价格显示方式（无需除以 100）、获取产品时 region_id 的必要性、CORS 端口约定（8000）、Vite SSR 配置、使用 @medusajs/types 替代自定义类型，以及下单后清除购物车状态。

一份分类整理的清单，涵盖超过 30 个命名反模式，涉及购物车/导航、商品浏览、结账流程、移动端、SEO、性能、设计一致性以及后端集成等多个方面——每个条目均以具体的 ❌ 规则形式呈现，供实施前及实施过程中逐项核查。

该技能提供一个10步顺序工作流，从发现阶段（加载 design.md）开始，依次覆盖基础架构、核心组件、购物流程和优化环节。每个步骤均明确指定在实施前需加载的文件，确保不遗漏任何内容，并保持风格的一致性。

指导结账架构决策（单页式与多步骤式），强制要求从后端获取支付方式而非硬编码，标记访客结账需求，并通过 reference/layouts/checkout.md 和 reference/medusa.md 提供 Medusa 专属的支付集成步骤。

涵盖 SDK 配置、区域与定价模式、使用 region_id 获取产品、限定于购物车区域的国家列表、Vite SSR 配置，以及使用 Medusa MCP 服务器进行方法验证——有效预防最常见的 Medusa 店面集成错误。

指引开发者参阅 reference/mobile-responsiveness.md，了解触控目标尺寸、安全区域插边以及图像优化相关内容；并参阅 reference/seo.md，了解产品 JSON-LD 结构化数据、元标签、Open Graph 以及通过 PageSpeed Insights 衡量核心网页指标（Core Web Vitals）的相关内容。