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"、針對 iOS 固定按鈕使用 env(safe-area-inset-bottom)、最小 44px 觸控目標、在折疊線以下的商品圖片強制使用 loading="lazy"，以及禁止在店面 UI 中使用表情符號。

為 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 結構化資料、meta 標籤、Open Graph，以及透過 PageSpeed Insights 進行 Core Web Vitals 測量。